QGateway

Dokumentasi API v1

Terima QRIS otomatis dari aplikasimu

Satu permintaan untuk membuat tagihan, satu endpoint untuk menerima kabar lunas. Base URL: https://qgateway.ruangasn.com

Mulai cepat

  1. Daftar → unggah QRIS statis toko di menu QRIS saya.
  2. Pasang detektor di menu Detektor (HP Android + MacroDroid, dan/atau GoBiz).
  3. Menu Aplikasi & API: buat kunci qg_test_, isi URL webhook, tekan Kirim tes.
  4. Buat tagihan dari server (di bawah), simulasikan lunas, pastikan webhook diterima.
  5. Verifikasi email → buat kunci qg_live_ → bayar satu tagihan kecil dari e-wallet sendiri.

Autentikasi

Kirim kunci di header Authorization: Bearer qg_live_… (atau X-API-Key). Mode ditentukan oleh kunci: qg_test_ = sandbox (uang tidak sungguhan, data & kode unik terpisah), qg_live_ = produksi. Kunci hanya tampil sekali dan disimpan sebagai hash; cabut kapan saja dari dasbor. Jangan pernah menaruh kunci di kode frontend.

Buat tagihan

POST /api/v1/invoices — alokasikan kode unik, buat QRIS bernominal, kembalikan halaman bayar.

curl -X POST https://qgateway.ruangasn.com/api/v1/invoices \
  -H "Authorization: Bearer qg_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "INV-2026-001",
    "amount": 149000,
    "customer_name": "Budi Santoso",
    "description": "Paket Pro 1 bulan",
    "return_url": "https://tokomu.com/terima-kasih",
    "metadata": {"user_id": 42}
  }'
FieldWajibKeterangan
external_idyaID pesananmu (huruf, angka, . _ - : / #, maks 100). Idempoten: permintaan ulang mengembalikan tagihan yang sama selama masih menunggu/lunas. Juga diterima sebagai external_order_id.
amountyaNominal pokok (rupiah, bilangan bulat, 1 – 10.000.000).
customer_name, customer_email, descriptiontidakTampil di halaman bayar & dasbor.
return_urltidakPembeli diarahkan ke sini setelah lunas, ditambah ?invoice_id=…&external_id=…&status=paid. Jangan menganggap lunas dari parameter ini — percayai webhook.
webhook_urltidakMenimpa URL webhook aplikasi untuk tagihan ini.
metadatatidakObjek bebas (maks 20 kunci / 2 KB), dikembalikan di webhook.
ttl_minutestidakMasa berlaku 1 – 1440 menit (bawaan per aplikasi, 15).
qris_idtidakPakai QRIS tertentu (bawaan: QRIS aplikasi atau QRIS utama).
HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "invoice_id": "inv_k3v9q2m8x1c7w4z6b0n5",
    "external_id": "INV-2026-001",
    "mode": "test",
    "status": "pending",
    "paid": false,
    "base_amount": 149000,
    "unique_code": 7,
    "total_amount": 149007,
    "qr_mode": "dynamic",
    "qr_string": "00020101021226...5406149007...6304A1B2",
    "qr_image_url": "https://qgateway.ruangasn.com/pay/inv_k3v9.../qr.png",
    "checkout_url": "https://qgateway.ruangasn.com/pay/inv_k3v9...",
    "expires_at": "2026-11-18T10:15:00+07:00",
    "paid_at": null
  }
}

Kode unik dimulai dari +Rp 1 dan selalu dipilih yang terkecil yang bebas, sehingga dua pesanan bernominal sama tidak pernah punya total yang sama. Jangan menghitung sendiri — selalu tampilkan total_amount dari respons. Aplikasi bisa diatur ke mode kurangi (total = pokok − kode) agar pembeli membayar sedikit lebih murah.

Cek, daftar, batalkan

EndpointFungsi
GET /api/v1/invoices/{id}Status satu tagihan (cadangan bila webhook belum siap). Sekaligus memicu cek mutasi GoBiz.
GET /api/v1/invoices?status=paid&external_id=…&limit=20Daftar tagihan aplikasi ini (mode sesuai kunci).
POST /api/v1/invoices/{id}/cancelBatalkan tagihan yang masih menunggu → webhook invoice.cancelled.
POST /api/v1/invoices/{id}/simulateHanya kunci qg_test_: tandai lunas seolah pembeli membayar. Tagihan LIVE ditolak 403.
GET /api/v1/meCek koneksi: aplikasi, mode, QRIS, jumlah detektor online, sisa kuota & saldo.

Status tagihan: pending → paid | expired | cancelled. Pembayaran yang masuk sampai 30 menit setelah kedaluwarsa tetap dilunasi dengan paid_late: true.

Webhook

Saat status berubah, QGateway mengirim POST JSON ke URL webhook aplikasimu. Event: invoice.paid, invoice.expired, invoice.cancelled (dan ping dari tombol uji).

POST https://tokomu.com/webhook/qgateway
Content-Type: application/json
X-QGateway-Event: invoice.paid
X-QGateway-Timestamp: 1795001722
X-QGateway-Signature: 5f2c…  (hex HMAC_SHA256(timestamp + "." + body, webhook_secret))
X-QGateway-Delivery: 7d0c9a7e-1f3b-4c39-9a51-5f3a9f8a2b11   (sama di setiap percobaan ulang)
X-QGateway-Attempt: 1

{"event":"invoice.paid","invoice_id":"inv_k3v9q2m8x1c7w4z6b0n5","external_id":"INV-2026-001","mode":"live",
 "status":"paid","paid":true,"base_amount":149000,"unique_code":7,"total_amount":149007,"customer_name":"Budi Santoso",
 "description":"Paket Pro 1 bulan","metadata":{"user_id":42},"paid_late":false,"created_at":"2026-11-18T10:00:00+07:00",
 "expires_at":"2026-11-18T10:15:00+07:00","paid_at":"2026-11-18T10:03:12+07:00","paid_via":"android"}
  • Tanda tangan: hex(HMAC_SHA256(timestamp + "." + body_mentah, webhook_secret)). Hitung dari byte mentah, bandingkan waktu-konstan, tolak timestamp > 5 menit.
  • Balas 2xx dalam 8 detik. Selain itu dianggap gagal dan dicoba ulang: 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, 12 jam, 24 jam (total 8 percobaan). Pengalihan (3xx) tidak diikuti.
  • Idempoten: event yang sama bisa datang lebih dari sekali. Pakai external_id atau X-QGateway-Delivery sebagai kunci.
  • URL webhook harus publik (http/https). Alamat lokal/privat diblokir. Setiap percobaan tercatat di detail transaksi beserta balasan servermu, dan bisa dikirim ulang manual.

Contoh kode

PHP (native)

<?php
// webhook.php — terima kabar lunas dari QGateway
$raw = file_get_contents('php://input');          // body MENTAH, jangan json_decode dulu
$ts  = $_SERVER['HTTP_X_QGATEWAY_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_QGATEWAY_SIGNATURE'] ?? '';
$secret = getenv('QGATEWAY_WEBHOOK_SECRET');

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit('stale'); }          // anti-replay 5 menit
$expected = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (! hash_equals($expected, $sig)) { http_response_code(401); exit('bad signature'); }

$e = json_decode($raw, true);
if ($e['event'] === 'invoice.paid') {
    // WAJIB idempoten: event yang sama bisa datang lagi (retry). Kunci: external_id.
    tandaiPesananLunas($e['external_id'], $e['total_amount']);
}
http_response_code(200);
echo 'ok';

Laravel

// routes/web.php  (kecualikan dari CSRF: bootstrap/app.php → validateCsrfTokens(except: ['webhook/qgateway']))
Route::post('/webhook/qgateway', function (Illuminate\Http\Request $r) {
    $raw = $r->getContent();
    $ts  = $r->header('X-QGateway-Timestamp');
    abort_if(abs(time() - (int) $ts) > 300, 400);
    abort_unless(hash_equals(hash_hmac('sha256', $ts.'.'.$raw, config('services.qgateway.secret')),
        (string) $r->header('X-QGateway-Signature')), 401);

    $e = json_decode($raw, true);
    if ($e['event'] === 'invoice.paid') {
        Order::where('code', $e['external_id'])->where('status', '!=', 'paid')->update(['status' => 'paid']);
    }
    return response('ok');
});

// Membuat tagihan dari controller checkout:
$res = Http::withToken(config('services.qgateway.key'))->post('https://qgateway.ruangasn.com/api/v1/invoices', [
    'external_id' => $order->code, 'amount' => $order->total, 'customer_name' => $user->name,
    'return_url' => route('orders.show', $order),
])->throw()->json('data');
return redirect($res['checkout_url']);

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';
const app = express();

// express.raw() = byte persis yang ditandatangani. express.json() merusak tanda tangan.
app.post('/webhook/qgateway', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.header('X-QGateway-Timestamp');
  const sig = req.header('X-QGateway-Signature') || '';
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(400).send('stale');
  const expected = crypto.createHmac('sha256', process.env.QGATEWAY_WEBHOOK_SECRET)
    .update(ts + '.' + req.body).digest('hex');
  if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return res.status(401).send('bad signature');

  const e = JSON.parse(req.body.toString('utf8'));
  if (e.event === 'invoice.paid') markPaid(e.external_id);   // idempoten!
  res.send('ok');
});

// Buat tagihan
const r = await fetch('https://qgateway.ruangasn.com/api/v1/invoices', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.QGATEWAY_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ external_id: 'INV-1', amount: 50000 }),
});
const { data } = await r.json();   // data.checkout_url

Python (Flask)

import hmac, hashlib, time, os, json
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhook/qgateway")
def qgateway():
    raw = request.get_data()                       # bytes mentah
    ts = request.headers.get("X-QGateway-Timestamp", "0")
    sig = request.headers.get("X-QGateway-Signature", "")
    if abs(time.time() - int(ts)) > 300:
        abort(400)
    expected = hmac.new(os.environ["QGATEWAY_WEBHOOK_SECRET"].encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    e = json.loads(raw)
    if e["event"] == "invoice.paid":
        mark_paid(e["external_id"])               # idempoten
    return "ok"

Halaman bayar & QR sendiri

Paling mudah: arahkan pembeli ke checkout_url — sudah berisi QR, nominal dengan kode unik disorot, hitung mundur, dan berubah sendiri saat lunas (pembeli lalu diarahkan ke return_url). Pelanggan Pro bisa memberi warna toko dan menghapus merek QGateway.

Mau tampil di aplikasimu sendiri? Render qr_string dengan pustaka QR apa saja, atau pakai qr_image_url (PNG, cocok untuk bot WhatsApp/Telegram). Tampilkan total_amount persis dan pantau status lewat webhook.

Mode QR per QRIS: Dinamis (tag 01=12, nominal terkunci), Kompatibel (tag 01=11 + nominal, untuk pemindai yang menolak 12), Statis asli (QR tidak diubah, pembeli mengetik total — wajib untuk GoPay bila memakai detektor notifikasi HP).

Detektor pembayaran

HP Android (MacroDroid, gratis)

  1. Di HP yang menerima notifikasi pembayaran (GoBiz/GoPay Merchant, DANA Bisnis, myBCA, BRImo, Livin', ShopeePay Partner, dll.), pasang MacroDroid dari Play Store.
  2. Buat detektor di dasbor → salin token (dt_…).
  3. Makro baru → Trigger: Notification Received → pilih aplikasi pembayaran tadi.
  4. Action: HTTP Request:
URL     : https://qgateway.ruangasn.com/api/v1/ingest
Method  : POST
Header  : X-Device-Token: dt_xxxxxxxx   (dari menu Detektor)
Body    : application/json
{"source_app":"[notification_app_package]","title":"[notification_title]","text":"[notification]"}
  1. Makro kedua untuk detak jantung: Trigger Regular Interval 5 menit → HTTP Request POST https://qgateway.ruangasn.com/api/v1/heartbeat header token sama, body {"battery":"[battery]"}.
  2. Pengaturan HP → Baterai → MacroDroid: Tanpa batasan (wajib di Xiaomi, Oppo, Vivo, Samsung). Izinkan akses notifikasi & mulai otomatis.
  3. Uji: menu Detektor → Uji teks notifikasi, lalu bayar Rp 1.001 ke QRIS-mu sendiri.

Pembaca notifikasi hanya menerima kalimat uang masuk ("diterima", "masuk", "menerima") dan menolak kata uang keluar, gagal, refund, promo. Notifikasi kembar dalam 10 menit diabaikan. Bila nominal tidak terbaca, tagihan tetap menunggu — tidak pernah salah lunas.

GoBiz (GoPay Merchant) — beta

Hubungkan nomor GoBiz lewat OTP. Server membaca menu Keuangan → Pendapatan (tempat GoPay mencatat pembayaran QR bernominal) saat ada tagihan menunggu dan halaman bayar terbuka, maksimal sekali per 6 detik. Ini memakai portal web GoBiz yang bukan API resmi: bisa berubah sewaktu-waktu, jadi pasang juga detektor HP sebagai cadangan.

Kode galat

Bentuk: {"success": false, "error": {"code": "…", "message": "…"}}

HTTPcodeArti
401unauthorizedKunci API / token perangkat salah atau dicabut.
402insufficient_creditKuota gratis & saldo habis dan masa tenggang lewat (hanya LIVE).
403email_unverified, live_forbidden, account_suspendedVerifikasi email dulu / simulasi untuk tagihan LIVE / akun dinonaktifkan.
404not_foundTagihan tidak ada untuk kunci & mode ini.
409external_id_conflict, not_pendingexternal_id dipakai dengan nominal lain / status tidak bisa diubah.
422validation_failed, invalid_amount, qris_missingIsian tidak valid / belum ada QRIS.
429codes_exhausted, terlalu seringKode unik untuk nominal itu habis sementara / batas 120 permintaan per menit per kunci.

Integrasi pakai AI

Tempel prompt ini ke Claude Code, Cursor, Codex, Copilot, atau ChatGPT di proyekmu. AI akan menulis endpoint checkout, verifikasi webhook, dan tesnya.

Kamu senior engineer. Integrasikan pembayaran QRIS QGateway ke proyek ini. Dokumentasi: https://qgateway.ruangasn.com/docs

Fakta penting:
- Uang pembeli masuk langsung ke rekening merchant; QGateway hanya membuat nominal unik + mengirim webhook saat lunas.
- Kredensial dari environment, JANGAN di frontend: QGATEWAY_KEY (qg_test_… untuk uji, qg_live_… untuk produksi), QGATEWAY_WEBHOOK_SECRET (whsec_…).

Tugas:
1. Endpoint checkout di backend: POST https://qgateway.ruangasn.com/api/v1/invoices dengan header "Authorization: Bearer $QGATEWAY_KEY",
   body JSON {external_id: <ID pesanan unik>, amount: <rupiah, integer>, customer_name, return_url}.
   Simpan data.invoice_id & data.total_amount di pesanan, lalu redirect pembeli ke data.checkout_url.
   Permintaan ulang dengan external_id yang sama mengembalikan tagihan yang sama (aman di-retry).
2. Endpoint webhook POST /webhook/qgateway: baca body MENTAH, tolak bila |now - X-QGateway-Timestamp| > 300 detik,
   verifikasi X-QGateway-Signature == hex(HMAC_SHA256(timestamp + "." + rawBody, QGATEWAY_WEBHOOK_SECRET)) dengan
   perbandingan waktu-konstan. Kecualikan rute ini dari CSRF.
3. Bila event == "invoice.paid": tandai pesanan external_id lunas SECARA IDEMPOTEN (abaikan bila sudah lunas). Balas HTTP 200.
   Event lain: invoice.expired, invoice.cancelled (pesanan boleh dibatalkan).
4. Halaman status pesanan: tampilkan lunas/menunggu; boleh cek GET https://qgateway.ruangasn.com/api/v1/invoices/{invoice_id} sebagai cadangan.
5. Tulis tes: tanda tangan salah → 401; event sama dua kali → pesanan tetap satu kali lunas.
Uji memakai kunci qg_test_ lalu POST https://qgateway.ruangasn.com/api/v1/invoices/{id}/simulate untuk mensimulasikan pembayaran.