> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Ingestion API - Pemantauan Non-Moneter

> Kirim aktivitas non-moneter seperti login, gameplay, bonus, pembayaran, sengketa, dan keamanan akun ke mesin yang sama dengan penilaian transaksi Anda.

Transaksi adalah uang. Event adalah segala hal lain yang diketahui platform Anda: login yang mendahului penarikan, tangan yang memindahkan chip antara dua akun, bonus yang diklaim dua kali, chargeback yang tiba seminggu kemudian.

Event menggunakan satu envelope untuk setiap kategori, bersifat idempoten secara desain, dan dievaluasi oleh [mesin aturan yang sama](https://docs.didit.me/id/transaction-monitoring/event-rules.md) yang menilai [transaksi](https://docs.didit.me/id/transaction-monitoring/transactions.md) Anda.

> [!NOTE]
>
> Ingesti event bersifat **opt-in**. Aktifkan di **Transactions → Settings → Event monitoring**.
> Sampai Anda mengaktifkannya, tidak ada yang berubah: aturan transaksi yang sudah ada tetap hanya berjalan pada transaksi, dan aturan event tidak bisa dibuat secara tidak sengaja, karena aturan berlaku untuk transaksi kecuali Anda secara eksplisit menyertakan event.
>
> Selama belum aktif, setiap jalur penulisan - `POST /v3/events/`, `POST /v3/events/batch/`, `POST /v3/events/sdk-token/`, dan jalur perangkat `/v1/events/` - merespons `403` dengan `{"code": "event_monitoring_disabled"}`, dan tidak ada yang disimpan, diperkaya, atau dievaluasi. Operasi baca tidak terpengaruh.

## Endpoint

| Endpoint | Autentikasi | Gunakan untuk |
| - | - | - |
| `POST /v3/events/` | kunci API | Satu event dari backend Anda |
| `POST /v3/events/batch/` | kunci API | Hingga 500 event dalam satu permintaan |
| `POST /v3/events/sdk-token/` | kunci API | Membuat kredensial perangkat dengan cakupan terbatas |
| `POST /v1/events/` | `X-Monitoring-Token` | Satu event dari SDK perangkat |
| `POST /v1/events/batch/` | `X-Monitoring-Token` | Buffer SDK yang dikirimkan |
| `GET /v3/events/` | kunci API | Menampilkan dan memfilter event |
| `GET /v3/events/{event_uuid}/` | kunci API | Satu event beserta bukti aturannya |
| `GET /v3/events/subjects/{vendor_data}/` | kunci API | Linimasa satu subjek (lihat `entity_type` di bawah) |
| `GET /v3/events/enrichment-metrics/` | kunci API | Kesehatan cache pengayaan IP |

Jalur `/v3/` adalah jalur server dan menggunakan autentikasi `x-api-key` yang sama dengan bagian lain dari API transaksi. Jalur `/v1/events/` adalah jalur perangkat - lihat [Pengiriman event SDK](https://docs.didit.me/id/transaction-monitoring/sdk-event-submission.md).

## Envelope

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'
```

```json theme={null}
{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}
```

| Kolom | Wajib | Catatan |
| - | - | - |
| `event_id` | ya | Pengidentifikasi Anda sendiri, unik per aplikasi. Ini adalah kunci idempotensi. |
| `event_category` | ya | Salah satu dari sepuluh kategori di bawah. |
| `action_type` | ya | String terbuka, hingga 128 karakter. |
| `occurred_at` | ya | Waktu kejadian di sisi Anda. Hingga 7 hari di masa lalu, 5 menit di masa depan. |
| `subject.vendor_data` | ya | ID pengguna Anda. Dipetakan ke Pengguna yang sama dengan yang akan dipetakan oleh transaksi. |
| `subject.entity_type` | tidak | `individual` (default) atau `company`. |
| `business.vendor_data` | tidak | Bisnis yang terkait dengan event tersebut. |
| `session` | tidak | `session_id`, `sequence`, `page_url`, `referrer`. |
| `device_context` | tidak | `fingerprint`, `persistent_device_id`, `bot_score`, dan `network_context.ip_address`. |
| `transaction_context` | tidak | `amount`, `currency`, `direction`, `payment_reference_id`. |
| `payload` | tidak | Kolom domain dari kategori tersebut. Hingga 16 KB. |
| `custom_values` | tidak | Hingga 100 kunci skalar, dapat dirujuk dari aturan sebagai `custom_values.<key>`. |

## Kategori

Sepuluh kategori utama, masing-masing dengan validasi berdasarkan tipe dan [kolom aturan](https://docs.didit.me/id/transaction-monitoring/event-rules.md#kolom-peristiwa) yang dikelola.

| Kategori | Tindakan umum |
| - | - |
| `auth` | `signup`, `login`, `login_failed`, `logout`, `password_forgot`, `password_reset`, `mfa_reset`, `mfa_challenge` |
| `session` | `session_started`, `session_ended`, `page_view`, `sdk_loaded`, `device_seen`, `bot_signal_observed`, `sdk_heartbeat` |
| `gameplay` | `round_started`, `round_completed`, `bet_placed`, `bet_settled`, `cashout`, `limit_change`, `p2p_settlement` |
| `bonus` | `bonus_claimed`, `bonus_wagered`, `bonus_released`, `promotion_viewed` |
| `affiliate` | `affiliate_attributed`, `referral_clicked`, `campaign_joined`, `commission_event` |
| `payment` | `deposit_initiated`, `deposit_completed`, `withdrawal_requested`, `withdrawal_completed`, `withdrawal_address_changed`, `payment_instrument_seen` |
| `dispute` | `chargeback_opened`, `chargeback_won`, `chargeback_lost`, `refund_issued`, `payment_dispute_updated` |
| `security` | `login_attempt`, `login_succeeded`, `login_failed`, `password_changed`, `mfa_changed`, `credential_reset`, `country_changed`, `device_changed`, `account_locked` |
| `responsible_gambling` | `self_exclusion_checked`, `self_exclusion_match`, `re_registration_attempt`, `limit_breach_attempt`, `registry_status_changed` |
| `custom` | Apa pun yang Anda definisikan |

`auth` adalah kategori produk yang lebih luas; `security` adalah subset berperingkat risiko dengan siklus hidup berurutan yang dibaca oleh aturan pengambilalihan akun.

### Kunci payload yang wajib

Sebagian tindakan tidak dapat dikorelasikan tanpa kunci tertentu, sehingga validasi menolaknya daripada menyimpan bukti yang tidak dapat digabungkan oleh siapa pun.

| Tindakan | Wajib |
| - | - |
| `gameplay.p2p_settlement` | `game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role`, dan salah satu dari `hand_id` / `round_id` / `match_id` |
| `gameplay.bet_placed`, `gameplay.bet_settled` | `game_id` |
| `payment.deposit_*`, `payment.withdrawal_completed`, `payment.withdrawal_requested`, `payment.deposit_initiated` | `payment_reference_id`, `amount`, `currency`, `payment_method`, `status` |
| `payment.withdrawal_address_changed` | `withdrawal_address_hash` |
| `dispute.chargeback_*` | `payment_reference_id`, dan salah satu dari `dispute_id` / `chargeback_id` |
| `security.*_changed` | `changed_field`; perubahan kontrol akun atau kontrol pencairan juga memerlukan `previous_reference_hash` atau `new_reference_hash` |
| `session.bot_signal_observed` | `telemetry_schema_version`, serta `bot_score` atau setidaknya satu metrik telemetri |
| `responsible_gambling.self_exclusion_match` | `registry_source`, `exclusion_status`, `identity_match_ref` |

> [!WARNING]
>
> Kirim **referensi dan hash**, jangan pernah rahasia mentah. Instrumen pembayaran, tujuan penarikan, dan perubahan kontrol akun disimpan sebagai referensi ter-hash yang Anda kirim. Jangan pernah mengirim nomor kartu, alamat penarikan lengkap, hash kata sandi, atau rahasia MFA.

### Contoh: penyelesaian P2P

```json theme={null}
{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}
```

### Contoh: chargeback

```json theme={null}
{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}
```

Siklus hidup sengketa hanya dapat ditambahkan: koreksi berupa event `dispute` baru, tidak pernah mengedit event pertama.

## Idempotensi

`event_id` unik per aplikasi dan merupakan seluruh kontrak idempotensi.

* **`event_id` sama, konten sama** mengembalikan `200` dengan `"idempotent_replay": true` dan event yang pertama kali disimpan. Coba lagi sesering yang Anda perlukan.
* **`event_id` sama, konten berbeda** mengembalikan `409`. Anda menggunakan ulang id tersebut secara tidak sengaja.

## Batch

`POST /v3/events/batch/` menerima hingga **500 event**. Batch dirancang agar sebagian dapat berhasil: satu tampilan halaman yang tidak valid tidak boleh menggagalkan chargeback di sebelahnya.

```json theme={null}
{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}
```

Respons berupa `207 Multi-Status` jika ada yang ditolak, dan `201 Created` jika semuanya berhasil diterima.

## Status

| Status | Arti |
| - | - |
| `ACCEPTED` | Tersimpan. Tidak ada aturan yang mengubah statusnya (ini adalah respons normal untuk sebagian besar event). |
| `APPROVED` | Sebuah aturan dijalankan dan skor tetap di bawah ambang batas peninjauan Anda. |
| `IN_REVIEW` | Sebuah aturan mendorongnya melewati ambang batas peninjauan, atau menetapkan status secara langsung. |
| `DECLINED` | Sebuah aturan menolaknya. |

`correlation_pending: true` berarti aturan lintas-subjek masih harus dijalankan. Proses ini selesai dalam hitungan menit, dan status serta skor event diperbarui langsung di tempatnya. Lihat [aturan asinkron](https://docs.didit.me/id/transaction-monitoring/event-rules.md#real-time-dan-aturan-asinkron).

## Retensi

Volume event jauh lebih besar daripada transaksi, sehingga setiap event dimasukkan ke dalam kelas retensi saat diterima.

| Kelas | Retensi aktif default | Yang masuk ke sini |
| - | - | - |
| `low_value` | 14 hari | Tampilan halaman, heartbeat, ping deteksi perangkat, telemetri bot, tampilan promosi |
| `standard` | 30 hari | Auth, session, gameplay, bonus, affiliate, custom |
| `risk_relevant` | 90 hari | Event security dan responsible gambling, serta **event apa pun yang dicocokkan oleh aturan** |
| `monetary_or_compliance` | Retensi transaksi | Event pembayaran dan sengketa |

Dua aturan berikut mengikuti tabel:

* Event yang cocok dengan aturan merupakan bukti, sehingga secara otomatis dinaikkan ke `risk_relevant`.
* Event pembayaran dan sengketa tetap menggunakan retensi transaksi. Event tersebut tidak pernah kedaluwarsa menurut jadwal event, dan penggantian pengaturan per kelas tidak dapat memperpendeknya.

Timpa ketiga kelas yang dapat kedaluwarsa per aplikasi di **Transactions → Settings → Event monitoring** (masing-masing 1-730 hari).

## Pengayaan IP

Event membawa [pengayaan IP](https://docs.didit.me/id/transaction-monitoring/ip-enrichment.md) yang sama dengan transaksi: negara, ASN, penanda VPN/proxy, dan penanda pusat data. Pengayaan diselesaikan **per alamat IP unik, tidak pernah per event**. Sesi yang memicu 200 tampilan halaman dari satu alamat hanya menyelesaikan alamat tersebut satu kali.

Telemetri bernilai rendah bahkan lebih terbatas: ia hanya membaca pengayaan jika event lain sudah menyelesaikan alamat tersebut. Telemetri ini tidak pernah memicu pencarian sendiri.

`GET /v3/events/enrichment-metrics/` melaporkan hasilnya, dan konsol menampilkan angka yang sama di atas daftar event:

```json theme={null}
{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}
```

## Membaca kembali event

```bash theme={null}
curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"
```

Filter: `event_category`, `action_type`, `status`, `retention_class`, `subject_vendor_data`, `business_vendor_data`, `session_id`, `device_fingerprint`, `ip_address`, `game_id`, `round_id`, `affiliate_code`, `payment_reference_id`, `counterparty_vendor_data`, `matched_only`, `occurred_from`, `occurred_to`, `search`. Filter dengan banyak nilai diulang dengan parameter yang sama (`?status=A&status=B`).

### Linimasa satu subjek

```bash theme={null}
curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"
```

`vendor_data` hanya unik **dalam** satu jenis entitas: ID yang sama bisa merujuk ke pengguna dan juga ke perusahaan, dan Didit memperlakukannya sebagai dua subjek yang berbeda. `entity_type` menentukan subjek yang Anda minta: `individual` (default) atau `company`. Jika dihilangkan untuk ID perusahaan, yang dikembalikan adalah linimasa individu, bukan keduanya. Filter daftar yang sama berlaku.

`GET /v3/events/{event_uuid}/` menambahkan payload, konteks perangkat, pengayaan IP, sinyal risiko subjek yang tersimpan di cache, dan setiap kecocokan aturan beserta buktinya, termasuk apakah setiap kolom yang cocok diturunkan dari server, diturunkan dari SDK, atau disediakan oleh pelanggan.

`DELETE /v3/events/{event_uuid}/delete/` menghapus satu event. Event tersebut tidak lagi dikembalikan dalam operasi pembacaan apa pun, dan penghapusan tidak dapat dibatalkan.

## Berikutnya

> [card] [Aturan pada event](https://docs.didit.me/id/transaction-monitoring/event-rules.md)
>
> Aturan kecepatan, rasio, urutan, dan korelasi atas data event.

> [card] [Pengiriman event SDK](https://docs.didit.me/id/transaction-monitoring/sdk-event-submission.md)
>
> Kirim event langsung dari perangkat dengan kredensial yang dibatasi cakupannya.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.