Dokumentasi API

Base URL: . Semua request & respons memakai JSON. Nominal dalam Rupiah (bilangan bulat).

Mulai cepat

  1. Daftar, lalu di menu QRIS & Shopee simpan QRIS statis dan token Shopee Partner Anda.
  2. Buat Project → simpan API key Live (byr_live_…) & Sandbox (byr_test_…).
  3. Isi Webhook URL server Anda (opsional, sangat disarankan).
  4. Panggil POST /api/v1/orders, kirim qr_image_url / checkout_url ke pembeli.
  5. 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

POST/api/v1/orders
FieldTipeKeterangan
amountintegerWajib. Nominal dasar (min 100). Kode unik 1–99 ditambahkan otomatis → total.
reference_idstringID pesanan di sistem Anda (maks 64). Idempoten: reference sama → order yang sama dikembalikan.
descriptionstringKeterangan, tampil di halaman bayar (maks 200).
customer_namestringNama pembeli (maks 80).
expires_inintegerMasa berlaku dalam menit, 1 sampai 1440 (24 jam). Default 15.
return_urlstringURL tujuan setelah bayar/kedaluwarsa (halaman checkout).
metadataobjectData bebas (maks 2000 karakter JSON), dikembalikan di webhook.
unique_codebooleanDefault 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

GET/api/v1/orders/{id}

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

GET/api/v1/orders?status=paid&limit=20&reference_id=INV-1001

Maks limit 100, urut terbaru.

Batalkan order

POST/api/v1/orders/{id}/cancel

Hanya untuk order pending. Memicu webhook order.cancelled.

Simulasi pembayaran (sandbox)

POST/api/v1/orders/{id}/simulate

Hanya dengan API key byr_test_…. Menandai order lunas dan mengirim webhook order.paid: untuk menguji alur bot Anda.

Info project

GET/api/v1/me
{ "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).

// 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

HTTPcodeArti
400invalid_amount, invalid_reference, invalid_expires_in, …Input tidak valid
401missing_api_key, invalid_api_keyAPI key salah / tidak dikirim
402subscription_expiredLangganan habis (hanya mode Live)
403account_suspended, live_modeAkun dinonaktifkan / simulasi dengan key Live
404not_foundOrder tidak ditemukan
409qris_not_set, detector_inactive, duplicate_reference, amount_in_use, invalid_statusKonfigurasi/kondisi belum sesuai
429rate_limitedTerlalu banyak request
503busySemua 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.' });
  }
});