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

# API Submit Transaksi: Payload & Model Data

> Kirim transaksi ke Didit untuk pemantauan real-time dengan data pihak dan metode pembayaran. 1,000 per bulan gratis, lalu $0.001 per transaksi.

Kirim transaksi ke Didit melalui API [Create Transaction](https://docs.didit.me/id/management-api/transactions/create.md). Setiap transaksi menyertakan data pihak, pembayaran, dan konteks terstruktur yang dievaluasi oleh mesin aturan secara real-time.

> [!TIP]
>
> Ketika transaksi berasal dari perangkat pengguna akhir, misalnya penarikan kripto atau pembayaran dalam aplikasi, pertimbangkan [pengiriman transaksi SDK](https://docs.didit.me/id/transaction-monitoring/sdk-transaction-submission.md): token dengan cakupan terbatas menggantikan kunci API, informasi perangkat dikumpulkan secara otomatis, dan tindakan pengguna yang diperlukan (pembuktian kepemilikan dompet, verifikasi tambahan) langsung dijalankan.

## Kategori transaksi

Setiap transaksi memiliki `transaction_category` yang menentukan bagaimana aturan dan analitik menangani transaksi tersebut:

| Kategori | Deskripsi |
| - | - |
| `finance` | Transaksi keuangan standar (deposit, penarikan, transfer) |
| `kyc` | Peristiwa terkait verifikasi identitas |
| `travel_rule` | Transfer aset virtual yang memerlukan kepatuhan Travel Rule |
| `user_event` | Peristiwa platform kustom (login, perubahan profil, dll.) |
| `gambling_bet` | Pemasangan taruhan atau taruhan judi |
| `gambling_limit_change` | Perubahan batas deposit, kerugian, atau taruhan pemain |
| `gambling_bonus_change` | Pemberian, penukaran, atau penyitaan bonus |
| `audit_trail_event` | Peristiwa audit sistem atau kepatuhan |

## Detail transaksi

Objek `transaction_details` memuat data keuangan:

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `direction` | string | `inbound` atau `outbound` |
| `amount` | string | Nilai transaksi sebagai string desimal (misalnya `"1500.50"`) |
| `currency` | string | Kode mata uang ISO (misalnya `USD`, `EUR`, `BTC`) |
| `currency_kind` | string | `fiat` atau `crypto` (alias `currencyType`); menentukan apakah skrining kripto dipicu |
| `action_type` | string | Label tindakan yang ditentukan vendor (misalnya `deposit`, `withdrawal`, `purchase`) |
| `payment_details` | string | Deskripsi bebas tentang pembayaran (misalnya `"Bank transfer from ABC Corp"`) |
| `payment_reference_id` | string | ID referensi pembayaran eksternal. Untuk skrining kripto pascatransfer, gunakan hash transaksi blockchain. |

## Subjek dan pihak lawan

Setiap transaksi memiliki **subjek** (wajib) dan **pihak lawan** (opsional). Keduanya menggunakan model pihak yang sama:

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `entity_type` | string | `person` atau `company` |
| `vendor_data` | string | Pengenal Anda untuk pihak ini, menautkan transaksi ke [pengguna](https://docs.didit.me/id/management-api/users/list.md) atau [profil bisnis](https://docs.didit.me/id/business-verification/business-profiles.md) |
| `full_name` | string | Nama lengkap pihak |
| `first_name` | string | Nama depan |
| `last_name` | string | Nama belakang |
| `date_of_birth` | string | Tanggal ISO (misalnya `1990-01-15`) |
| `country_code` | string | Kode negara ISO 3166-1 alpha-2 |
| `address` | object atau string | Alamat terstruktur dengan `street`, `city`, `state`, `country`, `postal_code`. Juga menerima string biasa, misalnya alamat dompet untuk pihak lawan kripto. Didit menyimpannya tanpa perubahan pada pihak tersebut. |

Didit menurunkan `country_code` pihak dari `address.country` ketika `address` berupa objek. Ketika `address` berupa string, `country_code` dikembalikan sebagai `null` pada pihak tersebut.

Ketika `vendor_data` cocok dengan pengguna atau bisnis yang sudah ada, Didit secara otomatis menautkan transaksi ke profil entitas tersebut, sehingga memungkinkan evaluasi aturan lintas sesi dan pemeriksaan frekuensi transaksi.
Dalam respons, kedua pihak dikembalikan dalam array `parties` dengan peran `APPLICANT` dan `COUNTERPARTY`.

## Metode pembayaran

Lampirkan `payment_method` ke setiap pihak untuk menjelaskan instrumen di sisi tersebut:

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `method_type` | string | `bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet`, atau `other` (alias `type`); `ewallet`, `card`, dan `crypto` diterima sebagai alias, dan nilai yang tidak dikenali disimpan sebagai `other` |
| `account_id` | string | Nomor rekening, alamat, atau token kartu |
| `issuing_country` | string | Negara yang menerbitkan instrumen pembayaran |

Pada transaksi `travelRule`, metode pembayaran pihak lawan dengan `method_type: "unhosted_wallet"` (alias `type`) menyatakan dompet pihak lawan sebagai dompet swakelola.
Ketika Travel Rule diaktifkan dan jumlahnya, dalam mata uang default aplikasi Anda, tidak berada di bawah `threshold_amount`, transfer langsung masuk ke `UNCONFIRMED_OWNERSHIP` dan alur pembuktian kepemilikan, lihat [Dompet swakelola yang dideklarasikan](https://docs.didit.me/id/transaction-monitoring/travel-rule.md#dompet-swakelola-yang-dideklarasikan).

Untuk transaksi kripto, sertakan alamat di `account_id` dan atur `currency_kind` ke `crypto` agar skrining blockchain dapat berjalan otomatis. Arah transaksi menentukan dompet mana yang diskrining: skrining inbound pra-transfer menggunakan dompet pengirim di `counterparty.payment_method.account_id`; skrining outbound menggunakan dompet tujuan di `counterparty.payment_method.account_id`. Jika Anda mengirim hash blockchain di `transaction_details.payment_reference_id`, skrining transaksi inbound memerlukan alamat deposit layanan Anda di `subject.payment_method.account_id`, sedangkan skrining transaksi outbound memerlukan dompet tujuan di `counterparty.payment_method.account_id`.

## Penggantian skrining kripto

Gunakan `include_crypto_screening` di tingkat atas permintaan untuk mengganti default yang dikonfigurasi di **Transactions** > **Settings** pada Console:

| Nilai | Deskripsi |
| - | - |
| `true` | Paksa skrining kripto untuk transaksi ini |
| `false` | Lewati skrining kripto untuk transaksi ini |
| dihilangkan atau `null` | Gunakan default tingkat aplikasi |

## Konteks perangkat

Sertakan informasi perangkat pada subjek (dan secara opsional pada pihak lawan) agar aturan intelijen perangkat dapat berjalan. Kolom permintaan adalah `device_context` pada setiap pihak. Alias camelCase `device` juga diterima dan merupakan format pengiriman yang digunakan SDK. Respons mengembalikannya sebagai `device` pada setiap pihak dalam array `parties`.

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `device_context.fingerprint` | string | Sidik jari perangkat yang unik |
| `device_context.persistent_device_id` | string | Pengenal perangkat yang stabil lintas sesi (skema fingerprint v2) |
| `device_context.user_agent` | string | String user agent browser atau aplikasi |
| `device_context.browser_family` | string | Keluarga browser (misalnya `Chrome`, `Firefox`, `Safari`). **Harus dikirim secara eksplisit**. Nilainya tidak diturunkan dari `user_agent`. Mendukung aturan seperti `subject_browser_family`. |
| `device_context.browser_version` | string | Versi browser (misalnya `131.0`). Harus dikirim secara eksplisit. |
| `device_context.platform` | string | Pengenal platform (`web`, `ios`, `android`, `macos`, `windows`, `linux`). **Harus dikirim secara eksplisit**. Nilainya tidak diturunkan dari `user_agent`. Mendukung aturan seperti `subject_platform`. |
| `device_context.os_family` | string | Keluarga sistem operasi (misalnya `iOS`, `Android`, `Windows`) |
| `device_context.os_version` | string | String versi sistem operasi |
| `device_context.accept_language` | string | Nilai header Accept-Language (misalnya `en-US,en;q=0.9`). Pada jalur SDK, nilai ini dikumpulkan secara otomatis. |
| `device_context.session_id` | string | Pengenal sesi dari sesi pengguna saat ini. Disimpan dalam metadata. Alias camelCase: `sessionId`. |
| `device_context.session_age_ms` | number | Usia sesi pengguna dalam milidetik pada saat transaksi. Mendukung aturan seperti `subject_session_age_ms`. |
| `device_context.network_context.ip_address` | string | Alamat IP klien |
| `device_context.network_context.ip_country_code` | string | Negara IP yang ditentukan berdasarkan geolokasi (ISO 3166-1 alpha-3) |
| `device_context.network_context.latitude` | number | Lintang geografis dari IP |
| `device_context.network_context.longitude` | number | Bujur geografis dari IP |

> [!NOTE]
>
> `browser_family` dan `platform` **tidak** diturunkan dari `user_agent`. Keduanya harus dikirim sebagai kunci tingkat atas yang eksplisit di dalam `device_context` agar aturan intelijen perangkat dapat aktif. Jika Anda menggunakan SDK Didit, kedua kolom ini dikumpulkan secara otomatis.

Alias camelCase diterima untuk setiap kolom: `userAgent`, `browserFamily`, `browserVersion`, `osFamily`, `osVersion`, `acceptLang`, `sessionId`, `sessionAgeMs`. Sub-objek `network_context` menerima alias `ip` / `countryCode3` / `lat` / `lon`, dan blok `ipInfo` tingkat atas juga digabungkan ke dalam `network_context`.

Konteks perangkat memungkinkan aturan seperti deteksi multi-akun (fingerprint yang sama pada subjek yang berbeda), deteksi kombinasi browser baru dan IP baru, transfer bernilai tinggi dengan usia sesi yang rendah, serta penilaian risiko berbasis lokasi.

## Properti khusus

Tambahkan pasangan kunci-nilai tambahan apa pun dalam objek `custom_properties`. Aturan dapat merujuk kolom ini dalam kondisinya. Fitur ini berguna untuk meneruskan konteks khusus bisnis, seperti kategori produk, ID merchant, atau saluran.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

Dalam kondisi aturan, rujuk setiap kunci dengan path kolom `custom_values.<key>`. Misalnya, payload di atas cocok dengan `custom_values.product_category eq "electronics"`. Di pembuat aturan Console, kunci yang muncul pada transaksi yang baru diterima akan tampil di pemilih kolom kondisi di bawah **Properti khusus**. **Masukkan properti kustom** dalam grup yang sama memungkinkan Anda mengetik kunci apa pun secara manual (peka huruf besar/kecil). Lihat [Aturan & penilaian](https://docs.didit.me/id/transaction-monitoring/rules.md#merujuk-properti-kustom) untuk detailnya.

## Contoh permintaan

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'
```

## Respons

API mengembalikan transaksi yang dibuat beserta hasil evaluasi awalnya:

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `uuid` | string | Pengenal unik transaksi dari Didit |
| `txn_id` | string | ID transaksi yang Anda berikan |
| `status` | string | `APPROVED`, `IN_REVIEW`, `DECLINED`, atau `AWAITING_USER` |
| `score` | number | Skor risiko kumulatif dari semua aturan yang cocok |
| `severity` | string | Tingkat keparahan tertinggi dari aturan yang cocok (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) |
| `decision_reason_code` | string | Kode alasan yang dapat dibaca mesin untuk keputusan status |
| `decision_reason_label` | string | Deskripsi keputusan yang dapat dibaca manusia |

Lihat [Referensi API](https://docs.didit.me/id/management-api/transactions/create.md) untuk skema permintaan dan respons lengkap, serta [referensi skema respons](https://docs.didit.me/id/transaction-monitoring/response-schema.md) untuk penelusuran payload beranotasi.

## Tetapkan transaksi ke peninjau

Tetapkan transaksi yang ditahan kepada anggota aplikasi Anda, atau batalkan penugasannya, dengan kunci API yang memiliki izin `write:transactions`.
Setiap perubahan dicatat di linimasa transaksi sebagai `TRANSACTION_ASSIGNED`.

| Panggilan | Kegunaan |
| - | - |
| `POST /v3/transactions/{transaction_uuid}/assign/` | Menetapkan satu transaksi. |
| `POST /v3/transactions/assign/` | Menetapkan hingga 500 transaksi kepada satu anggota. |

Kedua panggilan menerima `assignee_email`, yaitu email anggota aplikasi yang telah masuk ke Didit.
Kirim `null` atau string kosong untuk membatalkan penugasan.
Panggilan massal juga menerima `transaction_ids`, yaitu daftar 1 hingga 500 UUID transaksi.

```bash theme={null}
curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'
```

Panggilan tunggal mengembalikan `uuid`, `transaction_number`, `assignee`, dan `changed` (`false` jika transaksi sudah ditugaskan kepada anggota ini), atau `404` jika transaksi tidak ada di aplikasi.
Panggilan massal mengembalikan `transactions` (satu entri seperti di atas), `updated_count`, dan `not_found_transaction_ids`.

Filter [daftar transaksi](https://docs.didit.me/id/management-api/transactions/list.md) dengan `assignee`, yaitu daftar yang dipisahkan koma di mana nilai apa pun cocok: `me`, `unassigned`, `rules` (diputuskan oleh aturan saja, tanpa melibatkan peninjau), atau email anggota.

## Idempotensi

`txn_id` (`transaction_id` yang Anda kirim) unik untuk setiap aplikasi.
Mengirim ulang `transaction_id` yang sudah ada akan mengembalikan `400` dengan `A transaction with this transaction_id already exists.` pada kolom `transaction_id`, dan dua permintaan identik yang berjalan bersamaan akan membuat permintaan kedua menerima `409`.
Kedua respons tersebut tidak mengembalikan transaksi yang sudah ada.
Untuk mencoba ulang dengan aman, perlakukan `400` atau `409` untuk `transaction_id` duplikat sebagai "sudah dibuat" dan cari transaksi yang sudah ada, alih-alih mengirim ulang: baca transaksinya 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 oleh webhook `transaction.created` di samping `txn_id` Anda.
Selalu hasilkan `txn_id` di sisi Anda (misalnya ID DB transaksi Anda sendiri, UUID, atau hash deterministik).

## Pengisian data historis

Teruskan `txn_date` yang berisi tanggal di masa lalu untuk mengimpor transaksi historis. Aturan tetap dievaluasi secara default. Gunakan impor CSV di konsol dengan mode dry-ingest jika Anda ingin melewati evaluasi aturan selama pemuatan data historis dalam jumlah besar. Lihat [panduan integrasi](https://docs.didit.me/id/transaction-monitoring/integration-guide.md#ingesti-historis).

## Langkah berikutnya

> [card] [Aturan & penilaian](https://docs.didit.me/id/transaction-monitoring/rules.md)
>
> Cara transaksi yang dikirim dievaluasi terhadap aturan.

> [card] [Skema respons](https://docs.didit.me/id/transaction-monitoring/response-schema.md)
>
> Payload respons lengkap dengan anotasi.

> [card] [Skrining kripto](https://docs.didit.me/id/transaction-monitoring/aml-screening.md)
>
> Skrining otomatis dompet dan transaksi untuk transaksi kripto.

> [card] [Travel Rule](https://docs.didit.me/id/transaction-monitoring/travel-rule.md)
>
> Lampirkan data kepatuhan Travel Rule ke transfer aset virtual.

> [card] [Pengayaan IP](https://docs.didit.me/id/transaction-monitoring/ip-enrichment.md)
>
> Konteks yang berasal dari IP tersedia untuk aturan.

> [card] [Referensi API](https://docs.didit.me/id/management-api/transactions/create.md)
>
> Skema permintaan lengkap untuk endpoint Create Transaction.


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