Dokumentasi API PayBridge

Terima pembayaran QRIS dan Virtual Account dengan satu API sederhana. Tanpa signature rumit, tanpa menunggu — daftar, ambil API key, dan transaksi uji pertamamu jalan dalam hitungan menit.

Mulai dalam 10 menit

1. Daftar akun → menu Developer → buat aplikasi → salin API key (pb_test_…).

2. Buat pembayaran pertama:

curl -X POST https://pay.idcloudhost.com/v1/payments \
  -H "Authorization: Bearer pb_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-001" \
  -d '{"amount": 150000, "rail": "qris", "reference": "INV/001"}'

Respons berisi qr_content — render sebagai gambar QR (mis. npm qrcode) dan tunjukkan ke pembayar.

3. Set webhook URL di menu Developer, lalu buka pembayaran tadi di portal dan klik Simulasikan lunas. Webhook payment.paid tiba di server-mu — integrasi selesai.

Autentikasi

Semua request memakai API key di header Authorization:

Authorization: Bearer pb_test_xxx

API key diterbitkan per aplikasi di portal, tampil sekali saat dibuat. Tidak ada signature, timestamp, atau header tambahan — cukup key ini lewat HTTPS.

Test vs live

Environment ditentukan oleh prefix key, bukan base URL — kode integrasi tidak berubah:

Idempotency

Semua POST wajib menyertakan header Idempotency-Key — pakai ID unik dari sistemmu (mis. nomor invoice). Request ulang dengan key sama mengembalikan hasil pertama (HTTP 200), tidak pernah membuat transaksi ganda. Timeout? Kirim ulang saja dengan key yang sama.

Rate limit

120 request per menit per API key. Terlampaui → HTTP 429 dengan header Retry-After (detik). Hormati nilainya, lalu ulangi request yang sama (aman — idempotency).

Membuat pembayaran

POST /v1/payments

Respons 201:

{
  "id": "pay_x8Kj2…",
  "status": "pending",
  "amount": 150000,
  "rail": "qris",
  "reference": "INV/001",
  "qr_content": "00020101…",        // rail=qris → render jadi QR
  "va_number": null,                 // rail=va → nomor VA
  "va_bank": null,
  "hosted_url": "https://pay.idcloudhost.com/p/pay_x8Kj2…",
  "expires_at": "2026-08-19T15:30:00.000Z",
  "paid_at": null,
  "metadata": null,
  "created_at": "2026-08-19T14:30:00.000Z"
}

Halaman bayar hosted — tanpa frontend sama sekali

Setiap payment membawa hosted_url: halaman bayar siap pakai yang bisa kamu kirim langsung ke pelanggan (WhatsApp, email, SMS). Halaman itu menampilkan nama usahamu, nominal, QR yang sudah dirender (atau nomor VA + tombol salin), memperbarui statusnya sendiri saat pembayaran masuk, dan menangani kedaluwarsa. Kalau kamu tidak ingin membangun tampilan pembayaran sendiri, cukup teruskan tautan ini — integrasi minimummu tinggal dua hal: buat payment, dengarkan webhook.

Siklus status

pending ──► paid ──► refunded
   ├──────► expired
   └──────► failed

Hanya lima status, tidak ada yang keenam. Kasus tak lazim dari penyedia (mis. lebih bayar) masuk array flags — integrasi sederhana boleh mengabaikannya dan tetap benar.

Membaca pembayaran

GET /v1/payments/{id} — satu pembayaran.
GET /v1/payments?reference=INV/001 — cari berdasarkan referensimu.
GET /v1/payments?status=paid&limit=100 — daftar, terbaru dulu.

Objek yang dikembalikan selalu berbentuk sama dengan respons create. Gunakan ini sebagai jaring pengaman (mis. cron rekonsiliasi) — mekanisme utama pelunasan adalah webhook.

Refund

POST /v1/payments/{id}/refunds

curl -X POST https://pay.idcloudhost.com/v1/payments/pay_x8Kj2/refunds \
  -H "Authorization: Bearer pb_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rf-001" \
  -d '{"amount": 50000, "reason": "Kelebihan bayar"}'

amount opsional (default: penuh). Refund parsial boleh berulang sampai total = nominal asal. Hanya pembayaran berstatus paid yang bisa direfund.

Menerima webhook

Set webhook URL per aplikasi di portal. Event dikirim sebagai POST JSON:

{
  "id": "evt_9aB3…",             // dedup dengan id ini
  "type": "payment.paid",
  "created_at": "2026-08-19T14:35:12.000Z",
  "data": { …objek payment utuh… }
}

Balas 2xx secepatnya (proses berat kerjakan async). Aturan yang menyelamatkan kamu dari insiden klasik:

• Dedup per id event — pengiriman minimal-sekali, duplikat mungkin terjadi.
• Jangan andalkan urutan tiba — nilai kebenaran ada di field status, bukan urutan.

Verifikasi signature

Setiap webhook membawa header PayBridge-Signature:

PayBridge-Signature: t=1755612912,v1=5f8a…

v1 = HMAC-SHA256(signing secret, t + "." + body). Signing secret ada di menu Developer. Node.js:

const crypto = require('node:crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(s => s.split('=')));
  const calc = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(calc));
}

PHP:

function verify(string $rawBody, string $header, string $secret): bool {
  parse_str(str_replace(',', '&', $header), $p);
  $calc = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
  return hash_equals($calc, $p['v1']);
}

Retry & replay

Webhook yang tidak dibalas 2xx diulang dengan backoff: 1m → 5m → 15m → 1j → 3j → 6j → 12j → 24j. Setelah itu masuk dead-letter dan bisa di-replay kapan pun dari halaman Webhook di portal — bersama seluruh riwayat pengiriman, status, dan jumlah percobaannya.

Kode error

Semua error berbentuk sama — code stabil untuk mesin, message menyebut nilai yang salah, doc_url menaut kemari:

{ "error": { "code": "…", "message": "…", "doc_url": "…" } }

Sandbox

Akun baru langsung berada di mode sandbox — tidak perlu menunggu apa pun untuk mulai menulis kode. Perilaku sandbox identik dengan produksi (endpoint, format, error), bedanya:

• Pembayaran tidak melibatkan dana riil.
• Pelunasan dipicu manual: buka pembayaran di portal → Simulasikan lunas — webhook payment.paid terkirim sungguhan ke server-mu.
• Jalan ke produksi dibuka lewat Sertifikasi — mandiri, tanpa menunggu review manual.

Sertifikasi → live

Akses live tidak menunggu email atau rapat sign-off. Halaman Sertifikasi di portal berisi 9 butir yang tercentang otomatis dari bukti nyata saat integrasimu melakukannya di sandbox:

Sembilan centang penuh → akses live terbuka detik itu juga: buat key pb_live_, ganti prefix key di konfigurasi, selesai.

Butir-butir ini bukan formalitas — mereka persis daftar penyebab insiden payment paling umum, jadi lulus sertifikasi berarti integrasimu sudah tahan di skenario yang biasanya baru ketahuan di produksi.

PayBridge · pay.idcloudhost.com · Pertanyaan? alfian@idcloudhost.com