> ## 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.

# Integrasi Pemantauan Transaksi: API KYT

> Arsitektur dan praktik terbaik KYT Didit: real-time vs batch, pihak, idempotensi, impor historis, webhook. 1.000 per bulan gratis, lalu $0.001 per panggilan.

This guide covers the full integration surface of Pemantauan Transaksi. [Panduan cepat](https://docs.didit.me/id/transaction-monitoring/quickstart.md) membantu Anda mulai; halaman ini membantu Anda mencapai produksi.

## Arsitektur

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## Autentikasi

Gunakan header `x-api-key` standar. Kunci yang sama dipakai untuk sesi dan entitas. Lihat [autentikasi API](https://docs.didit.me/id/getting-started/api-authentication.md).

## Mengirim transaksi

Hanya ada satu endpoint: `POST /v3/transactions/`. Lihat [mengirim transaksi](https://docs.didit.me/id/transaction-monitoring/transactions.md) untuk skema lengkap.

**Payload minimal:**

```json theme={null}
{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}
```

**Payload lebih lengkap dengan metode pembayaran, konteks perangkat, dan properti kustom:**

```json theme={null}
{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}
```

Alias camelCase diterima untuk setiap kolom tingkat atas (`txnId`, `txnDate`, `type`, `info`, `applicant`, `props`, `travelRule`, `includeCryptoScreening`); format wire pada SDK dan format snake\_case dipetakan ke tempat yang sama.

## Pemodelan pihak

Setiap transaksi wajib memiliki `subject` (pelanggan Anda, yaitu pihak yang Anda pantau) dan `counterparty` opsional (pihak lawannya). Masing-masing memiliki `payment_method` sendiri dan konteks `device` opsional.

Dalam respons, keduanya dikembalikan dalam array `parties` dengan peran `APPLICANT` dan `COUNTERPARTY`; pihak tanpa `vendor_data` disimpan sebagai snapshot eksternal (`kind: EXTERNAL`) tanpa entitas tertaut.

Lihat [payload transaksi](https://docs.didit.me/id/transaction-monitoring/transactions.md) untuk kolom pihak.

## Idempotensi

`txn_id` (`transaction_id` yang Anda kirim) bersifat unik per aplikasi.
Mengirim ulang `transaction_id` yang sudah ada akan mengembalikan `400` dengan `A transaction with this transaction_id already exists.` pada kolom `transaction_id`; ketika dua permintaan identik datang bersamaan, permintaan kedua menerima `409`.
Tidak ada respons yang mengembalikan transaksi yang sudah ada.
Pada `400` atau `409` untuk `transaction_id` duplikat, cari transaksi yang sudah ada alih-alih mengirim ulang: baca dengan [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/id/management-api/transactions/get) menggunakan `uuid` dari respons pertama, atau gunakan `transaction_id` (uuid Didit) yang dibawa webhook `transaction.created` di samping `txn_id` Anda.

**Selalu buat `txn_id` di sisi Anda** sebelum mengirim; jangan mengandalkan ID yang dibuat Didit untuk idempotensi. Gunakan ID database Anda sendiri, UUID, atau hash dari kolom transaksi.

## Real-time vs batch

* **Real-time**: direkomendasikan untuk sebagian besar kasus penggunaan. Kirim transaksi begitu terjadi di sistem Anda. Aturan dievaluasi secara sinkron dan mengembalikan keputusan.
* **Batch / backfill**: untuk ingesti historis, berikan `txn_date` di masa lalu. Aturan tetap dijalankan dan dapat memicu webhook. Untuk menghindari pemicuan aturan saat backfill, gunakan impor CSV di konsol dengan flag "dry ingest".

## Ingesti historis

Saat Anda bermigrasi dari sistem pemantauan transaksi lain:

1. Ekspor transaksi historis Anda ke CSV.
2. Gunakan *Transactions → Import history* di konsol (atau kirim melalui API secara berulang) dengan `txn_date` di masa lalu.
3. Aktifkan aturan hanya setelah ingesti selesai, atau gunakan dry ingest untuk melewati evaluasi aturan.

> [!WARNING]
>
> Berhati-hatilah saat mengevaluasi aturan pada riwayat. Memasukkan riwayat 6 bulan melalui aturan "20 transfer dalam 30 hari" akan menghasilkan ribuan alert sekaligus.

## Webhook

Berlangganan ke:

* `transaction.created`: setiap transaksi yang dikirim.
* `transaction.status.updated`: perubahan status (misalnya analis memindahkan dari `IN_REVIEW` ke `APPROVED`, atau pemeriksaan AML asinkron memperbarui skor).

Detail lengkap: [webhook TM](https://docs.didit.me/id/transaction-monitoring/webhooks.md).

```typescript theme={null}
app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});
```

## Menangani status

| Status | Yang harus dilakukan |
| - | - |
| `APPROVED` | Proses transaksi seperti biasa. |
| `IN_REVIEW` | Tahan transaksi hingga peninjauan analis atau pemeriksaan ulang otomatis selesai. |
| `DECLINED` | Tolak transaksi. Tampilkan pesan error umum kepada pengguna. |
| `AWAITING_USER` | Pengguna harus bertindak sebelum transaksi dapat diselesaikan: baca blok `action_required` dan kirimkan `url`-nya kepada pengguna (SDK dapat [menangani ini secara otomatis](https://docs.didit.me/id/transaction-monitoring/sdk-transaction-submission.md#tindakan-yang-diperlukan-pengguna)). |

Lihat [status TM](https://docs.didit.me/id/transaction-monitoring/statuses.md).

## Menautkan transaksi ke entitas

Sertakan `vendor_data` pada setiap pihak. Manfaatnya:

* Setiap transaksi diagregasi ke profil Pengguna atau Bisnis.
* Aturan frekuensi dan perilaku memiliki riwayat lengkap untuk dievaluasi.
* Pemblokiran entitas otomatis berlaku pada transaksi berikutnya.

`vendor_data` yang tidak ada bukan error fatal: transaksi disimpan sebagai snapshot eksternal, tetapi Anda kehilangan agregasi tingkat entitas.

## Sesi remediasi

Ketika tindakan aturan memindahkan transaksi ke `AWAITING_USER`, Didit otomatis membuat **sesi remediasi**, yaitu sesi verifikasi yang di-hosting standar untuk `vendor_data` yang sama.
Aturan kustom selalu menyebutkan alur kerja pada tindakan itu sendiri. Untuk aturan bawaan pustaka, alur kerja akan beralih ke [alur kerja remediasi di pengaturan transaksi Anda](https://docs.didit.me/id/transaction-monitoring/settings.md#alur-kerja-remediasi), lalu ke alur kerja Autentikasi Biometrik aplikasi Anda (jika subjek memiliki wajah referensi yang tersimpan), lalu ke alur kerja default aplikasi Anda.
Transaksi Travel Rule dikecualikan dari penggantian otomatis ini. Tindakan yang tertunda pada transaksi tersebut adalah pembuktian kepemilikan dompet.
Transaksi (respons, setiap pembacaan berikutnya, dan setiap webhook) memuat sesi ini dalam blok kanonis `action_required`:

```json theme={null}
{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}
```

`remediation` dipertahankan untuk kompatibilitas mundur. `action_required` adalah blok kanonis, dan blok ini juga memuat tindakan `wallet_ownership` untuk transfer [Travel Rule](https://docs.didit.me/id/transaction-monitoring/travel-rule.md).
Tindakan `wallet_ownership` tidak mengubah status transaksi dengan sendirinya. Transaksi tetap mempertahankan status yang diberikan aturan Anda, sering kali `APPROVED`, jadi periksa `action_required` pada setiap respons, bukan hanya saat `AWAITING_USER`.

Pengguna menyelesaikan verifikasi. Untuk alur kerja **Autentikasi Biometrik**, pengguna mengambil swafoto yang telah melalui Deteksi Liveness dan dicocokkan dengan wajah yang diambil saat onboarding KYC awal mereka. Ini adalah langkah tambahan paling kuat untuk [transaksi bernilai tinggi](https://docs.didit.me/id/transaction-monitoring/sdk-transaction-submission.md#contoh-biometrik-tambahan-untuk-penarikan-bernilai-tinggi).
Setelah sesi mencapai keputusan, transaksi mengikutinya secara otomatis: `APPROVED` (`decision_reason_code: user_action_approved`), `DECLINED` (`user_action_declined`), atau `IN_REVIEW` (`user_action_in_review`). Webhook `transaction.status.updated` kemudian dipicu.

> [!NOTE]
>
> Jenis alur kerja apa pun selain KYB dapat dipilih.
> Alur kerja Autentikasi Biometrik (dan alur kerja yang menjalankan Pencocokan Wajah sebelum Verifikasi Identitas) mensyaratkan subjek sudah memiliki wajah referensi yang tersimpan dari verifikasi yang disetujui. Pengguna yang belum memiliki wajah referensi diarahkan ke alur kerja default aplikasi Anda, dengan catatan pada transaksi yang mencatat penggantian ini.

## Praktik terbaik

| Praktik | Alasan |
| - | - |
| Selalu kirim `vendor_data` | Memungkinkan agregasi. |
| Gunakan `txn_id` Anda sendiri | Idempotensi. |
| Berlangganan ke `transaction.created` dan `transaction.status.updated` | Menangkap perubahan status asinkron (misalnya hasil peninjauan analis). |
| Tetapkan ambang batas aturan secara cermat | Ambang batas rendah = lebih banyak alert; tinggi = lebih banyak risiko yang terlewat. Lihat [penilaian risiko](https://docs.didit.me/id/transaction-monitoring/risk-scoring.md). |
| Pantau jumlah eksekusi aturan di konsol | Temukan aturan yang tidak pernah terpicu (salah konfigurasi) atau yang terpicu pada semua kejadian (terlalu longgar). |
| Uji aturan dalam mode TEST sebelum masuk ke produksi | Lihat [aturan](https://docs.didit.me/id/transaction-monitoring/rules.md). |

## Batas laju

Lihat [pembatasan laju](https://docs.didit.me/id/integration/rate-limiting.md). Pembuatan transaksi adalah salah satu endpoint dengan kapasitas pemrosesan tertinggi; batas tipikalnya berada di kisaran ratusan permintaan per detik. Berhati-hatilah saat mengirim permintaan dalam lonjakan.

## Langkah berikutnya

> [card] [Transaksi](https://docs.didit.me/id/transaction-monitoring/transactions.md)
>
> Referensi payload lengkap.

> [card] [Aturan](https://docs.didit.me/id/transaction-monitoring/rules.md)
>
> Cara aturan dievaluasi.

> [card] [Webhook](https://docs.didit.me/id/transaction-monitoring/webhooks.md)
>
> Katalog event.

> [card] [Pemecahan masalah](https://docs.didit.me/id/transaction-monitoring/troubleshooting.md)
>
> Masalah integrasi yang umum.


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