Gateway QRIS

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

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)

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

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;