Cara Mengecek Status Pembayaran Menggunakan QRIS Inquiry API untuk UMKM Indonesia 2026

Transaksi pembayaran digital di Indonesia tumbuh 40.35% year-over-year menurut data Bank Indonesia. Pertumbuhan ini membawa tantangan baru bagi pemilik usaha: bagaimana memantau status pembayaran secara real-time, terutama saat periode traffik tinggi? QRIS Inquiry API menjadi solusi untuk menjawab kebutuhan ini.

Artikel ini membahas cara mengecek status pembayaran menggunakan QRIS Inquiry API secara praktis, termasuk integrasi dengan payment gateway utama di Indonesia dan troubleshooting masalah umum yang sering dihadapi UMKM.

Apa itu QRIS Inquiry API dan Mengguna Penting

QRIS Inquiry API adalah antarmuka yang memungkinkan sistem bisnis Anda mengecek status transaksi QRIS secara real-time tanpa perlu menunggu notifikasi webhook. Berbeda dengan webhook yang bersifat push (server payment gateway mengirim notifikasi ke Anda), inquiry API bersifat pull — sistem Anda aktif meminta update status ke server payment gateway.

Pendekatan ini krusial untuk beberapa skenario:

• Webhook tidak terkirim karena downtime server, network failure, atau konfigurasi salah
• Pelanggan menanyakan status pembayaran secara langsung (via WhatsApp, chat, atau di toko fisik)
• Reconcile harian antara sistem internal dengan data payment gateway
• Kebutuhan update status real-time saat peak hour (misalnya flash sale atau promo besar)

Pada 2025, QRIS telah berekspansi internasional dan kini diterima di China dan Amerika Serikat. Bagi bisnis Indonesia yang berencana go-global, memahami inquiry API bukan lagi opsi — tapi kebutuhan dasar.

Payment Gateway yang Menyediakan QRIS Inquiry API

Mayoritas payment gateway di Indonesia sudah menyediakan endpoint inquiry untuk QRIS. Berikut daftar utama beserta nama endpoint-nya:

• NICEPAY: Status Inquiry API — endpoint khusus untuk mengecek status transaksi QRIS dengan parameter transactionId atau referenceNo
• SNAP (Midtrans): Check Status Transaction — API standar untuk memverifikasi status semua metode pembayaran, termasuk QRIS
• Zipay: Inquiry QRIS Status — endpoint spesifik untuk mengecek pembayaran QRIS
• Paydia: Query Payment — API yang mengembalikan detail status dan timestamp pembayaran
• QRIS.id: Check Invoice Status — untuk mengecek status invoice berbasis QRIS

Meskipun nama endpoint berbeda, pola implementasinya mirip: Anda mengirim request dengan identifier transaksi (transaction ID, invoice number, atau reference number), dan server mengembalikan status pembayaran beserta metadata-nya (timestamp, amount, customer info).

Untuk integrasi QRIS yang lebih dalam ke sistem bisnis Anda, panduan lengkap integrasi payment gateway dan QRIS untuk bisnis Indonesia 2026 membahas langkah-langkah setup dari awal hingga production.

Struktur Response QRIS Inquiry API

Response dari inquiry API umumnya mengikuti pola yang sama di berbagai payment gateway. Berikut contoh struktur yang umum (format bisa berbeda tergantung provider):

{
  "status": "SUCCESS",
  "transactionId": "TXN123456789",
  "amount": 150000,
  "paymentMethod": "QRIS",
  "transactionTime": "2025-06-27T10:30:00+07:00",
  "settlementTime": "2025-06-27T10:32:15+07:00"
}

Field status biasanya memiliki nilai seperti:

• SUCCESS atau COMPLETED — pembayaran berhasil
• PENDING — menunggu pembayaran
• FAILED — pembayaran gagal atau expired
• REFUNDED — transaksi sudah direfund

Penting untuk memahami mapping nilai status antara payment gateway yang Anda gunakan dengan sistem internal Anda. Setiap gateway mungkin menggunakan terminologi berbeda, namun konsep dasarnya sama: transaksi memiliki lifecycle yang jelas dan perlu ditangani secara konsisten.

Implementasi Retry Logic yang Benar

Salah satu pola umum saat menggunakan inquiry API adalah melakukan retry hingga status menjadi final (SUCCESS/FAILED). Namun, retry yang salah bisa menyebabkan infinite loop atau pemborosan resource.

Pattern yang disarankan:

1. Exponential backoff — interval retry meningkat secara eksponensial (misal: 5s, 10s, 20s, 40s)
2. Max retry limit — berhenti setelah N percobaan (biasanya 5-10x)
3. Timeout protection — berhenti jika total waktu melebihi threshold (misal 5 menit untuk QRIS)
4. Idempotency — satu transaksi tidak boleh diproses dua kali meskipun di-inquire berkali-kali

Untuk implementasi webhook QRIS yang benar dengan idempotency pattern dan retry logic, panduan idempotency pattern untuk QRIS webhook membahas skema database dan contoh kode implementasi.

Jika Anda mengalami webhook yang hilang atau notifikasi tidak sampai, cara debug dan test QRIS webhook memberikan solusi praktis untuk troubleshooting masalah tersebut.

Alternatif Selain Inquiry API

Inquiry API bukan satu-satunya cara mengecek status pembayaran QRIS. Ada beberapa metode alternatif yang bisa digunakan tergantung kebutuhan bisnis Anda:

1. Merchant Dashboard — www.merchant.qris.interactive.co.id menyediakan interface web untuk melihat riwayat transaksi dan status pembayaran. Cocok untuk reconcile harian atau pengecekan manual sesekali.
2. EDC Applications — aplikasi di mesin EDC yang terhubung dengan QRIS. Beberapa provider menyimpan riwayat transaksi yang bisa diakses langsung dari device.
3. GoPay Merchant App — untuk merchant yang menggunakan GoPay sebagai channel QRIS, aplikasi merchant menyediakan history transaksi yang bisa diakses via mobile.

Metode ini lebih cocok untuk operasional manual atau ketika Anda tidak memerlukan integrasi otomatis. Namun, untuk sistem yang fully automated dan skala besar, inquiry API tetap menjadi pendekatan yang paling efisien.

Troubleshooting Masalah Umum

Berikut masalah-masalah yang sering terjadi saat menggunakan QRIS Inquiry API dan cara解决nya:

Timeout atau Slow Response

Saat peak hour, server payment gateway mungkin mengalami delays. Solusi:

• Tambahkan timeout yang wajar (misal 10-30 detik)
• Gunakan queue untuk batch inquiry agar tidak overload sistem Anda sendiri
• Implement retry dengan exponential backoff seperti dijelaskan sebelumnya

Pending Status Terlalu Lama

QRIS memiliki timeout window (biasanya 30-60 menit). Jika status masih PENDING setelah melewati window, kemungkinan besar pembayaran gagal atau expired. Tindakan:

• Tandai transaksi sebagai FAILED di sistem setelah melewati timeout window + buffer (misal 5 menit)
• Berikan notifikasi ke customer bahwa pembayaran expired dan perlu retry

Duplicate Transaction

Kadang customer melakukan pembayaran dua kali untuk order yang sama. Deteksi dengan:

• Cek apakah ada dua transaksi SUCCESS dengan referenceNo yang sama
• Gunakan unique identifier yang menggabungkan orderId + timestamp untuk menghindari race condition

Rate Limiting

Beberapa payment gateway menerapkan rate limit pada inquiry API. Solusi:

• Batch inquiry untuk multiple transaksi dalam satu request jika gateway menyediakan endpoint batch
• Implement client-side rate limiting dengan token bucket algorithm
• Cache status transaksi untuk beberapa waktu (misal 1-2 menit) untuk mengurangi call redundant

Tren teknologi bisnis Indonesia 2025 menunjukkan fokus pada cybersecurity dan financial inclusion untuk UMKM. Memiliki sistem payment monitoring yang robust bukan hanya tentang convenience — tapi juga tentang keamanan dan trust dalam bisnis digital.

Langkah Selanjutnya

Implementasi QRIS Inquiry API adalah salah satu komponen dalam ekosistem pembayaran digital yang modern. Jika Anda membutuhkan bantuan untuk:

• Integrasi QRIS dengan sistem bisnis yang kompleks
• Implementasi retry logic dan idempotency pattern yang benar
• Troubleshooting masalah payment yang berlarut-larut
• Modernisasi sistem pembayaran UMKM Anda

Tim Colabs siap membantu. Diskusikan kebutuhan bisnis Anda dan temukan solusi yang tepat untuk scale yang Anda targetkan.