QRIS Gateway Docs
Portal Dashboard Admin
Getting Started

Introduction

qris-gateway adalah multi-tenant dynamic QRIS payment gateway: mengenerate QRIS dinamis dengan nominal tetap secara instant, melacak status pembayaran, dan mengirimkan signed webhook saat transaksi lunas — tanpa tergantung pada API resmi e-wallet tunggal.

EMVCo 54 Tag Injection

Suntik nominal ke QRIS statis & hitung checksum CRC16-CCITT dalam milidetik.

App Listener Support

Terima notifikasi masuk dari Tasker / MacroDroid di HP Merchant.

Signed Webhook

Verifikasi keaslian webhook dengan HMAC SHA-256 Signature (X-Signature).

Authentication

Setiap tenant / merchant memiliki dua API Key terpisah yang otomatis menentukan mode lingkungan (live vs sandbox):

live_sk_...

Live API Key

Digunakan untuk transaksi pembayaran riil pada lingkungan produksi.

sb_sk_...

Sandbox API Key

Digunakan untuk pengujian tanpa uang asli + mendukung fitur simulate-payment.

// Kirim via HTTP Header (Recommended)
X-API-Key: live_sk_gopay_secret_key_12345
// Atau via Authorization Bearer
Authorization: Bearer live_sk_gopay_secret_key_12345

Flow Overview & Diagram

Alur pencocokan pembayaran dari notifikasi HP Merchant hingga callback webhook ke server Anda: 

Payment app notification (GoPay Merchant, DANA, BCA, OVO)
        │
        │  read by App Listener (Tasker / MacroDroid)
        ▼
POST /v1/webhook/payment-status  (X-User-ID + X-Webhook-Secret)
        │
        │  match against pending transactions by tenant + amount
        ▼
transaction.payment_status = 'paid'
        │
        ▼
Signed Outbound Webhook (X-Signature: sha256=...) ──► Merchant Webhook URL
POST

/v1/qris-codes

Generate QRIS Dinamis dan buat record transaksi baru (Expiry 5 menit).

Request Sample (cURL) 
curl -X POST http://localhost:3000/v1/qris-codes   -H "Content-Type: application/json"   -H "X-API-Key: live_sk_gopay_secret_key_12345"   -d '{ "amount": 50000 }'
Response (200 OK) 
{
  "success": true,
  "data": {
    "id": "tr_3d5fbe55dd23f25f",
    "tenant_id": "default",
    "mode": "live",
    "qris_url": "http://localhost:3000/qr/tr_3d5fbe55dd23f25f",
    "qris_code": "00020101021226660014ID.CO.BNI.WWW...540550000...6304XXXX",
    "amount": 50000,
    "payment_status": "unpaid",
    "expires_at": "2026-07-22T09:20:00.000Z",
    "expires_in": "5 menit"
  }
}
POST

/v1/webhook/payment-status

Endpoint inbound yang dipanggil oleh Android Listener App saat notifikasi pembayaran masuk di HP Merchant.

Inbound App Listener Payload 
curl -X POST http://localhost:3000/v1/webhook/payment-status   -H "Content-Type: application/json"   -H "X-User-ID: default"   -H "X-Webhook-Secret: whsec_4150ecb52e474d30958b0cbac55785cd"   -d '{ "amount": 50000, "issuer": "DANA", "reference_id": "notif_99812" }'
POST

/v1/transactions/simulate-payment

Mensimulasikan kelunasan transaksi khusus mode Sandbox (sb_sk_...). Memicu penanda-tanganan & pengiriman outbound webhook asli.

curl -X POST http://localhost:3000/v1/transactions/simulate-payment   -H "Content-Type: application/json"   -H "X-API-Key: sb_sk_gopay_secret_key_12345"   -d '{ "transaction_id": "tr_3d5fbe55dd23f25f" }'