Direct API

Endpoint yang sama dengan Checkout, POST /v1/transactions. Bedanya di field yang Anda pakai: bukannya me-redirect pembeli ke checkout_url, Anda membaca payload pembayarannya dan membuat tampilannya sendiri. Desain, copy, dan error state sepenuhnya di tangan Anda.

Satu endpoint, bukan satu per metode

Kalau pernah integrasi payment gateway lain, Anda mungkin mengira ada endpoint terpisah per metode — satu path untuk membuat virtual account, satu untuk generate QR, satu lagi untuk charge kartu. Memang begitu standar jalur bank di belakangnya, dan itu sebabnya menambah metode di integrasi seperti itu selalu berarti menulis kode baru.

Di sini semua metode pakai POST /v1/transactions. Metode adalah nilai yang Anda kirim, bukan path yang Anda panggil, dan perbedaannya ada di object payment pada response. Urusan tiap jalur bank kami kerjakan di balik satu endpoint itu, jadi menambah metode di integrasi Anda paling banyak cuma satu cabang kode.

Pengecualiannya adalah operasi yang berbeda, bukan metode yang berbeda: GET /v1/payment_methods untuk melihat metode yang bisa diterima akun Anda, dan POST /v1/refunds — yang hanya didukung sebagian metode, dan menjawab 422 dengan kode yang jelas untuk metode lainnya.

Minta satu metode

Kirim payment_methods berisi satu kode — ["va_bca"] — dan response-nya langsung membawa object payment metode itu, tanpa ada yang perlu dipilih pembeli. Kalau kirim beberapa kode, berarti Anda sendiri yang membuat pilihan metodenya, dari GET /v1/payment_methods.

Tiga format, berapa pun metodenya

Berapa pun metode yang kami dukung, pembayaran hanya tampil dalam salah satu dari tiga format. Tangani tiga format itu, dan daftar metodenya bisa bertambah tanpa mengubah kode Anda.

// A Direct API integration is one switch, and it stays one
// switch as methods are added.
switch (trx.payment.type) {
  case "qr":           return <Qr value={trx.payment.qr_string} />;
  case "payment_code": return <Code value={trx.payment.payment_code} />;
  case "redirect":     return redirect(trx.payment.redirect_url);
}

Data pembeli, Anda yang kumpulkan

Tidak ada halaman dari kami yang bisa menanyakan apa pun ke pembeli, jadi data pembeli yang dibutuhkan metode harus ikut di customer saat create. Create dengan metode yang field wajibnya kosong ditolak 422 beserta nama field-nya — lihat metode pembayaran untuk data yang dibutuhkan tiap metode. Kalau tidak mau bikin form itu sendiri, Checkout yang mengumpulkannya untuk Anda.

Yang jadi tanggung jawab Anda

• Masa berlaku. Sembunyikan pembayarannya saat expires_at dan buat permintaan pembayaran baru kalau pembeli masih mau bayar. Kode atau QR yang dipakai setelah itu gagal di bank, bukan di kami.
• Instruksi. Setiap response membawa blok instructions yang ditulis untuk pembeli dalam bahasa Indonesia. Tampilkan apa adanya, jangan tulis versi sendiri — ini bedanya pembeli yang langsung bayar dan pembeli yang menelepon Anda.
• Metode baru. Metode dengan format yang belum Anda implementasikan tidak akan tampil. Setiap format baru butuh satu cabang kode; metode baru dengan format yang sudah ada tidak butuh apa-apa.

Konfirmasi pembayaran

Sama persis dengan Checkout: tunggu webhook payment.paid, atau polling GET /v1/transactions/:id. Apa pun yang tampil di layar pembeli bukan bukti pembayaran — yang jadi bukti hanya data di sistem kami.