Hubungkan aplikasi Anda ke GateQRIS: buat QRIS dinamis lewat API, tampilkan ke pembeli, dan terima kabar otomatis begitu pembayaran terdeteksi. Dana masuk langsung ke e-wallet Anda — GateQRIS hanya mendeteksi dan meneruskan konfirmasinya.
1. Daftar dan atur QRIS statis toko Anda di dashboard (menu QRIS Saya), lalu pasang aplikasi Listener di HP yang menerima notifikasi pembayaran.
2. Buat kunci API di dashboard, menu Integrasi API. Satu akun bisa punya banyak kunci — satu untuk tiap aplikasi — dan tiap kunci bisa dicabut sendiri-sendiri.
3. Dari server aplikasi Anda, panggil POST /api/integrasi/transaksi untuk membuat pembayaran, tampilkan qr_url dari respons ke pembeli.
4. GateQRIS mendeteksi pembayaran, mengubah status menjadi lunas, lalu mengirim webhook ke URL Anda (atau aplikasi Anda memeriksa status lewat GET). Selesai.
Alamat dasar semua endpoint: https://gateqris.web.id
Setiap panggilan wajib membawa kunci API pada header x-api-key. Kunci berbentuk gq_… dan hanya ditampilkan sekali saat dibuat — server kami hanya menyimpan hash-nya. Perlakukan kunci seperti kata sandi: simpan di server aplikasi Anda (variabel lingkungan), jangan pernah menaruhnya di aplikasi HP / halaman web yang bisa dilihat pembeli.
x-api-key: gq_8f3ka91bd27c...
POST /api/integrasi/transaksi
| Field | Wajib | Keterangan |
|---|---|---|
| referensi | Ya | Kode order di aplikasi Anda, maks 64 karakter. Bersifat idempoten: memanggil ulang dengan referensi yang sama mengembalikan transaksi yang sama, bukan membuat duplikat. |
| nominal | Ya | Bilangan bulat (rupiah), Rp100 s.d. Rp100.000.000. |
curl -X POST https://gateqris.web.id/api/integrasi/transaksi \
-H "Content-Type: application/json" \
-H "x-api-key: gq_KUNCI_ANDA" \
-d '{"referensi": "ORDER-001", "nominal": 50000}'
Respons berhasil (HTTP 201):
{
"id": 128,
"referensi": "ORDER-001",
"status": "menunggu",
"nominal": 50000,
"kode_unik": 7,
"nominal_total": 50007,
"payload_qris": "0002010102122668...",
"qr_url": "data:image/png;base64,iVBORw0K...",
"kedaluwarsa_at": "2026-11-12T09:15:00.000Z",
"lunas_at": null
}
Kode unik (1–99) ditambahkan agar dua pembayaran senominal sama tidak tertukar; pembeli membayar nominal_total. Tampilkan gambar dari qr_url (sudah berupa PNG siap pakai) atau buat QR sendiri dari payload_qris. Transaksi berlaku 30 menit; sesudah itu statusnya menjadi kedaluwarsa dan tidak bisa dibayar lagi.
GET /api/integrasi/transaksi/{referensi}
curl https://gateqris.web.id/api/integrasi/transaksi/ORDER-001 \ -H "x-api-key: gq_KUNCI_ANDA"
Bentuk respons sama seperti pembuatan. Nilai status: menunggu (belum dibayar), lunas (pembayaran terdeteksi, lunas_at terisi), atau kedaluwarsa. Cara ini cocok bila aplikasi Anda lebih suka memeriksa sendiri (polling) daripada menerima webhook.
Isi URL webhook di dashboard (menu Integrasi API). Begitu transaksi menjadi lunas, GateQRIS mengirim POST JSON ke URL itu:
{
"event": "transaksi.lunas",
"referensi": "ORDER-001",
"nominal": 50000,
"kode_unik": 7,
"nominal_total": 50007,
"lunas_at": "2026-11-12T08:47:11.000Z"
}
Balas dengan status 2xx agar dianggap diterima. Bila gagal, pengiriman dicoba sampai 3 kali. Seluruh riwayat percobaan (status HTTP dan respons server Anda) bisa dilihat di dashboard lewat tombol Inspeksi pada transaksi — dari sana webhook juga bisa dikirim ulang secara manual.
Verifikasi tanda tangan. Setiap webhook membawa header x-gateqris-timestamp dan x-gateqris-signature. Tanda tangan adalah HMAC-SHA256 memakai Rahasia Webhook Anda, atas teks timestamp + "." + body-mentah. Verifikasi sebelum mempercayai isi webhook:
// Node.js
const crypto = require('crypto');
function webhookValid(req, bodyMentah, rahasia) {
const ts = req.headers['x-gateqris-timestamp'];
const tanda = req.headers['x-gateqris-signature'];
const hitung = crypto.createHmac('sha256', rahasia)
.update(ts + '.' + bodyMentah).digest('hex');
return crypto.timingSafeEqual(Buffer.from(hitung), Buffer.from(tanda || ''));
}
// PHP
function webhookValid($bodyMentah, $rahasia) {
$ts = $_SERVER['HTTP_X_GATEQRIS_TIMESTAMP'] ?? '';
$tanda = $_SERVER['HTTP_X_GATEQRIS_SIGNATURE'] ?? '';
$hitung = hash_hmac('sha256', $ts . '.' . $bodyMentah, $rahasia);
return hash_equals($hitung, $tanda);
}
Belum yakin webhook Anda bekerja? Tekan Tes Webhook di dashboard — GateQRIS mengirim satu webhook percobaan ber-event webhook.tes dan melaporkan status HTTP yang diterima.
Listener Android adalah cara utama mendeteksi pembayaran. Kedua kanal deteksi GateQRIS — Listener maupun webhook mutasi — tidak pernah membutuhkan kredensial portal e-wallet/bank Anda (kata sandi, PIN, OTP, token/cookie): GateQRIS tidak meminta dan tidak menyimpannya. Bila Anda memakai layanan pemantau mutasi (atau ingin meneruskan laporan dari sistem Anda sendiri), laporan uang masuk bisa dikirim ke:
POST /api/integrasi/mutasi — autentikasi x-api-key yang sama. Dua gaya isi diterima:
// Gaya notifikasi
{ "judul": "DANA", "teks": "Pembayaran QRIS Rp50.007 berhasil", "paket": "id.dana" }
// Gaya laporan mutasi
{ "nominal": 50007, "keterangan": "QRIS masuk dari BUDI" }
Laporan dicocokkan dengan mesin yang sama persis seperti notifikasi Listener: nominal total dicocokkan ke transaksi yang sedang menunggu milik akun Anda. Respons: { "diterima": true, "cocok": true, "referensi": "ORDER-001" }. Laporan tampil di dashboard pada kartu Mutasi Masuk dengan sumber “Webhook Mutasi”. Kanal ini tidak menggandakan deteksi Listener — bila keduanya aktif dan laporan yang sama masuk dua kali, pencocokan kedua tidak menemukan transaksi menunggu lagi dan tidak mengubah apa pun.
Membuat transaksi tidak memotong apa pun. Biaya Rp50 dipotong dari Saldo Layanan hanya saat transaksi menjadi lunas — transaksi kedaluwarsa atau gagal tidak dikenai biaya, dan tidak ada sistem tahan-lalu-kembalikan. Bila Saldo Layanan kurang dari Rp50 (dan tidak ada langganan aktif), pembuatan transaksi ditolak dengan HTTP 402 sampai Anda top up dari dashboard.
| HTTP | Kode | Arti |
|---|---|---|
| 400 | REFERENSI_KURANG / NOMINAL_SALAH | Isi permintaan tidak lengkap atau nominal di luar batas. |
| 401 | KUNCI_KURANG / KUNCI_SALAH | Header x-api-key tidak ada, tidak dikenal, atau sudah dicabut. |
| 402 | SALDO_KURANG | Saldo Layanan di bawah Rp50. Top up dulu dari dashboard. |
| 404 | TIDAK_ADA | Referensi tidak ditemukan di akun Anda. |
| 409 | KODE_UNIK_HABIS | Kode unik 1–99 sedang penuh oleh transaksi menunggu. Coba lagi sebentar. |
| 422 | QRIS_BELUM_DIATUR | Akun belum menyimpan QRIS statis. Atur di dashboard, menu QRIS Saya. |
Apakah dana pembeli melewati GateQRIS? Tidak. QR yang dibayar adalah QRIS milik Anda sendiri; dana masuk langsung ke e-wallet / rekening Anda. GateQRIS hanya membaca notifikasi pembayarannya lewat aplikasi Listener.
Kunci saya bocor, bagaimana? Cabut kunci itu dari dashboard (Integrasi API → Cabut) — berhenti berlaku seketika — lalu buat kunci baru. Aplikasi lain yang memakai kunci berbeda tidak ikut terganggu.
Webhook saya mati sesaat, apakah transaksi hilang? Tidak. Status transaksi tetap tersimpan; periksa lewat GET status, atau kirim ulang webhook-nya dari Inspeksi di dashboard.