Integrasi Pemantauan Transaksi: API KYT

This guide covers the full integration surface of Pemantauan Transaksi. Panduan cepat membantu Anda mulai; halaman ini membantu Anda mencapai produksi.

Arsitektur

Autentikasi

Gunakan header x-api-key standar. Kunci yang sama dipakai untuk sesi dan entitas. Lihat autentikasi API.

Mengirim transaksi

Hanya ada satu endpoint: POST /v3/transactions/. Lihat mengirim transaksi untuk skema lengkap. Payload minimal:

{
  "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:

{
  "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 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}/ 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:

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

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.

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

Lihat status TM.

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, 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:

{
  "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. 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. 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.

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

Batas laju

Lihat pembatasan laju. 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

Transaksi

Referensi payload lengkap.

Aturan

Cara aturan dievaluasi.

Webhook

Katalog event.

Pemecahan masalah

Masalah integrasi yang umum.

Memulai

Fitur

Referensi

Konsol

Integrasi Pemantauan Transaksi: API KYT

Arsitektur

Autentikasi

Mengirim transaksi

Pemodelan pihak

Idempotensi

Real-time vs batch

Ingesti historis

Webhook

Menangani status

Menautkan transaksi ke entitas

Sesi remediasi

Praktik terbaik

Batas laju

Langkah berikutnya

Transaksi

Aturan

Webhook

Pemecahan masalah

​Arsitektur

​Autentikasi

​Mengirim transaksi

​Pemodelan pihak

​Idempotensi

​Real-time vs batch

​Ingesti historis

​Webhook

​Menangani status

​Menautkan transaksi ke entitas

​Sesi remediasi

​Praktik terbaik

​Batas laju

​Langkah berikutnya

Transaksi

Aturan

Webhook

Pemecahan masalah

Arsitektur

Autentikasi

Mengirim transaksi

Pemodelan pihak

Idempotensi

Real-time vs batch

Ingesti historis

Webhook

Menangani status

Menautkan transaksi ke entitas

Sesi remediasi

Praktik terbaik

Batas laju

Langkah berikutnya