Panduan Integrasi API Pembayaran untuk Developer Indonesia

Membangun integrasi pembayaran yang rapi tidak harus rumit. Jika Anda seorang developer yang ingin menerima pembayaran di aplikasi, situs, atau sistem internal, panduan ini menjelaskan alur dasar API pembayaran Indonesia menggunakan BorderPay: mulai dari autentikasi dengan API key, membuat transaksi, mengecek status, hingga menangani webhook secara aman. BorderPay menyediakan REST API sederhana di atas mitra Payment Gateway yang berlisensi Bank Indonesia, jadi Anda cukup fokus menulis kode—urusan pemrosesan dan penyimpanan dana ditangani mitra berlisensi tersebut.

Sebelum masuk ke detail, satu catatan penting: BorderPay adalah lapisan teknologi (software), bukan payment gateway atau PJP sendiri. Metode pembayaran yang tersedia saat ini adalah QRIS dan Virtual Account (VA). Untuk referensi teknis lengkap dan contoh payload terbaru, selalu rujuk dokumentasi resmi.

Kenapa memakai REST API pembayaran

BorderPay menawarkan beberapa cara integrasi, jadi Anda bisa memilih yang paling sesuai dengan kebutuhan tim:

• Buat link manual dari dashboard — cocok untuk menagih tanpa menulis kode sama sekali.
• Payment link — bagikan tautan bayar ke pelanggan lewat chat, email, atau media sosial.
• Embed Checkout — tempel satu snippet untuk memunculkan halaman bayar di situs Anda.
• REST API — kontrol penuh dan otomatis, untuk integrasi ke dalam sistem sendiri.

Pendekatan REST API cocok ketika Anda butuh kontrol penuh—misalnya membuat transaksi secara programatik, menyimpan status ke database sendiri, atau mencocokkan pembayaran dengan pesanan di sistem Anda. Jika kebutuhan Anda lebih ringan dan tidak ingin banyak menulis kode, Embed Checkout atau payment link biasanya sudah cukup sebagai jalan tengah yang praktis.

Kabar baiknya, Anda bisa mulai mengoprek REST API sejak hari pertama lewat mode test/sandbox—integrasi dan uji coba di sandbox bisa berjalan cepat tanpa menunggu apa pun. Namun untuk go-live dan menerima uang sungguhan, akun wajib menyelesaikan proses KYC terlebih dahulu, dan proses verifikasi itu mengikuti alurnya sendiri.

Langkah 1: Autentikasi dengan API key

Setiap permintaan ke REST API BorderPay diautentikasi menggunakan API key. Anda akan mendapatkan pasangan key untuk mode test dan mode live. Gunakan key mode test selama pengembangan, lalu ganti ke key live setelah siap dan KYC selesai. Praktik menyimpan dan merotasi kunci ini dengan aman dibahas di keamanan API key.

Prinsip keamanan yang wajib dipatuhi:

• Simpan API key di sisi server, jangan pernah di kode frontend, aplikasi mobile, atau repository publik.
• Gunakan variabel lingkungan (environment variable), bukan hardcode di dalam kode.
• Kirim key lewat header Authorization pada setiap request, selalu di atas koneksi HTTPS.

Karena key inilah yang mewakili identitas merchant Anda, kebocorannya setara dengan memberi orang lain akses ke akun. Perlakukan API key seperti kata sandi: rahasiakan, rotasi bila dicurigai bocor, dan batasi siapa yang bisa mengaksesnya.

Langkah 2: Menemukan metode pembayaran yang tersedia

Sebelum membuat transaksi, Anda bisa memanggil endpoint discovery GET /payment-methods. Endpoint ini mengembalikan daftar metode yang aktif untuk akun Anda—misalnya QRIS dan daftar bank VA yang didukung. Pendekatan ini membuat integrasi Anda tahan perubahan: ketika ada metode baru diaktifkan, kode Anda bisa menyesuaikan tanpa perlu di-hardcode satu per satu.

Bila Anda masih menimbang mau menawarkan metode apa ke pelanggan, dua artikel ini membantu membandingkan pilihan: QRIS vs Virtual Account dan apa itu Virtual Account.

Langkah 3: Membuat pembayaran

Untuk membuat transaksi, kirim permintaan POST ke endpoint pembuatan pembayaran dengan data inti seperti:

• amount — nominal yang harus dibayar.
• payment method — QRIS atau VA (beserta bank tujuan bila VA).
• reference/order id — ID pesanan dari sistem Anda, untuk pencocokan nanti.
• customer info — opsional, sesuai kebutuhan.

Respons akan berisi objek pembayaran lengkap dengan id transaksi, status awal (biasanya pending), serta instruksi bayar—misalnya string QRIS untuk ditampilkan sebagai kode QR, atau nomor Virtual Account beserta bank tujuan.

Perhatikan masa berlaku instruksi bayar:

Karena tidak ada mekanisme bayar-telat, tampilkan hitung mundur atau tanggal kedaluwarsa ke pelanggan agar mereka membayar tepat waktu. Jika lewat batas, buat transaksi baru. Untuk memahami perbedaan QRIS statis dan dinamis dalam konteks ini, lihat QRIS statis vs dinamis.

Idempotensi saat membuat transaksi

Jaringan bisa timeout atau retry otomatis mengirim permintaan dua kali. Agar tidak membuat dua tagihan untuk satu pesanan, terapkan pola idempotensi—kirim kunci unik per pesanan (misalnya order id) sehingga permintaan yang sama tidak menghasilkan transaksi ganda. Simpan pemetaan antara order id dan id transaksi di database Anda, lalu periksa dulu sebelum membuat transaksi baru.

Langkah 4: Mengecek status pembayaran

Ada dua cara mengetahui apakah pembayaran sudah lunas:

1. Polling — panggil endpoint status transaksi dengan id yang Anda terima saat pembuatan. Cocok untuk pengecekan sesekali, misalnya saat pelanggan kembali ke halaman "cek status".
2. Webhook — biarkan BorderPay memberi tahu Anda begitu status berubah. Ini cara yang direkomendasikan karena mendekati real-time dan hemat request.

Sebisa mungkin, jadikan webhook sebagai sumber kebenaran untuk perubahan status, dan gunakan polling hanya sebagai cadangan. Hindari bergantung sepenuhnya pada polling ketat karena boros request dan lambat memantulkan perubahan status.

Langkah 5: Menangani webhook dengan aman

Webhook adalah notifikasi HTTP yang dikirim BorderPay ke URL endpoint Anda ketika terjadi peristiwa penting. Event yang perlu Anda tangani antara lain:

• payment.paid — pembayaran berhasil dan terkonfirmasi.
• payment.expired — transaksi kedaluwarsa sebelum dibayar.
• payment.failed — pembayaran gagal.

Setiap notifikasi ditandatangani dengan HMAC. Berikut praktik wajib di sisi merchant:

1. Verifikasi tanda tangan HMAC setiap payload sebelum memprosesnya, untuk memastikan notifikasi benar-benar dari BorderPay dan tidak dipalsukan.
2. Terapkan idempotensi — satu event bisa terkirim lebih dari sekali (misalnya karena retry). Simpan id event/transaksi yang sudah diproses, lalu abaikan duplikat agar Anda tidak, misalnya, mengirim barang dua kali.
3. Balas cepat dengan HTTP 2xx. Lakukan pekerjaan berat (kirim email, update stok) secara asinkron agar respons webhook tidak lambat.
4. Jangan percaya nominal dari klien—selalu cocokkan amount dan order id pada payload webhook dengan catatan di database Anda.

BorderPay menyimpan log pengiriman webhook dan mendukung kirim ulang, sehingga bila endpoint Anda sempat down, Anda tetap punya jejak dan bisa memulihkan status. Uji handler webhook Anda menghadapi ketiga event di atas sejak awal, bukan hanya jalur sukses.

Menguji sebelum go-live

Manfaatkan mode test/sandbox untuk menjalankan seluruh alur—buat transaksi, simulasikan pembayaran, dan pastikan endpoint webhook Anda menerima serta memverifikasi event dengan benar. Uji juga skenario expired dan failed, bukan hanya jalur sukses, supaya sistem Anda siap menghadapi kondisi nyata.

Setelah alur test lancar, selesaikan KYC untuk mengaktifkan mode live. Perlu diingat, hanya bagian integrasi dan sandbox yang bisa selesai cepat; verifikasi KYC untuk menerima uang sungguhan mengikuti prosesnya sendiri dan tidak instan.

Setelah pembayaran: settlement dan penarikan

Ketika transaksi lunas, dana tidak langsung bisa ditarik. Dana tertahan sebentar lalu tersedia sesuai jadwal per metode, mengikuti hari kerja dan melewati akhir pekan serta libur nasional. Status dan tanggal ketersediaan tampil di dashboard, jadi Anda selalu tahu kapan saldo bisa dicairkan.

Untuk mencairkan saldo, penarikan diproses otomatis ke rekening bank Indonesia dengan biaya per penarikan; bila penarikan gagal, saldo dikembalikan penuh. BorderPay tidak memungut biaya pendaftaran maupun langganan—biaya hanya muncul saat transaksi. Rincian biaya bisa Anda lihat di halaman pricing.

Ringkasan alur integrasi

1. Simpan API key dengan aman di server, mulai dengan mode test.
2. Panggil GET /payment-methods untuk discovery metode aktif.
3. Buat pembayaran via POST, tampilkan QRIS/VA ke pelanggan, hormati masa berlaku.
4. Cek status lewat webhook (utama) atau polling (cadangan).
5. Verifikasi HMAC + idempotensi di handler webhook Anda.
6. Uji end-to-end di sandbox, selesaikan KYC, lalu go-live.

Dengan pola di atas, integrasi Anda akan tahan terhadap retry, aman dari pemalsuan notifikasi, dan mudah dirawat. Mulai baca dokumentasi, cek FAQ bila ada pertanyaan, atau langsung daftar untuk mendapatkan API key mode test dan mencoba sendiri.