Blog

Integrasi API QRIS: Alur, Keamanan, dan Checklist Teknis

Posted by

On Juli 31, 2026

Jawaban singkat: integrasi API QRIS menghubungkan sistem order dengan penyedia pembayaran untuk membuat QR dinamis, menerima perubahan status, dan merekonsiliasi transaksi secara otomatis. Implementasi yang aman tidak berhenti saat QR tampil: aplikasi harus memverifikasi callback, mencegah proses ganda dengan idempotency, menangani kedaluwarsa, dan menguji seluruh alur di sandbox.

Kalau kamu sedang menyusun backlog integrasi, panduan ini memberi peta dari pembuatan order sampai rekonsiliasi, tanpa mengarang endpoint atau payload Ezeelink. Kamu juga mendapat sequence table, matriks status, checklist keamanan, skenario pengujian, serta gate go-live yang bisa dipakai bersama tim produk dan engineering.

Laptop merchant menampilkan integrasi API QRIS dengan pembayaran berhasil — Integrasi QRIS yang andal menghubungkan order, pembayaran, verifikasi webhook, penyimpanan status, dan rekonsiliasi.

Apa Itu Integrasi API QRIS?

Integrasi API QRIS adalah pertukaran data terstruktur antara sistem bisnis dan PJP untuk mengelola siklus pembayaran QRIS. Sistem bisnis mengirim permintaan pembuatan transaksi, menerima data QR, memantau status, lalu mencocokkan hasil pembayaran dengan order internal.

Dalam konteks Indonesia, Standar Nasional Open API Pembayaran (SNAP) mendefinisikan API sebagai protokol dan instruksi yang memfasilitasi interkoneksi antaraplikasi. SNAP bertujuan mendorong integrasi, interoperabilitas, keamanan, dan keandalan infrastruktur pembayaran. Detail kontrak teknis tetap mengikuti dokumentasi penyedia yang dipilih.

Pada rantai QRIS, issuer melayani sumber dana pengguna, acquirer melayani merchant, dan ASPI mendukung standar industri di bawah kerangka Bank Indonesia. Sistem dapat menerima pembayaran dari BCA, BRI, Mandiri, BNI, GoPay, DANA, OVO, atau e-wallet lain secara interoperable. Namun, integrasi API bisnis tetap terhubung ke PJP yang memiliki kontrak, credential, status, MDR, dan mekanisme settlement sendiri.

Bila bisnis belum membutuhkan integrasi langsung, payment link bisa menjadi jalur yang lebih ringan. API menjadi pilihan tepat ketika order, status, dan rekonsiliasi perlu terhubung otomatis dengan website, aplikasi, POS, atau sistem internal.

Bisnis yang belum memiliki akun merchant perlu menyelesaikan onboarding lebih dahulu; gunakan panduan cara punya QRIS untuk memahami tahap dasarnya. Ketersediaan API, sandbox, credential, dan kontrak teknis tetap harus dikonfirmasi langsung kepada PJP yang dipilih.

Apa Bedanya QRIS Statis dan Dinamis untuk Integrasi?

Perbandingan QRIS statis dan QRIS dinamis untuk integrasi API — QRIS dinamis membawa konteks transaksi yang lebih terstruktur, sedangkan QRIS statis mengandalkan input dan pencocokan tambahan.

QRIS statis memakai kode yang sama dan biasanya mengandalkan input nominal, sedangkan QRIS dinamis dibuat untuk transaksi tertentu dengan nominal dan identitas order. Untuk integrasi website, QR dinamis lebih mudah dipetakan ke satu checkout karena sistem memiliki referensi yang jelas.

Aspek	QRIS statis	QRIS dinamis
Kode QR	Dipakai berulang	Dibuat per order/transaksi
Nominal	Sering diinput pembayar	Ditetapkan dari order
Korelasi order	Perlu pencocokan tambahan	Lebih langsung melalui ID order
Kedaluwarsa	Tidak terkait order tertentu	Umumnya memiliki masa berlaku
Cocok untuk	Kasir sederhana/offline	Checkout web, aplikasi, POS terintegrasi

Pilihan arsitektur: Jangan memilih QR dinamis hanya karena lebih modern. Gunakan ketika manfaat korelasi order, otomatisasi status, dan rekonsiliasi memang sepadan dengan biaya engineering.

Bagaimana Alur Request sampai Status Pembayaran?

Alur API: request QR, callback, status paid — Backend merchant harus menyimpan referensi transaksi dan memverifikasi pembaruan status sebelum memenuhi pesanan.

Alur aman memisahkan status order bisnis dari status pembayaran provider, lalu menyinkronkannya melalui referensi yang stabil. Browser pengguna tidak boleh menjadi satu-satunya sumber kebenaran karena tab dapat ditutup sebelum redirect selesai.

Urutan	Komponen	Aksi	Kontrol penting
1	Checkout	Membuat order internal	ID unik dan nominal final
2	Backend bisnis	Meminta transaksi QR	Autentikasi server-to-server
3	Provider	Mengembalikan data QR dan expiry	Validasi respons sebelum disimpan
4	Frontend	Menampilkan QR dan penghitung waktu	Tidak menyimpan secret
5	Provider → webhook	Mengirim perubahan status	Signature, timestamp, replay check
6	Backend	Memperbarui order secara idempotent	State transition yang sah
7	Rekonsiliasi	Mencocokkan laporan dan database	Exception queue dan audit log

Kalau webhook terlambat, backend dapat melakukan pengecekan status sesuai kebijakan provider, bukan polling tanpa batas. Terapkan backoff, timeout, dan batas percobaan. Untuk transaksi yang belum jelas, jangan otomatis membuat QR baru dengan order yang sama tanpa strategi idempotency.

Komponen API Apa yang Dibutuhkan?

Empat komponen API QRIS: auth, generate QR, webhook, rekonsiliasi — Pisahkan antarmuka pelanggan, logika backend, penerimaan webhook, penyimpanan transaksi, dan proses rekonsiliasi.

Minimalnya, integrasi membutuhkan fungsi pembuatan transaksi, pembacaan status, penerimaan webhook, dan rekonsiliasi. Nama endpoint, header, serta payload berbeda antar penyedia; artikel ini sengaja memakai istilah konseptual agar tidak dijadikanmenyamar sebagai dokumentasi produk.

Create transaction: menerima ID order, nominal, deskripsi, dan masa berlaku.
Payment status: membaca status provider untuk satu referensi transaksi.
Webhook/callback receiver: menerima notifikasi perubahan status dari server provider.
Cancel/expire handling: menutup order yang tidak dibayar tanpa menghapus audit trail.
Refund/dispute workflow: bila didukung, harus dipisahkan dari alur pembayaran awal.
Settlement/reconciliation report: mencocokkan transaksi berhasil dengan pencairan.
Credential management: menyimpan key/secret di secret manager, bukan frontend atau repositori.

Jika bisnis juga menerima rekening virtual, pelajari konsep virtual account agar model status dan rekonsiliasinya tidak dicampur mentah dengan QRIS. Satu order boleh menawarkan beberapa metode, tetapi hanya satu jalur pembayaran yang boleh menutup order.

Bagaimana Mengamankan Webhook dan Callback?

Keamanan webhook: HTTPS, verifikasi signature, idempotency key — Webhook tidak boleh dipercaya hanya karena mencapai endpoint; autentikasi, validasi, idempotency, dan audit log tetap diperlukan.

Webhook harus diperlakukan sebagai input eksternal yang tidak dipercaya sampai lolos verifikasi. Jangan mengubah order menjadi “paid” hanya karena menerima JSON dengan status sukses! Periksa signature sesuai dokumentasi provider, timestamp, referensi, nominal, dan state order.

OWASP menempatkan risiko seperti broken authentication, security misconfiguration, dan unsafe consumption dalam API Security Top 10 2023. Bagi integrasi pembayaran, prinsip praktisnya adalah memverifikasi pihak pengirim dan tetap memvalidasi data dari layanan tepercaya.

Terima webhook hanya melalui HTTPS dan batasi metode HTTP yang diizinkan.
Verifikasi signature memakai algoritma serta canonical string resmi provider.
Periksa timestamp dan nonce/event ID untuk mengurangi replay.
Cocokkan ID transaksi, nominal, mata uang, merchant, dan status sebelumnya.
Terapkan idempotency: event yang sama boleh diterima ulang, tetapi efek bisnis hanya sekali.
Balas cepat setelah event tersimpan; proses berat dijalankan melalui antrean.
Simpan audit log tanpa menulis secret, token, atau data sensitif ke log aplikasi.

Fact lock: Contoh signature, nama header, endpoint, dan masa toleransi timestamp harus diambil dari dokumentasi provider yang disetujui tim teknis—bukan dikarang untuk artikel.

Bagaimana Menyusun Sandbox dan Skenario Testing?

Checklist go-live API QRIS: sandbox, signature, recon, monitoring, rollback, production key — Uji jalur normal dan kegagalan agar sistem tidak menggandakan order atau menandai pembayaran sebelum status terverifikasi.

Sandbox harus menguji state transition dan kegagalan. Bukan hanya demo pembayaran berhasil. Buat data uji yang terisolasi, gunakan credential khusus sandbox, dan pastikan tidak ada transaksi produksi yang tersambung ke environment pengembangan.

Skenario	Ekspektasi	Bukti lulus
Pembayaran berhasil	Order berubah sekali menjadi paid	Event, referensi, waktu tercatat
QR kedaluwarsa	Order tetap unpaid/expired	Tidak ada fulfilment
Webhook dikirim ulang	Tidak ada efek ganda	Idempotency key/event ID sama
Signature salah	Request ditolak dan dicatat	Tidak mengubah order
Nominal tidak cocok	Masuk exception queue	Alert dan investigasi
Webhook terlambat	State tetap konsisten	Rekonsiliasi memperbaiki selisih
Provider timeout	Retry dengan backoff	Tidak membuat order ganda

Tambahkan test untuk zona waktu, format desimal, jaringan lambat, dan deployment rollback. Tim QA perlu mengetahui mana skenario yang dapat disimulasikan oleh sandbox provider dan mana yang harus diuji melalui stub internal. Dokumentasikan gap agar “sandbox hijau” tidak dianggap jaminan produksi tanpa risiko.

Mengapa Idempotency dan Rekonsiliasi Wajib?

Idempotency mencegah satu event menghasilkan efek bisnis berulang, sedangkan rekonsiliasi menemukan selisih yang tetap lolos dari alur real-time. Keduanya dibutuhkan karena webhook dapat dikirim ulang, koneksi dapat putus, dan respons dapat diterima dalam urutan berbeda.

Skalanya bukan kecil. BI mencatat pembayaran digital pada triwulan I 2026 mencapai 14,82 miliar transaksi, tumbuh 37,69% yoy, sementara transaksi QRIS tumbuh 116,43% yoy. Angka ini berasal dari siaran pers BI April 2026 dan menunjukkan mengapa desain “biasanya berhasil” tidak cukup untuk sistem pembayaran.

Kunci idempotency: order ID + event ID atau mekanisme resmi provider.
State machine: hanya izinkan transisi yang valid, misalnya pending → paid atau pending → expired.
Rekonsiliasi harian: bandingkan order internal, transaksi provider, dan laporan settlement.
Exception queue: pisahkan selisih untuk ditinjau tanpa mengubah data mentah.
Audit trail: catat siapa/apa yang mengubah status dan kapan perubahan terjadi.

Untuk memahami pemisahan transaksi dan pencairan, baca alur pencairan QRIS same day serta panduan QRIS belum masuk ke rekening.

Apa Saja Kesalahan Integrasi API QRIS yang Sering Terjadi?

Kesalahan paling berbahaya adalah menjadikan redirect frontend sebagai bukti pembayaran. Redirect membantu pengalaman pengguna, tetapi status final harus divalidasi server-to-server atau melalui mekanisme resmi provider.

Menaruh API key atau secret di JavaScript frontend, mobile app, atau repositori.
Menerima callback tanpa signature, timestamp, dan validasi nominal.
Memproses webhook berulang tanpa idempotency.
Menganggap semua status provider bisa langsung dipetakan ke status order yang sama.
Tidak menangani QR kedaluwarsa dan membuat order duplikat saat retry.
Mencatat payload lengkap yang mengandung data sensitif ke log.
Tidak memiliki rekonsiliasi atau jalur manual untuk exception.
Melakukan polling terlalu agresif tanpa timeout, backoff, dan rate-limit awareness.
Menggunakan contoh endpoint dari artikel pihak ketiga sebagai konfigurasi produksi.

Sebelum go-live, lakukan threat modeling singkat: aset apa yang dilindungi, siapa yang boleh mengubah status, apa yang terjadi jika provider lambat, dan bagaimana rollback dilakukan. Jawaban tertulis lebih berguna daripada checklist keamanan yang hanya dicentang tanpa pemilik.

Bagaimana Checklist Go-Live Integrasi QRIS?

Go-live layak dilakukan ketika alur bisnis, keamanan, observability, dan dukungan operasional sama-sama siap. API yang berhasil dipanggil belum berarti sistem siap menerima uang pelanggan.

Kontrak: dokumentasi provider, environment, credential owner, dan batas tanggung jawab jelas.
Security: HTTPS, secret manager, signature verification, replay protection, rate limit.
Reliability: timeout, retry/backoff, idempotency, queue, dan circuit breaker sesuai kebutuhan.
Data: mapping status, nominal, reference, expiry, timezone, dan audit log tervalidasi.
Operations: dashboard, alert, runbook incident, rekonsiliasi, dan owner on-call tersedia.
Business: fulfilment hanya berjalan setelah status resmi, kebijakan refund/dispute terdokumentasi.
Release: canary/limited rollout, rollback plan, dan post-launch review dijadwalkan.

Ingin membahas kebutuhan penerimaan QRIS untuk website atau aplikasi? Lihat solusi QRIS Ezeelink dan konsultasikan alur bisnismu. Ketersediaan API, endpoint, SLA, sandbox, serta fitur teknis Ezeelink wajib dikonfirmasi tim produk/engineering sebelum ada klaim implementasi.

Ezeelink terdaftar sebagai PJP QRIS berizin Bank Indonesia (No. 23/572/DKSP/Srt/B).

Lakukan review 24–72 jam setelah peluncuran terbatas. Periksa rasio order berbayar, webhook gagal, retry, latency, duplicate event, selisih rekonsiliasi, dan tiket pelanggan. Jika exception meningkat, hentikan perluasan trafik dan gunakan rollback yang sudah diuji. Keputusan go-live yang baik selalu memiliki kondisi berhenti, bukan hanya tanggal peluncuran.

Daftar QRIS Ezeelink untuk menerima pembayaran digital di usaha — Daftar QRIS Ezeelink dan mulai terima pembayaran dari bank dan e-wallet.

Referensi:

FAQ Seputar Integrasi API QRIS

Apa itu API QRIS?

API QRIS adalah antarmuka yang menghubungkan sistem bisnis dengan penyedia pembayaran untuk membuat transaksi QR, membaca status, menerima webhook, dan membantu rekonsiliasi. Detail endpoint dan payload tidak universal; semuanya mengikuti kontrak serta dokumentasi PJP yang dipilih. Credential harus disimpan di backend, bukan browser atau aplikasi klien. Kontrak API provider tetap menjadi acuan teknis untuk setiap implementasi nyata.

Apa beda QRIS statis dan dinamis?

QRIS statis memakai kode yang dapat digunakan berulang dan sering meminta pembayar mengisi nominal. QRIS dinamis dibuat untuk order tertentu, sehingga nominal, referensi, dan masa berlaku lebih mudah dikaitkan dengan checkout. Untuk website atau aplikasi, dynamic QR biasanya memberi korelasi order yang lebih rapi, tetapi membutuhkan integrasi backend. Pemilihan tipe QR harus mengikuti hubungan transaksi, order, dan kebutuhan rekonsiliasi.

Bagaimana callback pembayaran bekerja?

Provider mengirim event ke endpoint webhook bisnis ketika status transaksi berubah. Backend memverifikasi signature, timestamp, referensi, nominal, dan state sebelumnya sebelum memperbarui order. Callback dapat terkirim lebih dari sekali atau terlambat, jadi pemrosesan harus idempotent dan tidak boleh mengandalkan urutan kedatangan sebagai satu-satunya kontrol. Urutan event bisa berubah, sehingga consumer tidak boleh bergantung pada kedatangannya.

Apakah integrasi API QRIS perlu sandbox?

Ya, sandbox diperlukan untuk menguji create transaction, expiry, status sukses/gagal, webhook berulang, signature salah, timeout, dan rekonsiliasi tanpa memakai dana produksi. Namun, kemampuan sandbox berbeda antarprovider. Tim perlu mencatat skenario yang tidak dapat disimulasikan dan menutup gap melalui stub internal, canary release, serta monitoring produksi. Sandbox membantu tim menguji error tanpa menyentuh uang atau pelanggan produksi.

Bagaimana mencegah callback palsu?

Gunakan HTTPS, verifikasi signature sesuai dokumentasi provider, periksa timestamp atau nonce, cocokkan nominal dan referensi, batasi state transition, serta terapkan idempotency. Jangan mempercayai status dari browser atau payload yang belum diverifikasi. Simpan secret di secret manager dan jangan pernah menampilkan contoh key atau signature produksi dalam dokumentasi publik. Rotasi secret dan pembatasan akses harus masuk ke prosedur operasional tim.

Data apa yang perlu direkonsiliasi?

Cocokkan order ID, referensi provider, nominal, status pembayaran, waktu, expiry, refund/dispute bila ada, dan laporan settlement. Rekonsiliasi harus menghasilkan exception queue untuk selisih, bukan langsung menimpa data mentah. Audit log perlu mencatat sumber perubahan agar tim finance dan engineering dapat menelusuri perbedaan secara konsisten. Simpan jejak perubahan status agar selisih dapat ditelusuri setelah penutupan buku.