Daftar isi

Alur integrasi

Gambaran urutan panggilan untuk satu siklus tagih-bayar, dari membuat pelanggan sampai menandai invoice lunas di sistem Anda.

Satu siklus tagih-bayar

  1. Buat pelanggan lewat POST /v1/customers, atau pakai id pelanggan yang sudah ada.
  2. Buat invoice lewat POST /v1/invoices, sertakan externalId berisi nomor order atau referensi transaksi di sistem Anda sendiri.
  3. Terbitkan link pembayaran lewat POST /v1/invoices/{id}/payment-link untuk mendapatkan URL pembayaran dan nomor Virtual Account.
  4. Kirim tautan pembayaran itu kepada pembayar — lewat WhatsApp, email, atau kanal lain.
  5. Terima notifikasi payment.received dan invoice.paid lewat webhook begitu pembayar menyelesaikan pembayaran.
  6. Tandai invoice lunas di sistem Anda berdasarkan notifikasi webhook yang diterima.

Webhook vs. polling

Pakai webhook sebagai jalur utama: begitu pembayaran masuk, TagihanDigital langsung mengirim event ke URL webhook Anda, jadi sistem Anda bisa bereaksi seketika tanpa menanyai API berulang kali. Pakai polling ke GET /v1/invoices/external/{externalId} sebagai jaring pengaman — misalnya dijalankan berkala setiap beberapa menit — untuk kasus webhook Anda sempat down, request-nya gagal terkirim, atau server Anda belum sempat memproses event yang masuk. Jangan mengandalkan salah satunya saja: webhook untuk kecepatan, polling untuk kepastian.

Rekonsiliasi dengan externalId

externalId adalah kunci yang menghubungkan invoice di TagihanDigital dengan order atau transaksi di sistem Anda sendiri, dan nilainya wajib unik per organisasi. Pakai field ini — bukan id internal kami — sebagai acuan saat mencocokkan status pembayaran, baik dari payload webhook maupun dari hasil polling, sehingga proses rekonsiliasi di sistem Anda tetap konsisten meskipun request pembuatan invoice pernah diulang karena timeout.