Menerima pembayaran di Indonesia: panduan untuk developer

QRIS adalah standar QR nasional Bank Indonesia. BI meluncurkannya pada 17 Agustus 2019 dan mewajibkan semua QR Code pembayaran memakai QRIS mulai 31 Desember 2019. Satu kode bisa dibayar dari aplikasi bank atau e-wallet mana pun yang terdaftar sebagai penerbit, dengan sumber dana berupa simpanan, kartu debet atau kredit, fasilitas kredit, atau uang elektronik, maksimal Rp10.000.000 per transaksi. Pada Merchant Presented Mode (MPM), pelangganlah yang memindai: QRIS statis dicetak sekali dan pelanggan mengetik nominalnya sendiri, sedangkan QRIS dinamis dibuat setelah merchant memasukkan nominal. Untuk aplikasi, pilih yang dinamis, karena setiap kode membawa nilai satu pesanan.

Virtual Account adalah andalan berikutnya: pelanggan mentransfer ke nomor yang diterbitkan khusus untuk pembayaran itu, lewat mobile banking, internet banking, atau ATM. E-wallet seperti GoPay, OVO, DANA, dan ShopeePay disetujui di dalam aplikasi dompetnya setelah redirect atau deeplink. Kartu hanya dipakai segelintir orang. Data Bank Dunia mencatat kepemilikan kartu kredit hanya 1,6 persen orang dewasa Indonesia pada 2021, dan Kartu Kredit Indonesia yang diluncurkan BI bersama ASPI pada 17 Agustus 2026 pun dibelanjakan lewat QRIS, dengan scan atau tap.

SNAP, Standar Nasional Open API Pembayaran, diatur dalam PADG 23/15/PADG/2021 yang ditetapkan pada 16 Agustus 2021. Cakupannya interkoneksi dan interoperabilitas, standar keamanan sistem informasi, tata kelola, dan manajemen risiko Open API Pembayaran, dengan spesifikasi untuk kategori registrasi, informasi saldo, informasi riwayat transaksi, transfer kredit, dan transfer debit. Penyedia Layanan wajib memindahkan API yang sudah berjalan ke SNAP paling lambat 30 Juni atau 31 Desember 2022, tergantung apakah mereka ikut menyusun standarnya, lalu mengintegrasikan pengguna layanannya paling lambat 30 Juni 2024, sedangkan UMKM dan lembaga nirlaba paling lambat 30 Juni 2025. Sejak 1 September 2023, pengelolaan SNAP dan Developer Site-nya dipegang ASPI.

Di kode, SNAP mudah dikenali. Spesifikasi Virtual Account dari ASPI mengelompokkan layanannya di bawah path transfer-va yang berversi (create-va, inquiry, payment, status), memakai header seperti X-TIMESTAMP, X-SIGNATURE, X-PARTNER-ID, X-EXTERNAL-ID, dan CHANNEL-ID, dan menyusun response code tujuh digit dari HTTP status, service code, dan case code, sehingga 2002400 berarti inquiry VA berhasil. Dokumentasi DOKU menunjukkan langkah signing-nya: HMAC-SHA512 dengan client secret sebagai kunci, atas method, path, access token, SHA-256 dari body yang di-minify, dan timestamp. Anda baru perlu menulis semua ini sendiri bila mengintegrasikan API SNAP milik bank atau endpoint SNAP milik gateway.

BI mewajibkan setiap Penyedia Jasa Pembayaran dan Lembaga Switching yang memproses transaksi QRIS memperoleh persetujuannya lebih dulu, jadi aplikasi merchant terhubung lewat acquirer atau gateway berizin, bukan bergabung langsung ke jaringannya. Xendit, Midtrans, dan DOKU masing-masing menyatukan QRIS, Virtual Account, e-wallet, dan kartu di balik satu API dan satu endpoint notifikasi. Integrasi langsung ke bank lewat SNAP cocok bagi bisnis yang sudah menjadi nasabah bank tersebut, dengan konsekuensi satu integrasi, satu set kredensial, dan satu siklus pengujian untuk setiap bank.

Harga QRIS diatur regulasi. Menurut BI, MDR ditanggung merchant dan tidak boleh dibebankan kepada konsumen. Dalam tabel yang berlaku sejak Maret 2025, usaha mikro dikenai 0% hingga Rp500.000 dan 0,3% di atasnya, merchant reguler lain 0,7%, pendidikan 0,6%, dan SPBU 0,4%. Mulai 1 Oktober 2026, BI memperluas MDR 0% ke usaha kecil, menengah, dan besar untuk transaksi hingga Rp100.000. Halaman QRIS BI masih menampilkan 0,7% rata untuk kategori itu saat dicek pada 12 Oktober 2026, jadi simpan kategori merchant dan ambang batasnya di konfigurasi, bukan di kode. Biaya gateway per metode pembayaran ada di halaman perbandingan biaya.

Konfirmasi pembayaran selalu asinkron, dan setiap gateway mengakui adanya notifikasi ganda. Midtrans menandatangani setiap notifikasi dengan SHA512 dari order_id, status_code, gross_amount, dan server key, mengulang pengiriman yang gagal paling banyak lima kali dalam rentang sekitar 2 hingga 210 menit, dan mengingatkan bahwa notifikasi settlement bisa tiba sebelum notifikasi pending. Xendit mengautentikasi lewat header x-callback-token, mengulang hingga enam kali dengan exponential backoff, dan tidak menjamin urutan. Aturan umumnya: verifikasi pengirim, balas 2xx secepatnya, dan buat pemrosesan idempoten berdasarkan ID pembayaran atau order dari provider.

Rekonsiliasi adalah pekerjaan tersendiri, karena dana masuk setelah webhook. Xendit mencantumkan settlement QRIS pada T+1 hari kerja dan mencatat bahwa refund QRIS bergantung pada penerbitnya: GoPay hanya menerima refund penuh. Pelanggan umumnya bisa mengajukan sengketa QRIS lewat penerbitnya dalam 90 hari. Simpan referensi provider di baris invoice agar setiap baris settlement bisa dicocokkan.

QRIS dan Virtual Account adalah pembayaran push: pelanggan yang memulai setiap transfer, dan Xendit menandai keduanya tidak mendukung merchant-initiated transaction. Tagihan terjadwal butuh instrumen yang sudah di-tokenisasi. Kartu memenuhi syarat, begitu juga e-wallet yang sudah ditautkan: Xendit mencantumkan pembayaran tersimpan yang bisa dipicu merchant untuk OVO, DANA, ShopeePay, dan channel GoPay recurring yang memerlukan aktivasi tambahan. Subscription API Midtrans hanya menerima credit_card dan gopay dalam IDR, dan secara default mencoba ulang tagihan yang gagal tiga kali dengan jeda satu jam. DOKU mendokumentasikan skema direct debit recurring untuk BRI.

Pelanggan lainnya memperpanjang lewat invoice: QRIS atau Virtual Account baru di setiap siklus, dikirim sebelum periode berakhir, dan webhook-lah yang memperpanjang akses. Modelkan status past due dan masa tenggang secara eksplisit, karena kegagalan yang paling umum adalah pelanggan yang belum membayar, bukan penolakan kartu yang bisa dicoba ulang.

Provider tidak seragam dalam menuliskan nominal. Midtrans mendefinisikan gross_amount sebagai integer di skema request, tetapi mengembalikannya sebagai string dua desimal seperti 275000.00. Xendit memublikasikan rentang nominal per channel, dari Rp1 sampai Rp10.000.000 untuk QRIS. Simpan rupiah sebagai integer, parse setiap string dari provider secara eksplisit di batas sistem, dan pisahkan nominal bruto, biaya, dan nominal settlement ke kolom masing-masing, karena jumlah yang masuk tidak akan sama dengan total invoice.