Referensi API

Panggil semua endpoint dari server Anda. Permintaan dan respons berformat JSON. URL webhook dan API key dikelola di dasbor merchant.

Butuh kode siap pakai? Contoh integrasi dalam Node.js, Python, PHP, Go, dan Java

Endpoint	Kegunaan
`POST /v1/payment_intents`	Buat pembayaran
`GET /v1/payment_intents/{id}`	Ambil pembayaran
`POST /v1/deposit_addresses`	Dapatkan alamat setoran pengguna
`GET /v1/deposits`	Daftar setoran
`GET /v1/deposits/{id}`	Ambil setoran
`GET /v1/chains`	Lihat chain dan token proyek
`PUT /v1/customers/{external_id}`	Tambahkan tag dan catatan ke pengguna (opsional)
`GET /v1/customers/{external_id}`	Ambil pengguna (opsional)

Konvensi

URL dasar	`https://api.kokiwa.com`, sama untuk mainnet dan testnet.
Autentikasi	Header `Authorization: Bearer sk_…`. Key yang diawali `sk_live_` mengakses mainnet dan yang diawali `sk_test_` mengakses testnet; datanya terpisah sepenuhnya. Key hanya mengakses proyeknya sendiri.
Jumlah	String dalam satuan token, seperti `"25.00"`. Permintaan mengizinkan hingga 6 desimal; respons mempertahankan presisi on-chain, sehingga banyaknya desimal bisa berbeda. Hanya `transaction.raw_amount` yang berisi nilai mentah on-chain.
Waktu	ISO 8601 UTC, seperti `2026-11-02T08:30:00Z`.
Alamat	Alamat EVM dikembalikan dalam format checksum EIP-55. Tampilkan apa adanya dan abaikan huruf besar/kecil saat membandingkan.
Idempotensi	Permintaan POST bisa mengirim `Idempotency-Key` (hingga 255 karakter). Percobaan ulang dengan key yang sama mengembalikan hasil pertama dengan header `Idempotent-Replayed: true`.

Kesalahan

Kegagalan mengembalikan 4xx atau 5xx. Gunakan code untuk menentukan penanganan; message hanya untuk debugging.

{
  "error": {
    "code": "amount_below_minimum",
    "message": "options[0].amount is below the minimum",
    "details": { "min_amount": "5.00" }
  }
}

HTTP	code	Arti
400	`invalid_*`	Parameter tidak valid; `message` menyebut kolomnya.
400	`chain_not_enabled`	Proyek belum punya alamat penerimaan aktif di chain ini, atau penerimaan dimatikan.
400	`chain_not_available`	Chain ini sedang tidak menerima pembayaran.
400	`chain_not_supported`	Chain ini tidak punya alamat setoran.
400	`token_not_enabled`	Proyek belum memilih token ini.
400	`currency_not_available`	Proyek tidak bisa menerima mata uang ini di chain mana pun.
400	`deposits_disabled`	Proyek mematikan alamat setoran.
400	`amount_below_minimum`	Di bawah jumlah minimum, yang tertera di `details.min_amount`.
401	`unauthorized`	API key tidak ada, tidak valid, atau sudah dicabut.
403	`project_disabled`	Proyek dinonaktifkan.
404	`not_found`	Sumber daya tidak ada atau milik proyek lain.
409	`request_in_progress`	Permintaan dengan `Idempotency-Key` yang sama masih berjalan. Coba lagi sebentar lagi.
422	`idempotency_key_reused`	`Idempotency-Key` yang sama dipakai untuk permintaan lain.
500	`internal_error`	Kesalahan server. Coba lagi nanti dengan `Idempotency-Key` yang sama.

Pembayaran

Pembayaran adalah pesanan yang harus dibayar pengguna. Pengguna membayar di halaman checkout dan Anda menerima hasilnya lewat webhook.

Buat pembayaran

POST/v1/payment_intents

Parameter	Keterangan
`currency` wajib	Mata uang, seperti `USDT`. Lihat `currencies` di `GET /v1/chains`.
`amount` wajib	Jumlah token, hingga 6 angka di belakang koma, seperti `"25.00"`.
`chains`	Hanya terima di chain ini, seperti `["bsc", "base"]`. Bawaannya semua chain tempat proyek menerima mata uang ini.
`customer`	ID pengguna di sistem Anda: 1 sampai 128 huruf, angka, atau `_ - . : @`.
`expires_in`	Masa berlaku dalam detik, 60 sampai 604800 (7 hari). Bawaan 1800 (30 menit).
`metadata`	Objek JSON apa pun, hingga 50 kunci dan 8KB, dikembalikan apa adanya oleh API dan webhook. Cocok untuk nomor pesanan.
`success_url`	URL https tujuan checkout setelah pembayaran.
`cancel_url`	URL https tujuan checkout saat pengguna mengklik Batal.

Chain dengan jumlah di bawah minimum dikeluarkan; jika tidak ada yang tersisa, permintaan gagal. Minimum bawaan adalah 5 USD; biaya Anda ada di bagian Biaya proyek di dasbor.

Tentukan token dan jumlah per chain

Untuk menerima beberapa mata uang, atau jumlah berbeda per chain, kirim options sebagai ganti currency, amount, dan chains. Hingga 16 item; token berupa simbol atau alamat kontrak.

"options": [
  { "chain": "bsc", "token": "USDT", "amount": "25.00" },
  { "chain": "bsc", "token": "USDC", "amount": "25.00" }
]

Respons

Mengembalikan 201 dan objek pembayaran. Buka checkout_url untuk pengguna.

{
  "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "object": "payment_intent",
  "status": "pending",
  "livemode": true,
  "customer": "user_42",
  "checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "metadata": { "order_id": "10086" },
  "success_url": "https://your-shop.com/orders/10086",
  "cancel_url": null,
  "created_at": "2026-11-02T08:30:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "paid_at": null,
  "paid_option": null,
  "options": [
    {
      "id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
      "chain": "bsc",
      "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": "0x8b1F…c04E"
    },
    {
      "id": "pio_2Mn7Xc4bQe6uJs1Ga8RvK3",
      "chain": "base",
      "token": { "symbol": "USDT", "address": "0xfde4…9bb2", "decimals": 6 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": null
    }
  ],
  "deposits": []
}

Kolom	Keterangan
`options`	Pilihan pengguna: satu token di satu chain per item.
`options[].received`	Jumlah yang sudah diterima untuk item ini.
`options[].deposit_address`	Alamat transfer khusus pembayaran ini, yang juga bisa Anda tampilkan di halaman sendiri. `null` jika metode ini tidak tersedia (chain selain BNB Chain, atau jumlah terlalu kecil).
`paid_option`	`options[].id` yang benar-benar dibayar pengguna.
`deposits`	Setiap setoran yang dikreditkan ke pembayaran ini, terlama lebih dulu. Lihat objek setoran.
`livemode`	`true` di mainnet, `false` di testnet.

Lihat pembayaran

GET/v1/payment_intents/{id}

Mengembalikan objek pembayaran. Gunakan untuk rekonsiliasi, atau untuk memeriksa status saat webhook tidak datang.

Status pembayaran

status	Keterangan
`pending`	Menunggu pembayaran.
`partially_paid`	Transfer ke alamat khusus masih kurang `amount − received`. Jangan kirim barang; status menjadi `paid` setelah pengguna melunasi.
`paid`	Lunas, siap dikirim. Kelebihan bayar juga dihitung di `received`; kokiwa tidak mengembalikannya.
`expired`	Kedaluwarsa tanpa pembayaran.
`paid_late`	Dana masuk ke alamat khusus setelah kedaluwarsa. Uangnya sudah milik Anda: putuskan kirim barang atau kembalikan dana.

Alamat setoran

Ambil alamat deposit pelanggan

POST/v1/deposit_addresses

Parameter	Keterangan
`customer` wajib	ID pengguna di sistem Anda, aturannya sama seperti pembayaran. Dibuat saat pertama kali dipakai.
`chain`	Saat ini hanya `bsc`, yang juga menjadi bawaan.

{
  "object": "deposit_address",
  "customer": "user_42",
  "chain": "bsc",
  "address": "0x3c9A…71d2",
  "tokens": [
    { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
  ]
}

Pengguna yang sama selalu mendapat alamat yang sama, jadi bisa ditampilkan jangka panjang. Hanya token di tokens yang dikreditkan.

Setiap transfer mengirim deposit.confirmed. Transfer di bawah min_settle_amount juga dikreditkan, dengan status held; setelah alamat mencapai minimum, semuanya disapu bersama ke alamat penerimaan Anda dengan satu biaya tetap.

Setoran

Setoran (deposit) adalah satu pembayaran on-chain yang dikreditkan, dari pembayaran atau alamat setoran. Satu pembayaran bisa punya beberapa setoran.

{
  "id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4",
  "object": "deposit",
  "status": "settled",
  "method": "wallet",
  "chain": "bsc",
  "customer": "user_42",
  "payment_intent": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
  "amount": "25.00",
  "fee": "0.0875",
  "net": "24.9125",
  "usd_value": "25.00",
  "confirmed_at": "2026-11-02T08:41:07Z",
  "transaction": {
    "hash": "0x4e7a…91c3",
    "log_index": 212,
    "block_number": 44718235,
    "block_time": "2026-11-02T08:40:58Z",
    "from": "0x1f9C…a2B0",
    "to": "0x7d3E…09f1",
    "raw_amount": "25000000000000000000"
  },
  "settlement": {
    "tx_hash": "0x4e7a…91c3",
    "by": "payment",
    "settled_at": "2026-11-02T08:40:58Z"
  }
}

Kolom	Keterangan
`method`	`wallet`: dibayar dengan dompet. `deposit_address`: ditransfer ke alamat.
`customer`	ID pengguna yang Anda kirim, atau `null`.
`payment_intent`	Pembayaran terkait; `null` untuk alamat setoran.
`amount`、`fee`、`net`	Jumlah yang dibayar pengguna, biaya, dan yang Anda terima. Selama `held`, `fee` bernilai 0 dan ditentukan saat penyapuan.
`usd_value`	`amount` dalam dolar AS pada harga token yang ditetapkan kokiwa.
`transaction`	Pembayaran pengguna on-chain, bisa dicek di penjelajah blok. Jika satu transaksi berisi beberapa transfer, `hash` + `log_index` menunjuk satu transfer. `from` tidak selalu dompet pengguna: setelah penarikan bursa, itu alamat bursa. `raw_amount` adalah nilai mentah transfer di on-chain dalam satuan terkecil token, hanya untuk dicocokkan di penjelajah blok.
`settlement`	Transaksi yang sampai ke alamat penerimaan Anda, atau `null` sebelum diselesaikan. `by` berupa `payment` (diselesaikan oleh pembayaran itu sendiri), `kokiwa` (disapu kokiwa), atau `owner` (Anda ambil dengan dompet sendiri, tanpa biaya). Setoran yang disapu bersama memakai `tx_hash` yang sama.

status	Keterangan
`confirmed`	Terkonfirmasi on-chain, menunggu disapu ke alamat penerimaan Anda. Anda bisa mengkreditkan pengguna.
`held`	Terkonfirmasi on-chain, masih terlalu kecil untuk disapu. Anda bisa mengkreditkan pengguna.
`settled`	Sudah sampai di alamat penerimaan Anda.

Lihat satu deposit

GET/v1/deposits/{id}

Daftar deposit

GET/v1/deposits

Terbaru lebih dulu.

Parameter kueri	Keterangan
`customer`	Hanya pengguna ini.
`tx_hash`	Cari berdasarkan hash transaksi pembayaran atau penyelesaian.
`limit`	Ukuran halaman, 1 sampai 100. Bawaan 20.
`starting_after`	`id` item terakhir di halaman sebelumnya.

curl "https://api.kokiwa.com/v1/deposits?tx_hash=0x4e7a…91c3" \
  -H "Authorization: Bearer $KOKIWA_KEY"

{ "object": "list", "data": [ { "id": "dep_9Kx2…", "object": "deposit", ... } ], "has_more": false }

Chain dan token

kokiwa mendukung jaringan dan mata uang di bawah ini. Gunakan kolom chain untuk chains dan options[].chain, serta kolom mata uang untuk currency.

`chain`	Blockchain	Mata uang	Metode pembayaran
`bsc`	BNB Chain	`USDT`, `USDC`	`wallet`, `deposit_address`
`ethereum`	Ethereum	`USDT`, `USDC`	`wallet`
`arbitrum`	Arbitrum	`USDT`, `USDC`	`wallet`
`base`	Base	`USDT`, `USDC`	`wallet`
`polygon`	Polygon	`USDT`, `USDC`	`wallet`
`optimism`	Optimism	`USDT`, `USDC`	`wallet`
`ton`	TON	`USDT`	`wallet`
`solana`	Solana	`USDT`, `USDC`	`wallet`

Testnet hanya mendukung USDT. Tokennya tUSDT, tetapi currency tetap USDT.

Ini seluruh rentang nilai, bukan yang pasti bisa diterima setiap proyek. Konfigurasi tiap bisnis berbeda, jadi periksa yang tersedia lewat endpoint di bawah.

Lihat jaringan dan token proyek

GET/v1/chains

Mengembalikan apa yang bisa diterima proyek milik key ini di jaringan saat ini.

{
  "object": "list",
  "livemode": true,
  "currencies": ["USDT"],
  "data": [
    {
      "object": "chain", "chain": "bsc", "name": "BNB Smart Chain", "chain_id": 56, "testnet": false, "native": "BNB",
      "payout_registered": true, "active": true,
      "methods": { "wallet": true, "deposit_address": true },
      "tokens": [
        { "symbol": "USDT", "asset": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "decimals": 18, "accepted": true },
        { "symbol": "USDC", "asset": "USDC", "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "decimals": 18, "accepted": false }
      ]
    }
  ]
}

Kolom	Keterangan
`currencies`	Mata uang yang bisa dikirim sebagai `currency` saat ini.
`data[].chain`	Nilai untuk `chain` dan `options[].chain`: `bsc`, `ethereum`, `arbitrum`, `base`, `polygon`, `optimism`, `ton`, `solana`.
`data[].active`	Apakah chain bisa menerima sekarang: alamat terdaftar, metode aktif, dan token dipilih.
`data[].tokens[].asset`	Mata uang token. Token dengan `asset` yang sama setara antar-chain.
`data[].tokens[].accepted`	Apakah proyek memilih token ini.

Pelanggan

Opsional. Pelanggan dibuat saat nilai customer pertama kali muncul; endpoint ini hanya perlu untuk memfilter berdasarkan tag di dasbor.

Atur label dan catatan

PUT/v1/customers/{external_id}

Parameter	Keterangan
`tags`	Hingga 20 tag, masing-masing 1 sampai 64 huruf, angka, atau `_ - . :`.
`metadata`	Objek JSON apa pun, hingga 50 kunci dan 8KB.

Lihat pelanggan

GET/v1/customers/{external_id}

Mengembalikan tag, catatan, dan deposit_addresses (alamat setoran per chain).

Berikutnya: Webhook