Membuat QRIS Dinamis lewat API

QRIS sudah menjadi cara bayar sehari-hari di Indonesia, dari warung kopi sampai toko online. Bagi developer, pertanyaannya bukan lagi "apakah perlu QRIS", melainkan "bagaimana menghasilkan QRIS yang benar dari aplikasi saya". Jawabannya adalah QRIS dinamis lewat API: setiap transaksi menghasilkan kode QR baru dengan nominal yang sudah terkunci, sehingga pelanggan cukup memindai dan membayar tanpa mengetik ulang jumlah. Artikel ini membahas alur teknis membuat QRIS dinamis via API secara praktis, mulai dari konsep sampai penanganan kasus tepi yang sering terlewat.

Perbedaan QRIS Statis dan Dinamis

Sebelum masuk ke API, penting memahami mengapa dinamis lebih cocok untuk integrasi otomatis.

• QRIS statis adalah satu kode QR tetap yang ditempel di meja kasir. Nominal diketik manual oleh pembeli. Cocok untuk toko fisik sederhana, tetapi rawan salah ketik dan sulit direkonsiliasi otomatis.
• QRIS dinamis dibuat per transaksi. Nominal sudah tertanam di dalam kode, sering kali punya masa berlaku (expiry), dan membawa identitas transaksi yang membuat rekonsiliasi otomatis jadi mungkin.

Untuk aplikasi dan sistem, QRIS dinamis hampir selalu pilihan yang tepat karena menghilangkan risiko salah nominal dan memudahkan pelacakan. Perbandingan lengkapnya bisa Anda baca di QRIS statis vs dinamis.

Keunggulan lain QRIS dinamis untuk integrasi adalah kemampuannya membawa identitas transaksi di dalam payload. Karena setiap QR terikat pada satu order, sistem Anda bisa langsung memetakan pembayaran yang masuk ke pesanan yang benar tanpa menebak-nebak. Inilah yang membuat rekonsiliasi otomatis menjadi mungkin dan menjadikan QRIS dinamis lebih ramah bagi checkout digital, pembayaran invoice, hingga aplikasi mobile.

Alur Dasar Membuat QRIS Dinamis lewat API

Secara garis besar, membuat QRIS dinamis mengikuti pola "charge" yang serupa di banyak payment gateway:

1. Server Anda mengirim permintaan ke endpoint pembuatan transaksi (charge) dengan menyertakan nominal, mata uang, ID pesanan internal Anda, dan metode QRIS.
2. Payment gateway mengembalikan data QR, biasanya berupa string QR (payload EMV) dan/atau URL gambar QR, plus ID transaksi dan waktu kedaluwarsa.
3. Aplikasi Anda menampilkan QR tersebut kepada pelanggan, entah sebagai gambar atau dirender dari string QR di sisi klien.
4. Pelanggan memindai dan membayar menggunakan aplikasi bank atau e-wallet apa pun yang mendukung QRIS.
5. Gateway mengirim notifikasi ke server Anda saat pembayaran berhasil.

Poin penting bagi developer: jangan pernah membuat charge dari sisi frontend. Permintaan pembuatan transaksi harus berasal dari server Anda agar API key tetap aman. Praktik menjaga kredensial ini dibahas di keamanan API key.

Satu detail teknis yang layak dicatat: ketika menampilkan QR, Anda punya dua opsi. Jika gateway memberi URL gambar, Anda tinggal memasangnya sebagai elemen gambar. Jika gateway hanya memberi string QR (payload EMV), Anda perlu merender string tersebut menjadi kode QR di sisi klien memakai pustaka QR generator. Pendekatan string lebih fleksibel karena Anda mengontrol ukuran dan gaya tampilan, tetapi pastikan payload dirender apa adanya tanpa modifikasi, karena satu karakter yang salah membuat QR gagal dipindai.

Menangani Notifikasi Pembayaran dengan Webhook

Menampilkan QR hanyalah setengah cerita. Bagian yang menentukan keandalan sistem adalah bagaimana Anda tahu pembayaran sudah lunas. Ada dua cara: polling status secara berkala, atau menerima webhook dari gateway. Webhook jauh lebih efisien dan real-time.

Saat pelanggan membayar, gateway akan mengirim HTTP request ke URL webhook Anda berisi status transaksi. Beberapa hal yang wajib diperhatikan:

• Verifikasi keaslian. Pastikan notifikasi benar-benar datang dari gateway, biasanya lewat tanda tangan (signature) atau token. Jangan langsung percaya body request mentah.
• Idempotensi. Gateway bisa mengirim notifikasi yang sama lebih dari sekali. Sistem Anda harus aman meski menerima duplikat, jangan sampai satu pesanan diproses dua kali. Konsep ini diulas di idempotency API pembayaran.
• Respons cepat. Balas webhook dengan status sukses secepatnya, lalu proses logika berat (kirim email, update stok) secara asinkron bila perlu.

Untuk memahami pola implementasi webhook secara menyeluruh, webhook pembayaran menjelaskan alur end-to-end yang bisa Anda jadikan acuan.

Kasus Tepi yang Sering Terlewat

QRIS dinamis punya beberapa jebakan yang baru terasa saat sudah di produksi. Antisipasi hal-hal berikut:

• Kedaluwarsa QR. QRIS dinamis punya masa berlaku. Jika pelanggan membuka halaman pembayaran terlalu lama, QR bisa kedaluwarsa. Tampilkan hitung mundur dan sediakan tombol "buat ulang QR".
• Pembayaran setelah kedaluwarsa. Ada kemungkinan pelanggan tetap membayar tepat saat batas waktu. Pastikan logika Anda menangani status akhir berdasarkan notifikasi gateway, bukan asumsi timer di frontend.
• Nominal minimum dan maksimum. QRIS punya batas transaksi tertentu. Validasi nominal sebelum membuat charge agar tidak gagal di tengah jalan. Batasan ini dibahas di limit transaksi QRIS.
• Sandbox dulu, produksi kemudian. Sebelum go-live, uji seluruh alur di lingkungan sandbox. Di sandbox, string QR sering hanya berupa placeholder dan tidak bisa dipindai sungguhan, jadi verifikasi lewat simulasi pembayaran. Panduannya ada di uji pembayaran sandbox.

Menyiapkan penanganan kasus tepi sejak awal akan menyelamatkan Anda dari keluhan pelanggan "sudah bayar tapi status belum berubah".

Satu prinsip yang perlu dipegang teguh: sumber kebenaran status pembayaran adalah gateway, bukan tampilan di layar pelanggan. Timer di frontend hanya untuk pengalaman pengguna; keputusan apakah pesanan lunas atau tidak harus selalu mengacu pada notifikasi resmi. Simpan status setiap transaksi di basis data Anda dan perbarui hanya berdasarkan data yang terverifikasi. Cara menyimpan status pembayaran secara aman dibahas di menyimpan status pembayaran. Dengan begitu, meski pelanggan menutup tab atau kehilangan koneksi, Anda tetap bisa menyelesaikan pesanan begitu dana benar-benar diterima.

Posisi BorderPay dalam Integrasi QRIS

BorderPay adalah lapisan teknologi (software) di atas mitra Payment Gateway yang berlisensi Bank Indonesia; pemrosesan dan penyimpanan dana dilakukan oleh mitra berlisensi. Untuk developer, ini berarti Anda memanggil API BorderPay untuk membuat charge QRIS dinamis, menerima webhook saat lunas, dan mengelola status transaksi, sementara pemrosesan dana yang diatur regulator tetap ditangani mitra berizin. Anda mendapat antarmuka yang konsisten tanpa harus mengurus banyak koneksi teknis sendiri.

Membuat QRIS dinamis lewat API sebenarnya sederhana secara konsep, tetapi keandalannya ditentukan oleh detail: verifikasi webhook, idempotensi, dan penanganan kedaluwarsa. Jika Anda ingin memulai dengan alur yang sudah rapi dan dokumentasi yang jujur soal batasannya, BorderPay bisa menjadi titik awal yang praktis untuk membangun pengalaman pembayaran QRIS di produk Anda.