Dokumentasi API
Gateway QRIS menyediakan API JSON untuk membuat tagihan QRIS dinamis dari QRIS static merchant, memeriksa status, membatalkan tagihan, dan menerima notifikasi pembayaran.
Autentikasi
Setiap endpoint privat memerlukan API key pada header:
x-api-key: qrs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Kunci dibuat di panel admin → tab Kunci API. Nilai kunci dan secret hanya ditampilkan sekali saat pembuatan. Kunci disimpan di database sebagai SHA-256 hash.
Base URL
https://qris.valettashop.com/api/v1
Buat tagihan
POST /api/v1/invoices
curl -X POST 'https://qris.valettashop.com/api/v1/invoices' \
-H 'x-api-key: qrs_xxxx' \
-H 'Content-Type: application/json' \
-d '{
"order_id": "VS-20261119-0001",
"amount": 250000,
"keterangan": "Pesanan dress moto",
"customer_name": "Budi",
"customer_phone": "08123456789",
"callback_url": "https://valettashop.com/webhook.php",
"success_url": "https://valettashop.com/terimahkasih.php"
}'
Parameter
order_id(wajib, string, maks 64) — idempoten. Permintaan denganorder_idyang sama mengembalikan tagihan yang sama.amount(wajib, integer) — nominal dalam rupiah, minimal 1.000.keterangan(opsional) — keterangan tagihan.customer_name,customer_phone(opsional).callback_url(opsional) — URL yang dipanggil gateway saat tagihan lunas.success_url(opsional) — tujuan redirect setelah pembayaran.
Respons 201
{
"data": {
"id": "inv_9a7f1c2b4d5e6f70",
"ref_id": "A1B2C3D4",
"order_id": "VS-20261119-0001",
"status": "pending",
"amount": 250000,
"unique_code": 37,
"total_amount": 250037,
"qris_content": "00020101021226...",
"qr_image_url": "https://qris.valettashop.com/api/public/invoices/inv_9a7f1c2b4d5e6f70/qr.png",
"pay_url": "https://qris.valettashop.com/pay/inv_9a7f1c2b4d5e6f70",
"success_url": "https://valettashop.com/terimahkasih.php",
"callback_url": "https://valettashop.com/webhook.php",
"merchant_name": "Valettashop",
"merchant_city": "Jakarta",
"expires_at": "2026-11-19 03:30:00",
"paid_at": null,
"paid_amount": null
}
}
Pelanggan wajib membayar tepat total_amount (nominal + kode unik).
Kode unik memudahkan pencocokan mutasi bank dengan tagihan.
Cek status tagihan
GET /api/v1/invoices/{id} — {id} boleh berupa id atau ref_id.
curl 'https://qris.valettashop.com/api/v1/invoices/inv_9a7f1c2b4d5e6f70' \ -H 'x-api-key: qrs_xxxx'
Status yang mungkin: pending, paid, expired, cancelled.
Batalkan tagihan
POST /api/v1/invoices/{id}/cancel. Tagihan yang sudah lunas tidak bisa dibatalkan (HTTP 409).
Profil merchant
GET /api/v1/me — mengembalikan kode merchant, nama, kota, batas nominal, dan status konfigurasi QRIS static.
Endpoint publik (tanpa API key)
GET /api/public/invoices/{id}/qr.png— gambar PNG QRIS dynamic.GET /api/public/invoices/{id}/status— status ringkas untuk halaman bayar.
Webhook masuk (notifikasi pembayaran)
POST /api/v1/webhook — dipakai provider atau proses rekonsiliasi untuk memberi tahu
bahwa sebuah tagihan telah dibayar.
X-QiosPay-Signature: t=1731978000,v1=<hex>
Tanda tangan = HMAC-SHA256(webhook_secret, t + "." + raw_body), dibandingkan dengan
hash_equals. Timestamp yang lebih lama dari 600 detik ditolak (anti-replay).
Signature salah atau kosong → HTTP 401 dan event dicatat sebagai ditolak.
{
"id": "inv_9a7f1c2b4d5e6f70",
"status": "paid",
"paid_amount": 250037
}
Webhook keluar (callback ke merchant)
Saat tagihan ditandai lunas, gateway mengirim POST JSON ke callback_url dengan header
X-QiosPay-Signature: t=<unix>,v1=<hex> (HMAC-SHA256 dari
webhook_secret + "." + body). Format sengaja meniru QiosPay supaya webhook yang sudah
ada di Valettashop dapat dipakai tanpa perubahan.
Batas dan batasan
- Gateway ini tidak terhubung ke rekening bank atau provider pembayaran. Ia hanya mengubah QRIS static menjadi dynamic dan mencatat tagihan.
- Status lunas hanya dapat ditetapkan oleh webhook terverifikasi atau oleh admin yang sudah memeriksa mutasi. Klaim pelanggan tanpa bukti tidak pernah otomatis dianggap lunas.
- QRIS dynamic yang dihasilkan hanya berlaku untuk penagihan ke QRIS static milik merchant itu. Ihrac merchant, dibuat dari kode acuan akuntansi Anda.
- Konversi static → dynamic mengubah tag
01dari11menjadi12, menyisipkan tag54(nominal), lalu menghitung ulang CRC16 (tag63). - Nominal dibatasi Rp 1.000 – Rp 100.000.000 per tagihan.
Contoh integrasi (PHP)
$ch = curl_init('https://qris.valettashop.com/api/v1/invoices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'x-api-key: ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'order_id' => $orderNo,
'amount' => $total,
'callback_url' => 'https://valettashop.com/webhook.php',
]),
]);
$json = json_decode((string) curl_exec($ch), true);
$invoice = $json['data'] ?? null;