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.

FieldTipeWajibKeterangan
amountintegeryaNominal rupiah, minimal 1.000, maksimal 100.000.000.
descriptionstringtidakKeterangan yang tampil ke pembeli (maks 200 karakter).
referencestringtidakID pesanan milikmu. Default: id tagihan.
buyer_namestringtidakNama pembeli untuk pencatatan.
buyer_emailstringtidakEmail 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.

Penarikan

Pencairan saldo tidak otomatis: pengguna mengajukan lewat POST /api/me/withdrawals, lalu admin memprosesnya. Saldo tersedia = total net transaksi lunas − pengajuan yang masih berjalan.

curl -X POST https://qris-site.pages.dev/api/me/withdrawals \
  -H "Content-Type: application/json" \
  -H "Cookie: qris_session=..." \
  -d '{"amount":50000,"bank_name":"BCA","account_number":"1234567890","account_name":"Nama Pemilik"}'

Endpoint admin

Memakai header Authorization: Bearer <ADMIN_TOKEN>.

EndpointFungsi
GET /api/paymentsDaftar transaksi + ringkasan. Query: status, q, limit, offset.
GET /api/healthStatus layanan dan koneksi database.
POST /api/demo-payMenandai 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);

Kembali ke beranda