Dokumentasi API
Base URL: . Semua request & respons memakai JSON. Nominal dalam Rupiah (bilangan bulat).
Mulai cepat
- Daftar, lalu di menu QRIS & Shopee simpan QRIS statis dan token Shopee Partner Anda.
- Buat Project → simpan API key Live (
byr_live_…) & Sandbox (byr_test_…). - Isi Webhook URL server Anda (opsional, sangat disarankan).
- Panggil
POST /api/v1/orders, kirimqr_image_url/checkout_urlke pembeli. - Terima webhook
order.paid→ kirim produk ke pembeli.
Selama pengembangan, pakai API key Sandbox lalu lunasi order lewat simulasi.
Autentikasi
Kirim API key di header Authorization. Jangan pernah menaruh API key di kode frontend/browser.
Authorization: Bearer byr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Batas: 120 request/menit per project.
Buat order
| Field | Tipe | Keterangan |
|---|---|---|
amount | integer | Wajib. Nominal dasar (min 100). Kode unik 1–99 ditambahkan otomatis → total. |
reference_id | string | ID pesanan di sistem Anda (maks 64). Idempoten: reference sama → order yang sama dikembalikan. |
description | string | Keterangan, tampil di halaman bayar (maks 200). |
customer_name | string | Nama pembeli (maks 80). |
expires_in | integer | Masa berlaku dalam menit, 1 sampai 1440 (24 jam). Default 15. |
return_url | string | URL tujuan setelah bayar/kedaluwarsa (halaman checkout). |
metadata | object | Data bebas (maks 2000 karakter JSON), dikembalikan di webhook. |
unique_code | boolean | Default true. false = nominal persis tanpa kode unik (ditolak jika ada order pending bernominal sama). |
curl -X POST {{BASE}}/api/v1/orders \
-H "Authorization: Bearer byr_test_xxx" \
-H "Content-Type: application/json" \
-d '{"amount":10000,"reference_id":"INV-1001","description":"Top up 86 diamond","customer_name":"Andi"}'
Respons 201:
{
"success": true,
"data": {
"id": "ord_Xy12…",
"reference_id": "INV-1001",
"status": "pending",
"test": true,
"amount": 10000,
"unique_code": 37,
"total": 10037,
"description": "Top up 86 diamond",
"customer_name": "Andi",
"metadata": null,
"qris_string": "00020101021226…6304ABCD",
"qr_image_url": "{{BASE}}/pay/ord_Xy12…/qr.png",
"checkout_url": "{{BASE}}/pay/ord_Xy12…",
"return_url": null,
"transaction_id": null,
"issuer": null,
"created_at": "2026-11-20T05:00:00.000Z",
"expires_at": "2026-11-20T05:15:00.000Z",
"paid_at": null
}
}
Pembeli harus membayar tepat sebesar total. qr_image_url menerima ?size=200..1024.
Cek order
Mengembalikan objek order seperti di atas. Status: pending, paid, expired, cancelled.
Memanggil endpoint ini juga memicu pengecekan ke Shopee (dibatasi tiap 8 detik). Jika memakai polling, cukup tiap 5–10 detik: webhook lebih disarankan.
Daftar order
Maks limit 100, urut terbaru.
Batalkan order
Hanya untuk order pending. Memicu webhook order.cancelled.
Simulasi pembayaran (sandbox)
Hanya dengan API key byr_test_…. Menandai order lunas dan mengirim webhook order.paid: untuk menguji alur bot Anda.
Info project
{ "project": {"id":1,"name":"Bot WA"}, "mode":"live", "merchant_name":"TOKO ANDA",
"qris_ready": true, "shopee_status": "valid", "plan_active": true, "plan_until": "2027-01-13T00:00:00.000Z" }
Webhook
Saat status order berubah, server kami mengirim POST ke Webhook URL project Anda:
POST https://server-anda.com/webhook
Content-Type: application/json
X-Webhook-Event: order.paid
X-Signature: <hex HMAC-SHA256(raw body, webhook secret)>
{ "event": "order.paid", "data": { …objek order… }, "sent_at": "2026-11-20T05:03:12.000Z" }
Event: order.paid, order.expired, order.cancelled, dan test (tombol "Tes" di dashboard).
- Balas dengan HTTP 2xx dalam 10 detik. Jika gagal, dikirim ulang setelah 30 dtk, 2 mnt, 10 mnt, 30 mnt, 2 jam.
- Selalu verifikasi
X-Signaturememakai raw body sebelum memproses. - Proses secara idempoten (cek
data.id): webhook bisa terkirim lebih dari sekali. - URL webhook harus bisa diakses publik (IP privat/localhost ditolak).
// Node.js + Express: verifikasi signature
const crypto = require('crypto');
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(req.body).digest('hex');
const given = String(req.headers['x-signature'] || '');
if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
return res.sendStatus(401);
}
const { event, data } = JSON.parse(req.body);
if (event === 'order.paid') {
// TODO: tandai pesanan data.reference_id lunas & kirim produk (idempoten!)
}
res.sendStatus(200);
});
// PHP: verifikasi signature
$raw = file_get_contents('php://input');
$sig = hash_hmac('sha256', $raw, getenv('WEBHOOK_SECRET'));
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$payload = json_decode($raw, true);
Kode error
| HTTP | code | Arti |
|---|---|---|
| 400 | invalid_amount, invalid_reference, invalid_expires_in, … | Input tidak valid |
| 401 | missing_api_key, invalid_api_key | API key salah / tidak dikirim |
| 402 | subscription_expired | Langganan habis (hanya mode Live) |
| 403 | account_suspended, live_mode | Akun dinonaktifkan / simulasi dengan key Live |
| 404 | not_found | Order tidak ditemukan |
| 409 | qris_not_set, detector_inactive, duplicate_reference, amount_in_use, invalid_status | Konfigurasi/kondisi belum sesuai |
| 429 | rate_limited | Terlalu banyak request |
| 503 | busy | Semua kode unik untuk nominal itu sedang terpakai |
Format error: { "error": "pesan", "code": "kode" }
Contoh: bot WhatsApp (Baileys)
// .env bot: JAGOBAYAR_URL={{BASE}} JAGOBAYAR_KEY=byr_live_xxx WEBHOOK_SECRET=whsec_xxx
const axios = require('axios');
const api = axios.create({
baseURL: process.env.JAGOBAYAR_URL + '/api/v1',
headers: { Authorization: 'Bearer ' + process.env.JAGOBAYAR_KEY },
timeout: 15000,
});
// Perintah: .beli diamond86
async function handleBeli(sock, msg, produk) {
const jid = msg.key.remoteJid;
try {
const { data } = await api.post('/orders', {
amount: produk.harga,
reference_id: `WA-${Date.now()}`,
description: produk.nama,
customer_name: msg.pushName || 'Pembeli',
metadata: { jid, produk: produk.kode },
});
const o = data.data;
await sock.sendMessage(jid, {
image: { url: o.qr_image_url },
caption: `*Tagihan ${produk.nama}*\n\nTotal bayar: *Rp${o.total.toLocaleString('id-ID')}*\n` +
`(harus PERSIS, termasuk kode unik)\nBerlaku 15 menit.\n\nAtau bayar lewat: ${o.checkout_url}`,
});
} catch (e) {
const err = e.response?.data?.error || e.message;
await sock.sendMessage(jid, { text: 'Gagal membuat tagihan: ' + err });
}
}
// Webhook (Express di proses bot yang sama)
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
/* …verifikasi X-Signature seperti di atas… */
const { event, data } = JSON.parse(req.body);
res.sendStatus(200); // balas cepat
if (event === 'order.paid') {
const { jid, produk } = data.metadata || {};
await sock.sendMessage(jid, { text: `✅ Pembayaran Rp${data.total.toLocaleString('id-ID')} diterima! Pesanan ${produk} diproses.` });
} else if (event === 'order.expired') {
await sock.sendMessage(data.metadata.jid, { text: '⌛ Tagihan kedaluwarsa. Ketik .beli lagi untuk membuat tagihan baru.' });
}
});