Dokumentasi
API QRIS.SITE
Tiga endpoint untuk menerima pembayaran QRIS: buat tagihan, cek status, dan terima notifikasi.
Ringkasan
Semua permintaan memakai JSON melalui HTTPS. Base URL mengikuti domain yang sedang dipakai:
https://qris-site.pages.dev
Respons selalu JSON. Kode status yang dipakai: 200 sukses, 400 input salah, 401 token tidak valid, 404 tidak ditemukan, 502 provider menolak.
Buat tagihan
POST /api/pay membuat tagihan baru dan mengembalikan QR serta URL checkout.
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
amount | integer | ya | Nominal rupiah, minimal 1.000, maksimal 100.000.000. |
description | string | tidak | Keterangan yang tampil ke pembeli (maks 200 karakter). |
reference | string | tidak | ID pesanan milikmu. Default: id tagihan. |
buyer_name | string | tidak | Nama pembeli untuk pencatatan. |
buyer_email | string | tidak | Email pembeli untuk pencatatan. |
curl -X POST https://qris-site.pages.dev/api/pay \
-H "Content-Type: application/json" \
-d '{
"amount": 150000,
"description": "Pesanan #1024",
"reference": "INV-1024"
}'
{
"id": "pay_m3k9a1f2b7c4",
"reference": "INV-1024",
"amount": 150000,
"fee": 1050,
"net_amount": 148950,
"status": "pending",
"mode": "demo",
"qr_string": "0002010102122667...",
"qr_image": "https://api.qrserver.com/v1/create-qr-code/?...",
"expires_at": "2026-11-17T14:00:00.000Z",
"checkout_url": "https://qris-site.pages.dev/bayar/pay_m3k9a1f2b7c4"
}
Bagikan checkout_url ke pembeli, atau render qr_image sendiri di halaman tokomu. Tagihan berlaku 15 menit.
Cek status
GET /api/pay/{id} — bisa memakai id tagihan atau referensi. Aman dipanggil berkala (polling).
curl https://qris-site.pages.dev/api/pay/pay_m3k9a1f2b7c4
Nilai status: pending, paid, expired, failed.
GET /api/pay?limit=10 mengembalikan daftar tagihan terbaru (ringkas, tanpa data pembeli) — berguna untuk menampilkan bukti aktivitas.
Webhook
Provider meneruskan notifikasi ke POST /api/webhook. Kamu tidak perlu memanggilnya sendiri; endpoint ini yang mengubah status tagihan menjadi lunas dan mencatat jejak audit.
Format yang diterima fleksibel: id/reference dibaca dari reference, order_id, merchant_ref, atau id. Status dibaca dari status dengan sinonim umum (success, settlement, capture, completed, lunas).
{
"reference": "INV-1024",
"status": "paid",
"amount": 150000,
"issuer": "gopay",
"paid_at": "2026-11-17T13:41:02Z"
}
Verifikasi tanda tangan
Bila WEBHOOK_SECRET dipasang, webhook tanpa tanda tangan valid akan ditolak (401) saat mode live. Tanda tangan = HMAC SHA-256 dari body mentah:
// Node.js
const crypto = require('crypto');
const expected = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(rawBody)
.digest('hex');
if (req.headers['x-signature'] !== expected) {
return res.status(401).end();
}
Alternatif sederhana: kirim secret yang sama pada header X-Webhook-Token.
Endpoint admin
Memakai header Authorization: Bearer <ADMIN_TOKEN>.
| Endpoint | Fungsi |
|---|---|
GET /api/payments | Daftar transaksi + ringkasan. Query: status, q, limit, offset. |
GET /api/health | Status layanan dan koneksi database. |
POST /api/demo-pay | Menandai tagihan lunas untuk pengujian (mode demo, atau admin token). |
curl https://qris-site.pages.dev/api/payments?status=paid&limit=20 \ -H "Authorization: Bearer $ADMIN_TOKEN"
Contoh kode
Membuat tagihan dari server Node, lalu menunggu status lunas:
const base = 'https://qris-site.pages.dev';
const res = await fetch(base + '/api/pay', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount: 150000, reference: 'INV-1024' })
});
const pay = await res.json();
console.log('Kirim pembeli ke:', pay.checkout_url);
// polling sederhana
let status = 'pending';
while (status === 'pending') {
await new Promise(r => setTimeout(r, 3000));
const s = await fetch(base + '/api/pay/' + pay.id).then(r => r.json());
status = s.status;
}
console.log('Hasil akhir:', status);