QRIS API vs Payment Gateway API: Perbedaan Teknis, Response Time, dan Retry Logic untuk Developer Indonesia

MDR 0,3% vs Latency P99: Mengapa Pilihan Integrasi QRIS Anda Menentukan Arsitektur Sistem

Saat Anda mengintegrasikan pembayaran QRIS, angka 0,3% MDR untuk UMKM sering jadi fokus utama. Tapi bagi developer, angka yang lebih penting adalah P99 latency payment gateway Anda. Dalam implementasi nyata, perbedaan antara langsung integrasi ke QRIS API versus melalui payment gateway tidak hanya soal biaya—tetapi bagaimana Anda menangani response time 500ms+ pada jam sibuk, retry dengan exponential backoff saat API timeout, dan memastikan webhook callback yang Anda terima benar-benar valid.

Artikel ini membedah secara teknis perbedaan antara integrasi langsung ke QRIS API (seperti Direct QRIS dari penyedia pembayaran) versus menggunakan payment gateway sebagai abstraksi layer, dengan fokus pada response time, latency metrics, error handling patterns, dan retry logic yang perlu Anda terapkan.

Direct QRIS API: Kontrol Penuh dengan Kompleksitas Sendiri

Integrasi langsung ke QRIS API berarti Anda berinteraksi langsung dengan sistem pembayaran masing-masing penyedia (DANA, GoPay, OVO, ShopeePay, dll). Pendekatan ini memberi kontrol penuh atas flow pembayaran, tetapi datang dengan kompleksitas signifikan.

Pertama, Anda harus mengimplementasikan sendiri retry logic yang tepat. Menurut dokumentasi DANA API, best practice untuk retry QRIS adalah menggunakan exponential backoff dengan maksimal 25 retry attempts, dan pentingnya menggunakan partnerReferenceNo yang sama saat retry. Ini berarti Anda tidak bisa sekadar mengirim ulang request yang sama—Anda harus mendesain sistem yang dapat melacak referensi unik per transaksi dan mengelola timing retry dengan cermat.

Kedua, setelah callback QRIS diterima, Anda wajib memverifikasi status menggunakan Status Inquiry API untuk memastikan integritas transaksi. NICEPAY API documentation menegaskan bahwa callback tidak bisa dianggap final tanpa verifikasi aktif. Ini menambah satu round-trip API per transaksi berhasil, yang berdampak pada total response time dan beban server Anda.

Ketiga, Anda perlu mengelola monitoring metrik secara mandiri. Payment gateway pada dasarnya memonitor metrik seperti average response time, P95/P99 latency, dan response time per endpoint untuk SLA mereka. Dengan integrasi langsung, Anda harus membangun dashbor dan monitoring sendiri untuk memastikan API eksternal berperforma baik dan mendeteksi anomali sebelum berdampak pada user.

Payment Gateway Abstraction: Standardisasi dengan Tradeoff Latency

Payment gateway seperti Midtrans dan Xendit bertindak sebagai layer abstraksi yang menyatukan berbagai metode pembayaran, termasuk QRIS, ke dalam API yang lebih seragam. Midtrans mendukung 24+ metode pembayaran dengan settlement 1-2 hari kerja, sementara Xendit menawarkan API yang lebih modern dengan settlement 1-3 hari kerja.

Keuntungan utamanya adalah konsistensi. Anda tidak perlu belajar dan mengintegrasikan API yang berbeda-beda untuk setiap penyedia QRIS. Satu endpoint payment gateway bisa menangani multiple QRIS provider di belakangnya. Ini sangat menghemat waktu development dan maintenance, terutama jika Anda perlu mendukung berbagai metode pembayaran selain QRIS.

Tetapi ada tradeoff: latency tambahan. Setiap request Anda melewati satu layer tambahan—dari sistem Anda ke payment gateway, lalu dari payment gateway ke QRIS provider, lalu kembali lagi. Dalam kasus normal, ini mungkin hanya menambah 100-200ms. Tetapi pada jam sibuk atau saat salah satu QRIS provider mengalami slowdown, latensi ini bisa membengkak signifikan. Jika payment gateway tidak meneruskan metric latency asli dari provider, Anda akan kehilangan visibilitas atas bottleneck sebenarnya.

Payment gateway juga memiliki aturan retry dan rate limiting yang berbeda-beda. Beberapa meneruskan retry langsung ke QRIS provider, lainnya mengimplementasikan queue internal. Anda perlu memahami bagaimana gateway pilihan Anda menangani retry dan error, karena ini berdampak pada bagaimana Anda mendesain sistem Anda sendiri—apakah perlu retry di sisi Anda, atau cukup mengandalkan mekanisme retry gateway.

Response Time dan Latency Metrics: Apa yang Harus Dimonitor

Untuk integrasi QRIS yang robust, Anda tidak bisa hanya mengandalkan satu metrik latency. Payment gateway profesional memonitor tiga metrik utama: average response time, P95/P99 latency, dan response time per endpoint. Masing-masing memberikan insight berbeda.

Average response time memberikan gambaran umum performa, tetapi bisa menyesatkan jika ada outlier yang ekstrem. P95 dan P99 latency jauh lebih penting untuk user experience—mereka menunjukkan performa yang dialami 95% dan 99% dari request. Jika P99 latency QRIS Anda 3 detik, berarti 1 dari 100 user mengalami delay yang signifikan, dan ini bisa berdampak besar pada conversion rate.

Response time per endpoint membantu Anda mengidentifikasi bottleneck spesifik. Apakah endpoint generate QRIS lambat, ataukah endpoint status inquiry yang bermasalah? Dengan integrasi langsung ke QRIS API, Anda bisa memonitor ini secara granular. Dengan payment gateway, Anda sering kali hanya melihat latency gateway itu sendiri, tanpa visibilitas ke mana sebenarnya waktu dihabiskan.

Untuk integrasi yang sehat, targetkan P95 latency di bawah 1 detik untuk generate QRIS, dan P99 di bawah 2 detik untuk status inquiry. Apapun di atas ini, Anda perlu pertimbangkan retry logic, circuit breaker, atau fallback ke metode pembayaran lain. Monitoring yang tepat juga membantu Anda mendeteksi degradation secara dini—sebelum user mulai komplain.

Retry Logic, Exponential Backoff, dan Idempotency

Network failure, timeout, dan error 500 dari API pembayaran adalah kenormalan. Sistem yang robust harus didesain dengan asumsi bahwa failure akan terjadi. Pertanyaannya adalah bagaimana Anda menangani failure tersebut tanpa mengganggu user atau menciptakan transaksi duplikat.

Pola retry logic yang baik untuk QRIS mengikuti prinsip exponential backoff: tunggu semakin lama di antara setiap retry. Jika retry pertama setelah 1 detik, berikutnya setelah 2 detik, lalu 4 detik, dan seterusnya. Dokumentasi DANA merekomendasikan maksimal 25 retry attempts—cukup untuk menangani fluktuasi jangka pendek, tetapi tidak selamanya untuk menemani sistem yang down berjam-jam.

Kunci dari retry yang aman adalah idempotency: request yang sama yang dikirim berkali-kali harus menghasilkan efek yang sama sekali saja. Untuk QRIS, ini berarti menggunakan partnerReferenceNo atau reference ID yang sama untuk setiap retry dari transaksi yang sama. Dengan begitu, meskipun sistem Anda mengirim 10 request karena network issue, QRIS provider akan mengenali ini sebagai transaksi yang sama—bukan 10 transaksi terpisah.

Implementasi idempotency biasanya memerlukan database layer yang bisa mengecek apakah reference ID sudah pernah digunakan sebelum memproses request baru. Jika sudah ada, sistem Anda bisa mengembalikan hasil yang ada tanpa memanggil API eksternal lagi. Ini tidak hanya mencegah duplikasi, tetapi juga menghemat quota API dan meningkatkan response time untuk retry request.

Webhook Idempotency dan Status Inquiry: Verifikasi Adalah Kunci

Callback atau webhook dari QRIS provider adalah cara paling efisien untuk mengetahui status pembayaran selesai. Tetapi callback tidak bisa dipercaya sepenuhnya—network failure, replay attack, atau bahkan callback palsu adalah risiko nyata. Oleh karena itu, NICEPAY documentation menegaskan bahwa setelah callback QRIS diterima, Anda wajib memverifikasi status menggunakan Status Inquiry API.

Implementasi webhook idempotency memerlukan pendekatan dua langkah. Pertama, saat callback diterima, simpan informasi tersebut ke database dengan status "pending-verification". Kedua, segera panggil Status Inquiry API untuk mengkonfirmasi. Jika status inquiry cocok dengan callback, update ke status final. Jika tidak, investigate lebih lanjut atau mark sebagai suspicious.

Pola ini menambah complexity, tetapi sangat penting untuk integritas keuangan. Tanpa verifikasi, sistem Anda bisa ditipu dengan callback palsu yang mengklaim pembayaran berhasil. Dengan verifikasi, Anda selalu memiliki sumber kebenaran tunggal dari Status Inquiry API—yang jauh lebih sulit dipalsukan karena memerlukan authentication dan berasal langsung dari penyedia pembayaran.

Kapan Harus Pilih Integrasi Langsung vs Payment Gateway

Keputusan antara integrasi langsung ke QRIS API atau menggunakan payment gateway bergantung pada skala, resource tim, dan kompleksitas kebutuhan bisnis Anda. Untuk startup dengan tim kecil yang perlu cepat go-to-market, payment gateway seperti Midtrans atau Xendit sering menjadi pilihan yang lebih masuk akal—Anda mendapatkan standardisasi, dokumentasi yang lebih baik, dan satu integrasi untuk multiple metode pembayaran.

Namun, untuk bisnis yang sudah mature dengan volume transaksi tinggi dan tim engineering yang cukup kuat, integrasi langsung ke beberapa QRIS provider utama bisa memberikan leverage biaya dan kontrol yang lebih baik. MDR QRIS memang diatur Bank Indonesia—0,3% untuk UMKM dan 0,7% untuk merchant reguler, sama untuk semua—tetapi payment gateway mungkin menambah fee tambahan di atasnya. Dengan integrasi langsung, Anda bisa menghindari fee ini dan mengontrol penuh flow pembayaran.

Pertimbangan lain adalah dukungan teknis. Dengan payment gateway, Anda memiliki satu titik kontak untuk issue pembayaran. Dengan integrasi langsung, Anda perlu berkoordinasi dengan multiple penyedia jika terjadi masalah. Untuk tim yang kecil, ini bisa menjadi overhead signifikan.

Terlepas dari pilihan Anda, kunci sukses integrasi QRIS adalah monitoring yang tepat, retry logic yang robust, dan verifikasi yang ketat. Tanpa ketiga-tiganya, bahkan integrasi yang paling mahal sekalipun akan mengalami issue yang berdampak pada bisnis.

Jika Anda membutuhkan bantuan mendesain arsitektur sistem pembayaran yang robust untuk bisnis Anda, tim di Colabs siap membantu. Kami berpengalaman mengintegrasikan berbagai metode pembayaran, termasuk QRIS, dengan pendekatan yang mempertimbangkan performa, keamanan, dan skalabilitas jangka panjang. Hubungi kami untuk konsultasi gratis kebutuhan sistem pembayaran Anda.