Dokumentasi

API Clinqoo

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"

Kredensial

Setiap akun punya dua nilai. Kirim keduanya di header pada setiap permintaan tulis:

NilaiHeaderContoh
Merchant IDX-Merchant-Idmch_9f2c1a7b0d
API keyAuthorization: Bearerqsk_...

API key hanya boleh disimpan di server. Kalau salah satu nilai hilang atau tidak cocok, API membalas 401 dengan pesan yang jelas.

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',
    'Authorization': 'Bearer ' + process.env.QRIS_API_KEY,
    'X-Merchant-Id': process.env.QRIS_MERCHANT_ID
  },
  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