Dokumentasi API doit.id

Terima pembayaran QRIS dan Virtual Account dengan satu API sederhana. Tanpa signature rumit, tanpa menunggu: daftar, ambil API key, dan transaksi uji pertamamu jalan dalam hitungan menit.

Mulai dalam 10 menit

1. Buat akun di doit.id/daftar (dashboard sandbox aktif begitu email dan nomor WhatsApp terverifikasi), lalu masuk ke portal → menu Developer → buat aplikasi → salin API key (pb_test_…).

2. Buat pembayaran pertama:

curl -X POST https://pay.doit.id/v1/payments \
  -H "Authorization: Bearer pb_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-001" \
  -d '{"amount": 150000, "rail": "qris", "reference": "INV/001"}'

Respons berisi qr_content: render sebagai gambar QR (mis. npm qrcode) dan tunjukkan ke pembayar.

3. Set webhook URL di menu Developer, lalu buka pembayaran tadi di portal dan klik Simulasikan lunas. Webhook payment.paid tiba di server-mu. Integrasi selesai.

Autentikasi

Semua request memakai API key di header Authorization:

Authorization: Bearer pb_test_xxx

API key diterbitkan per aplikasi di portal, tampil sekali saat dibuat. Tidak ada signature, timestamp, atau header tambahan; cukup key ini lewat HTTPS.

Test vs live

Environment ditentukan oleh prefix key, bukan base URL, jadi kode integrasi tidak berubah:

Idempotency

Semua POST wajib menyertakan header Idempotency-Key. Pakai ID unik dari sistemmu (mis. nomor invoice). Request ulang dengan key sama mengembalikan hasil pertama (HTTP 200), tidak pernah membuat transaksi ganda. Timeout? Kirim ulang saja dengan key yang sama.

Rate limit

120 request per menit per API key. Terlampaui → HTTP 429 dengan header Retry-After (detik). Hormati nilainya, lalu ulangi request yang sama (aman, karena idempotency).

Membuat pembayaran

POST /v1/payments

Respons 201:

{
  "id": "pay_x8Kj2…",
  "status": "pending",
  "amount": 150000,
  "rail": "qris",
  "reference": "INV/001",
  "qr_content": "00020101…",        // rail=qris → render jadi QR
  "va_number": null,                 // rail=va → nomor VA
  "va_bank": null,
  "hosted_url": "https://pay.doit.id/p/pay_x8Kj2…",
  "return_url": "https://tokomu.id/invoice/42",   // opsional saat create
  "provider": "pjp",             // penyelenggara berizin yang menerbitkan instrumen
  "provider_ref": "A48957157…",  // referensi di sisi penyedia, untuk rekonsiliasi
  "fee_amount": 4000,            // biaya layanan metode ini
  "fee_payer": "customer",       // siapa yang menanggung (diatur di portal)
  "total_amount": 154000,        // yang dibayar pelanggan; = amount bila payer merchant
  "expires_at": "2026-08-19T15:30:00.000Z",
  "paid_at": null,
  "metadata": null,
  "created_at": "2026-08-19T14:30:00.000Z"
}

Metode pembayaran & biaya layanan

Biaya di atas adalah default platform; harga nego per aplikasi bisa berbeda; tarif efektif untuk aplikasi Anda selalu terlihat di portal → Metode Pembayaran dan di field fee_amount setiap respons.

Di portal → Metode Pembayaran, tiap aplikasi bisa menyalakan/mematikan metode (VA per bank, QRIS) dan memilih siapa yang menanggung biaya layanan: Merchant (tagihan pelanggan tetap; biaya mengurangi penerimaan) atau Customer (biaya ditambahkan ke total yang dibayar, terlihat transparan di halaman bayar dan di field fee_amount/total_amount). Metode yang dimatikan menolak transaksi baru dengan error method_disabled; metode yang belum tersedia di platform tampil nonaktif dan mengembalikan method_unavailable.

Halaman bayar hosted: tanpa frontend sama sekali

Setiap payment membawa hosted_url: halaman bayar siap pakai yang bisa kamu kirim langsung ke pelanggan (WhatsApp, email, SMS). Halaman itu menampilkan nama usahamu, nominal, QR yang sudah dirender (atau nomor VA + tombol salin), memperbarui statusnya sendiri saat pembayaran masuk, dan menangani kedaluwarsa. Kalau kamu tidak ingin membangun tampilan pembayaran sendiri, cukup teruskan tautan ini. Integrasi minimummu tinggal dua hal: buat payment, dengarkan webhook.

Kembali otomatis. Bila kamu mengisi return_url, halaman akan mengalihkan pelanggan kembali ke sistemmu 5 detik setelah pembayaran diterima (dengan hitung mundur dan tautan manual). Ini penting: tanpa itu, pelanggan sering membiarkan tab pembayaran terbuka dan tidak pernah melihat konfirmasi di sisimu, padahal dananya sudah masuk.

Dwibahasa. Halaman tampil dalam Bahasa Indonesia secara default; tambahkan ?lang=en pada hosted_url untuk versi Inggris, atau biarkan pelanggan memakai sakelar ID | EN di pojok kanan atas.

Siklus status

pending ──► paid ──► refunded
   ├──────► expired ──► paid   (bayar telat)
   └──────► failed

Hanya lima status, tidak ada yang keenam. Satu transisi yang perlu kamu antisipasi: expired bisa berubah menjadi paid. Nomor VA dan kode QR di sisi bank hidup lebih lama daripada masa berlaku tagihan, jadi pelanggan yang terlanjur menyalin nomornya kadang tetap membayar setelah tagihan kedaluwarsa. Uang yang sudah berpindah tetap kami kreditkan: webhook payment.paid terkirim seperti biasa (bisa jadi setelah kamu menerima payment.expired), dan pembayarannya ditandai flag bayar_telat. Kalau pesananmu sudah dibatalkan, gunakan flag itu untuk memutuskan: penuhi pesanannya, atau refund.

Kasus tak lazim dari penyedia masuk array flags; integrasi sederhana boleh mengabaikannya dan tetap benar. Nilai yang ada saat ini: bayar_ganda (pembayaran yang sama dibayar lewat dua instrumen berbeda, mis. pelanggan ganti metode lalu keduanya terbayar; dana tetap tercatat dan direkap, tidak ada yang hilang) dan bayar_telat (dibayar setelah kedaluwarsa, lihat di atas).

Membaca pembayaran

GET /v1/payments/{id}: satu pembayaran.
GET /v1/payments?reference=INV/001: cari berdasarkan referensimu.
GET /v1/payments?status=paid&limit=100: daftar, terbaru dulu.

Objek yang dikembalikan selalu berbentuk sama dengan respons create. Gunakan ini sebagai jaring pengaman (mis. cron rekonsiliasi); mekanisme utama pelunasan adalah webhook.

Refund

POST /v1/payments/{id}/refunds

curl -X POST https://pay.doit.id/v1/payments/pay_x8Kj2/refunds \
  -H "Authorization: Bearer pb_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rf-001" \
  -d '{"amount": 50000, "reason": "Kelebihan bayar"}'

amount opsional (default: penuh). Refund parsial boleh berulang sampai total = nominal asal. Hanya pembayaran berstatus paid yang bisa direfund.

Recurring Billing

Tagih pelanggan Anda berulang (langganan, iuran, cicilan) tanpa membuat tagihan manual tiap bulan. Anda mendefinisikan paket (nominal + interval), lalu melanggankan pelanggan. doit.id menerbitkan invoice otomatis pada jadwalnya dan mengirim webhook invoice.created berisi hosted_url.

Alur singkat:

1. Buat paket   POST /v1/billing/plans          (sekali)
2. Langgankan   POST /v1/billing/subscriptions  (per pelanggan)
3. doit.id menerbitkan invoice tiap periode -> webhook invoice.created
4. Anda kirim hosted_url ke pelanggan lewat kanal Anda
5. Pelanggan bayar -> webhook payment.paid (seperti biasa)

Paket (Plan)

POST /v1/billing/plans

curl -X POST https://pay.doit.id/v1/billing/plans \
  -H "Authorization: Bearer <api key>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: plan-internet-20" \
  -d '{"name":"Internet 20 Mbps","amount":150000,"interval":{"unit":"month","count":1}}'

GET /v1/billing/plans untuk daftar. PATCH /v1/billing/plans/{id} dengan {"active":false} menonaktifkan paket (langganan yang sudah ada berhenti diterbitkan invoice-nya, tapi tidak terhapus).

Langganan (Subscription)

POST /v1/billing/subscriptions: melanggankan satu pelanggan ke sebuah paket.

Respons 201 memuat langganan + first_invoice (payment lengkap dgn hosted_url) bila invoice pertama langsung terbit, jadi Anda bisa segera meneruskannya tanpa menunggu webhook.

Kelola: GET /v1/billing/subscriptions (filter ?status=active), GET /v1/billing/subscriptions/{id} (detail + daftar invoice-nya), dan POST .../{id}/pause · .../resume · .../cancel. Pause menahan penerbitan; resume melanjutkan dari periode berikutnya (tidak memuntahkan tagihan periode tertinggal); cancel permanen.

Menerima webhook

Set webhook URL per aplikasi di portal. Event dikirim sebagai POST JSON:

{
  "id": "evt_9aB3…",             // dedup dengan id ini
  "type": "payment.paid",
  "created_at": "2026-08-19T14:35:12.000Z",
  "data": { …objek payment utuh… }
}

Balas 2xx secepatnya (proses berat kerjakan async). Aturan yang menyelamatkan kamu dari insiden klasik:

• Dedup per id event: pengiriman minimal-sekali, duplikat mungkin terjadi.
• Jangan andalkan urutan tiba: nilai kebenaran ada di field status, bukan urutan.

Verifikasi signature

Setiap webhook membawa header PayBridge-Signature:

PayBridge-Signature: t=1755612912,v1=5f8a…

v1 = HMAC-SHA256(signing secret, t + "." + body). Signing secret ada di menu Developer. Node.js:

const crypto = require('node:crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(s => s.split('=')));
  const calc = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(calc));
}

PHP:

function verify(string $rawBody, string $header, string $secret): bool {
  parse_str(str_replace(',', '&', $header), $p);
  $calc = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
  return hash_equals($calc, $p['v1']);
}

Retry & replay

Webhook yang tidak dibalas 2xx diulang dengan backoff: 1m → 5m → 15m → 1j → 3j → 6j → 12j → 24j. Setelah itu masuk dead-letter dan bisa di-replay kapan pun dari halaman Webhook di portal, bersama seluruh riwayat pengiriman, status, dan jumlah percobaannya.

Embed checkout

Setiap payment sudah punya hosted_url: halaman bayar siap pakai. Dengan embed.js, halaman itu terbuka sebagai modal di situs Anda, jadi pelanggan membayar tanpa berpindah halaman. Tanpa dependensi, satu tag script.

<script src="https://doit.id/embed.js"></script>

<!-- cara 1: tanpa menulis JS: tautan biasa berisi hosted_url -->
<a href="https://pay.doit.id/p/pay_xxx" data-doit-checkout>Bayar</a>

<!-- cara 2: dari kode, dengan callback -->
<script>
doit.open('https://pay.doit.id/p/pay_xxx', {
  onPaid:    function (ev) { /* ev = {id, status, reference} */ },
  onExpired: function (ev) { /* tagihan kedaluwarsa/gagal */ },
  onClose:   function (ev) { /* modal ditutup; ev = status akhir atau null */ },
  closeDelay: 2500          // ms sebelum modal menutup sendiri setelah lunas
});
</script>

Saat tagihan mencapai status akhir, halaman bayar mengirim postMessage {source:'doit-checkout', id, status, reference} ke jendela induk; modal menutup sendiri setelah pelanggan melihat tanda lunas.

AI agent & MCP

Integrasi doit.id bisa dikerjakan (atau dipakai langsung) oleh AI agent:

Pasang MCP server:

# unduh
curl -O https://doit.id/mcp/doit-mcp.mjs

# konfigurasi Claude Code / Claude Desktop (mcpServers):
{
  "doit": {
    "command": "node",
    "args": ["/path/ke/doit-mcp.mjs"],
    "env": { "DOIT_API_KEY": "pb_test_xxx" }
  }
}

Tool yang tersedia: create_payment, get_payment, list_payments, create_billing_plan, list_billing_plans, create_subscription, get_subscription. Pakai key pb_test_ dulu; semua tool menghormati idempotency secara otomatis.

Kode error

Semua error berbentuk sama: code stabil untuk mesin, message menyebut nilai yang salah, doc_url menaut kemari:

{ "error": { "code": "…", "message": "…", "doc_url": "…" } }

Sandbox

Akun baru langsung berada di mode sandbox; tidak perlu menunggu apa pun untuk mulai menulis kode. Perilaku sandbox identik dengan produksi (endpoint, format, error), bedanya:

• Pembayaran tidak melibatkan dana riil.
• Pelunasan dipicu manual: buka pembayaran di portal → Simulasikan lunas, webhook payment.paid terkirim sungguhan ke server-mu.
• Jalan ke produksi dibuka lewat Onboarding: mandiri, tanpa menunggu review manual.

Mode kompat Duitku: migrasi tanpa mengubah kode

Sudah punya integrasi Duitku yang berjalan? Kamu tidak perlu menulis ulang apa pun. Aktifkan sendiri lewat portal: Developer → Aplikasi baru → jawab “Migrasi dari payment gateway existing?” dengan Duitku. Kredensialnya langsung tampil sekali, bersebelahan dengan API key. Sudah punya aplikasi dan belum memilihnya saat dibuat? Tetap bisa: tautan yang sama muncul di baris aplikasi setelah diaktifkan, dipakai untuk melihatnya lagi bila lupa disalin. doit.id menyediakan endpoint yang kompatibel dengan API Payment Gateway Duitku v2, cukup ganti tiga nilai di konfigurasi:

Yang ditiru persis: POST /webapi/api/merchant/v2/inquiry (signature MD5(merchantCode + merchantOrderId + paymentAmount + apiKey); respons berisi reference, paymentUrl, vaNumber, qrString), POST /webapi/api/merchant/transactionStatus, dan callback ke callbackUrl-mu dalam format form-urlencoded dengan signature MD5(merchantCode + amount + merchantOrderId + apiKey), rumus yang sama dengan yang sudah diverifikasi kodemu hari ini.

Pemetaan paymentMethod: kode VA (BC=BCA, M2=Mandiri, BR=BRI, I1=BNI, B1=CIMB, BT=Permata, VA=Maybank, NC=BNC, DM=Danamon, BV=BSI) → Virtual Account bank terkait; kode QRIS/e-wallet (SP, SA, NQ, DQ, OV, DA, LF, LA, dll.) → QRIS yang bisa dibayar semua aplikasi. paymentUrl mengarah ke halaman bayar hosted doit.id.

Field callback yang dipantulkan apa adanya

Seperti Duitku, callback memantulkan kembali nilai yang kamu kirim saat inquiry. Banyak sistem memakainya untuk mengenali tujuan pembayaran, jadi nilainya dikirim persis seperti diterima:

Isi additionalParam dan productDetails juga tampil di portal pada detail transaksi dan ikut tercari di kolom pencarian, sangat membantu tim keuangan mencocokkan pembayaran dengan tagihan, karena nomor referensi biasanya berupa angka yang tidak bermakna.

Mode kompat Xendit: Invoice API tetap hidup di sini

Xendit sedang memensiunkan Invoice API (legacy) dan meminta penggunanya menulis ulang ke Payment Session. Kalau sistemmu memakai POST /v2/invoices, di sini kode itu tetap jalan apa adanya; cukup ganti dua nilai konfigurasi. Aktifkan sendiri lewat portal: Developer → Aplikasi baru → jawab “Migrasi dari payment gateway existing?” dengan Xendit, dan isi URL callback sistem lamamu di kolom yang sama (wajib untuk Xendit; di dashboard mereka pun disetel sekali, bukan dikirim per request). Kredensialnya tampil sekali, bersebelahan dengan API key.

Yang ditiru, persis kontrak legacy:

Onboarding → live

Akses live tidak menunggu email atau rapat sign-off. Halaman Onboarding di portal berisi 8 butir yang tercentang otomatis dari bukti nyata saat integrasimu melakukannya di sandbox:

Delapan centang penuh → akses live terbuka detik itu juga: buat key pb_live_, ganti prefix key di konfigurasi, selesai.

Butir-butir ini bukan formalitas; mereka persis daftar penyebab insiden payment paling umum, jadi menyelesaikan onboarding berarti integrasimu sudah tahan di skenario yang biasanya baru ketahuan di produksi.

doit.id · pay.doit.id · Pertanyaan? care@idcloudhost.com