RisaPay API Docs

1 Mulai Cepat

Lima langkah dari nol sampai menerima pembayaran.

① Daftar, terus ambil api_key, merchant_code (misal R39), private_key di dashboard.
② Hit POST api/transaction/create, simpan data.reference.
③ Tampilkan QR / nomor VA / link bayar ke pelanggan - atau arahkan ke {base}checkout/?page={reference}.
④ Siapin endpoint callback: verify signature → match nominal → mark paid → balas 200.
⑤ Polling/rekon berkala via GET api/transaction/detail.

2 Autentikasi

Satu header untuk semua request.

Regenerate key di dashboard = key lama auto mati. Key kosong/salah → JSON success:false (HTTP 200, bukan 401. Yang 429 cuma rate-limit).

3 Signature Request

HMAC-SHA256 dari string mentah yang dikirim.

amount adalah string persis seperti dikirim ("50000", bukan angka format). RisaPay match ke semua merchant milikmu buat nemuin merchant_code yang kepake.

4 Buat Transaksi

Body form-encoded, bukan JSON.

PHPSalin$merchantCode = 'R39';
$merchantRef  = 'INV-2026-0001';
$amount       = '50000';
$signature = hash_hmac('sha256', $merchantCode . $merchantRef . $amount, $privateKey);

$ch = curl_init('https://risapay.xfazrin.my.id/api/transaction/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
    CURLOPT_POSTFIELDS => http_build_query([
        'method' => 'QRIS', 'merchant_ref' => $merchantRef, 'amount' => $amount,
        'customer_name' => 'Budi', 'customer_email' => 'budi@mail.com',
        'customer_phone' => '081234567890', 'signature' => $signature,
    ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
$reference = $res['data']['reference']; // SIMPAN - kunci segalanya

Node.jsSalinconst crypto = require('crypto');
const merchantCode = 'R39', merchantRef = 'INV-2026-0001', amount = '50000';
const signature = crypto.createHmac('sha256', process.env.RISAPAY_PRIVATE_KEY)
  .update(merchantCode + merchantRef + amount).digest('hex');

const body = new URLSearchParams({ method: 'QRIS', merchant_ref: merchantRef,
  amount, customer_name: 'Budi', signature });
const r = await fetch('https://risapay.xfazrin.my.id/api/transaction/create', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + process.env.RISAPAY_API_KEY },
  body });
const res = await r.json();
const reference = res.data.reference; // SIMPAN

cURLSalincurl -X POST "https://risapay.xfazrin.my.id/api/transaction/create" \
  -H "Authorization: Bearer API_KEY_KAMU" \
  --data-urlencode "method=QRIS" \
  --data-urlencode "merchant_ref=INV-2026-0001" \
  --data-urlencode "amount=50000" \
  --data-urlencode "customer_name=Budi" \
  --data-urlencode "signature=HASH_HMAC_KAMU"

VALID - Respons QRIS - HTTP 200Salin{
    "success": true,
    "message": "Successfully generate transaction",
    "data": {
        "reference": "R1700000000XXXXX",
        "merchant_ref": "INV-2026-0001",
        "payment_method": "QRIS",
        "amount": 50000,
        "fee_merchant": 70,
        "fee_customer": 0,
        "total_fee": 70,
        "amount_received": 49930,
        "pay_code": null,
        "pay_url": null,
        "status": "UNPAID",
        "expired_time": 1700172800,
        "qr_string": "00020101..."
    }
}

QRIS → render qr_string jadi QR · VA → tampilin pay_code · e-wallet → redirect ke pay_url · atau lempar semua ke {base}checkout/?page={reference}.

VALID - Respons VA - field yang bedaSalin{
    "success": true,
    "data": {
        "reference": "R1700000000XXXXX",
        "payment_method": "BRIVA",
        "payment_name": "BRI Virtual Account",
        "amount": 50000,
        "fee_merchant": 3250,
        "amount_received": 46750,
        "pay_code": "88810123456789",
        "status": "UNPAID",
        "expired_time": 1700086400
    }
}

GAGAL - HTTP 200Salin{
    "success": false,
    "message": "Invalid signature"
}

5 Cek Status

Buat polling & rekon. Cuma transaksi milik api_key itu yang kebaca.

cURLSalincurl "https://risapay.xfazrin.my.id/api/transaction/detail?reference=R1700000000XXXXX" \
  -H "Authorization: Bearer API_KEY_KAMU"

VALID - HTTP 200Salin{
    "success": true,
    "message": "Transaction found",
    "data": {
        "reference": "R1700000000XXXXX",
        "merchant_ref": "INV-2026-0001",
        "payment_method": "QRIS",
        "amount": "10000",
        "status": "UNPAID",
        "paid_at": null,
        "expired_time": "1700172800",
        "qr_string": "00020101...",
        "checkout_url": "https://..."
    }
}

paid_at = unix timestamp pas lunas, null kalau belum. checkout_url itu alias dari pay_url.

GAGALSalin{ "success": false, "message": "Transaction not found" }
{ "success": false, "message": "Invalid API Key" }

6 OVO Push (2 langkah)

Flow khusus OVO: create dulu, baru push bill ke HP user.

① POST api/transaction/create dengan method=OVO → dapet reference.
② Tanpa Authorization:

FormSalinreference=R1700000000XXXXX&ovo_number=0812xxxx

VALIDSalin{ "status": "PAID", "message": "Periksa aplikasi OVO Anda" }

GAGALSalin{ "status": "GAGAL", "message": "Gagal update ke database" }
{ "status": "GAGAL", "message": "Server Error 500 ..." }

7 Callback ke Merchant

Wajib implement. Auto-retry 3x kalau respons bukan 200.

VALID - Payload (14 field)Salin{
    "reference": "R1715094140S41FP",
    "merchant_ref": "Q3123660",
    "payment_method": "QRIS",
    "payment_method_code": "QRIS",
    "total_amount": 117,
    "fee_merchant": 0,
    "fee_customer": 0,
    "total_fee": 0,
    "amount_received": 117,
    "is_closed_payment": 1,
    "status": "PAID",
    "paid_at": 1715094192,
    "note": "Transaksi sukses"
}

Verifikasi - PHPSalin$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_CALLBACK_SIGNATURE'] ?? '';
$calc = hash_hmac('sha256', $raw, $privateKeyAnda);
if (!hash_equals($calc, $sig)) { http_response_code(403); exit; }
$data = json_decode($raw, true);
// cocokkan merchant_ref + total_amount, tandai lunas per $data['reference'] (idempoten!)
http_response_code(200);

Verifikasi - Node.jsSalin// butuh express.raw({ type: 'application/json' }) agar dapat Buffer mentah
const sig = req.headers['x-callback-signature'] || '';
const calc = crypto.createHmac('sha256', process.env.RISAPAY_PRIVATE_KEY)
  .update(req.body).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(calc), Buffer.from(sig)))
  return res.sendStatus(403);
const data = JSON.parse(req.body.toString());
// ... tandai lunas per data.reference (idempoten)
res.sendStatus(200);

8 Referensi Error

Komplet, semua message diambil langsung dari code.

9 Status & Masa Berlaku

Lifecycle satu transaksi.

expired_time default 24 jam (VA) / 48 jam (lainnya), bisa di-override manual. Jangan mark paid dari return page, cuma dari verified callback atau detail = PAID.

10 Channel & Biaya (live dari database)

22 channel aktif.

↓ Unduhan

Start tanpa ngetik dari nol.

Import Postman → isi environment base_url, api_key, merchant_code, private_key - signature & merchant_ref auto-generate. Paste risapay-api.md ke AI favoritmu, langsung paham full flow.