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
- Daftar → unggah QRIS statis toko di menu QRIS saya.
- Pasang detektor di menu Detektor (HP Android + MacroDroid, dan/atau GoBiz).
- Menu Aplikasi & API: buat kunci
qg_test_, isi URL webhook, tekan Kirim tes. - Buat tagihan dari server (di bawah), simulasikan lunas, pastikan webhook diterima.
- 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}
}'
| Field | Wajib | Keterangan |
|---|---|---|
external_id | ya | ID pesananmu (huruf, angka, . _ - : / #, maks 100). Idempoten: permintaan ulang mengembalikan tagihan yang sama selama masih menunggu/lunas. Juga diterima sebagai external_order_id. |
amount | ya | Nominal pokok (rupiah, bilangan bulat, 1 – 10.000.000). |
customer_name, customer_email, description | tidak | Tampil di halaman bayar & dasbor. |
return_url | tidak | Pembeli diarahkan ke sini setelah lunas, ditambah ?invoice_id=…&external_id=…&status=paid. Jangan menganggap lunas dari parameter ini — percayai webhook. |
webhook_url | tidak | Menimpa URL webhook aplikasi untuk tagihan ini. |
metadata | tidak | Objek bebas (maks 20 kunci / 2 KB), dikembalikan di webhook. |
ttl_minutes | tidak | Masa berlaku 1 – 1440 menit (bawaan per aplikasi, 15). |
qris_id | tidak | Pakai 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
| Endpoint | Fungsi |
|---|---|
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=20 | Daftar tagihan aplikasi ini (mode sesuai kunci). |
POST /api/v1/invoices/{id}/cancel | Batalkan tagihan yang masih menunggu → webhook invoice.cancelled. |
POST /api/v1/invoices/{id}/simulate | Hanya kunci qg_test_: tandai lunas seolah pembeli membayar. Tagihan LIVE ditolak 403. |
GET /api/v1/me | Cek 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_idatauX-QGateway-Deliverysebagai 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)
- Di HP yang menerima notifikasi pembayaran (GoBiz/GoPay Merchant, DANA Bisnis, myBCA, BRImo, Livin', ShopeePay Partner, dll.), pasang MacroDroid dari Play Store.
- Buat detektor di dasbor → salin token (
dt_…). - Makro baru → Trigger: Notification Received → pilih aplikasi pembayaran tadi.
- 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]"}
- Makro kedua untuk detak jantung: Trigger Regular Interval 5 menit → HTTP Request
POST https://qgateway.ruangasn.com/api/v1/heartbeatheader token sama, body{"battery":"[battery]"}. - Pengaturan HP → Baterai → MacroDroid: Tanpa batasan (wajib di Xiaomi, Oppo, Vivo, Samsung). Izinkan akses notifikasi & mulai otomatis.
- 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": "…"}}
| HTTP | code | Arti |
|---|---|---|
| 401 | unauthorized | Kunci API / token perangkat salah atau dicabut. |
| 402 | insufficient_credit | Kuota gratis & saldo habis dan masa tenggang lewat (hanya LIVE). |
| 403 | email_unverified, live_forbidden, account_suspended | Verifikasi email dulu / simulasi untuk tagihan LIVE / akun dinonaktifkan. |
| 404 | not_found | Tagihan tidak ada untuk kunci & mode ini. |
| 409 | external_id_conflict, not_pending | external_id dipakai dengan nominal lain / status tidak bisa diubah. |
| 422 | validation_failed, invalid_amount, qris_missing | Isian tidak valid / belum ada QRIS. |
| 429 | codes_exhausted, terlalu sering | Kode 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.