API Documentation

Merchant API untuk integrasi pembayaran QRIS. Base URL: https://qrislive.web.id

Authentication

Semua endpoint Merchant API menggunakan API Key sebagai bearer token. Kirim via header:

Authorization: Bearer qris_<your_api_key>

API Key didapat saat membuat merchant melalui dashboard. Setiap merchant memiliki key sendiri.

Fee Structure

Dua mode fee yang bisa dipilih per merchant di dashboard:

Fee by User

default

Customer bayar amount + fee. Merchant terima amount penuh.

Fee by Merchant

opsi

Customer bayar amount saja. Fee dipotong dari settlement merchant.

Rate

-

0.7% + Rp200 per transaksi

Contoh (by user)

-

Rp10.000 → fee Rp270 → total Rp10.270

Contoh (by merchant)

-

Rp10.000 → fee Rp270 → settlement Rp9.730

Unique code

-

Digit 0-999 sebagai pembeda nominal yang sama

Semua nominal dalam rupiah (integer). Minimal Rp500.

Endpoints

POST/api/v1/transaction/createAPI Key (Bearer)

Buat transaksi baru. Dapatkan QRIS string + payment link untuk dibagikan ke customer.

Parameters

amount*

integer

Nominal transaksi (Rp). Min 500, max 10.000.000.000

reference

string

Opsional. Referensi invoice. Auto-generate jika dikosongkan.

Request Body

{
  "amount": 10000,
  "reference": "INV-250717-3841"
}

Response 201

{
  "transaction_id": "a1b2c3d4e5f6...",
  "reference": "INV-250717-3841",
  "amount": 10000,
  "fee_amount": 270,
  "unique_code": 42,
  "fee_side": "user",
  "total_amount": 10312,
  "qris_string": "00020101021226...",
  "qris_url": null,
  "status": "pending",
  "payment_url": "https://qrislive.web.id/pay/a1b2c3d4e5f6...",
  "expires_at": "2026-07-17T15:26:00.000Z"
}

Error Codes

400Invalid JSON atau amount di luar range

401Missing atau invalid API key

403Merchant disabled

409Reference already exists

GET/api/v1/transaction/:id/statusAPI Key (Bearer)

Cek status transaksi. Otomatis expire jika sudah lewat waktu.

Parameters

id*

string (path)

ID transaksi yang didapat dari response create

Response 200

{
  "transaction_id": "a1b2c3d4e5f6...",
  "reference": "INV-250717-3841",
  "amount": 10000,
  "fee_amount": 270,
  "unique_code": 42,
  "total_amount": 10312,
  "fee_side": "user",
  "status": "paid",
  "paid_at": "2026-07-17T15:10:00.000Z",
  "created_at": "2026-07-17T15:00:00.000Z",
  "expires_at": "2026-07-17T15:15:00.000Z"
}

Error Codes

401Missing atau invalid API key

404Transaction not found

GET/api/v1/merchant/balanceAPI Key (Bearer)

Cek saldo settlement yang tersedia untuk withdraw.

Parameters

Tidak ada parameter. Response langsung balance user yang terautentikasi.

Response 200

{
  "merchant_id": "merchant-id-xxx",
  "name": "Toko Saya",
  "available_balance": 250000
}

Error Codes

401Missing atau invalid API key

Payment Link

Setiap transaksi otomatis mendapat payment URLyang bisa dibagikan ke customer. Customer buka link → liat QR code → scan → bayar.

Format/pay/{transaction_id}

Contohhttps://qrislive.web.id/pay/a1b2c3d4e5f6...

QR ExpiryQR code otomatis nonaktif (410) setelah dibayar atau expired

QR Image Endpoint

QR code juga bisa diakses langsung sebagai gambar PNG (generated on-the-fly, tidak ada storage):

GET /api/v1/pay/{id}/qr
(public, no auth)

200 → image/png
404 → Transaction not found
410 → QR expired

Webhook

Saat transaksi berstatus paid, sistem mengirim POST ke webhook_url merchant. Sekali kirim, tidak ada retry otomatis.Kirim ulang manual via dashboard Webhook Log jika gagal.

Headers

X-SignatureHMAC-SHA256 dari body, menggunakan secret key merchant

X-Transaction-IdID transaksi yang dibayar

Content-Typeapplication/json

Payload

{
  "event": "transaction.paid",
  "transaction_id": "a1b2c3d4e5f6...",
  "reference": "INV-250717-3841",
  "amount": 10000,
  "fee_amount": 270,
  "fee_side": "user",
  "total_amount": 10312,
  "status": "paid",
  "paid_at": "2026-07-17T15:10:00.000Z"
}

Verifikasi Signature

Gunakan secret key merchant untuk memastikan webhook benar-benar dari kami.

// Node.js
const crypto = require("crypto");
const signature = crypto
  .createHmac("sha256", YOUR_SECRET_KEY)
  .update(JSON.stringify(req.body))
  .digest("hex");
const isValid = timingSafeEqual(signature, req.headers["x-signature"]);

Error Response

Semua error mengembalikan format JSON seragam:

{
  "error": "Deskripsi error"
}

400 — Bad request (invalid input)

401 — Unauthorized (API key missing/invalid)

403 — Forbidden (merchant disabled)

404 — Not found

409 — Conflict (duplicate reference)

Quick Start

Contoh integrasi dengan cURL:

1. Buat transaksi + dapatkan payment link

curl -X POST https://qrislive.web.id/api/v1/transaction/create \
  -H "Authorization: Bearer qris_<api_key>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000}' | python -m json.tool

Response termasuk payment_url — bagikan link itu ke customer.

2. Cek status

curl https://qrislive.web.id/api/v1/transaction/<id>/status \
  -H "Authorization: Bearer qris_<api_key>"

3. Cek saldo

curl https://qrislive.web.id/api/v1/merchant/balance \
  -H "Authorization: Bearer qris_<api_key>"