Quickstart

Kamu butuh test API key dan sebuah proyek yang menerima metode pembayaran yang kamu coba. Kalau belum punya keduanya, buat proyek di sandbox (semua metode tersedia di sana) dan ambil test key. Simpan key di environment variable:

export BAIYAR_KEY="bk_test_…"
export BAIYAR_API="https://api.baiyar.com"

1. Periksa key

curl "$BAIYAR_API/v1/account" -H "Authorization: Bearer $BAIYAR_KEY"

{
  "data": {
    "livemode": false,
    "merchant": { "id": "mer_01k7…" },
    "project": { "id": "prj_01k7…" },
    "key": { "id": "apk_01k7…", "kind": "project", "scopes": ["payments:read", "payments:write"] }
  },
  "meta": { "request_id": "req_…" }
}

Setiap jawaban punya dua bagian yang sama: data adalah yang kamu minta, dan meta tentang request-nya (request_id, dan untuk daftar, paginasinya). data.livemode: false menandakan ini test key.

2. Buat pembayaran

Pembayaran butuh Idempotency-Key. Saat mengulang request yang timeout, kirim key dan body yang sama agar Baiyar mengembalikan pembayaran yang sama. Nominal API memakai satuan terkecil mata uang: Rp10.000 adalah 1000000.

curl "$BAIYAR_API/v1/payments" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000000,
    "currency": "IDR",
    "payment_method": "payment.qris",
    "merchant_reference": "order-1001",
    "description": "Order 1001",
    "customer": { "name": "Sari Wijaya", "email": "sari@example.com" }
  }'

Jawabannya (201) berisi pembayaran di data. status awalnya pending; instruction berisi cara pembayar menyelesaikan pembayaran. Untuk QRIS bentuknya { "type": "qr", "qr_content": "…", "expires_at": "…" }: tampilkan qr_content sebagai kode QR. Metode lain menjawab dengan virtual account (va), tautan e-wallet (ewallet_link), push e-wallet (ewallet_push), atau kode gerai (retail_code).

Field request yang dipakai dalam contoh:

Field	Tujuan
amount, currency	Nominal dasar sebelum biaya dan kode mata uangnya. IDR dikirim sebagai bilangan bulat dalam satuan terkecil, bukan rupiah langsung.
payment_method	Metode yang diminta, misalnya payment.qris. Metode itu tetap harus tersedia untuk proyek dan environment tersebut.
project_id	Proyek tempat pembayaran dicatat. Wajib jika key berlaku untuk seluruh merchant; project key sudah terikat ke proyeknya.
merchant_reference	ID order dari sistemmu agar pembayaran bisa dicari dan dicocokkan kembali ke order.
description	Ringkasan untuk mengenali pembayaran di dashboard.
customer	Data pembayar opsional. Beberapa metode pembayaran mewajibkan nomor telepon.
metadata	Pasangan teks milikmu yang ikut muncul pada objek pembayaran dan event webhook; jangan masukkan rahasia atau data sensitif.
expires_in	Lama waktu pembayaran menunggu sebelum kedaluwarsa, dalam detik. Nilainya 300 detik sampai 7 hari; default-nya bergantung pada metode.

Respons juga memuat fee, charged_amount (jumlah yang dibayar pembeli, termasuk biaya bila dibebankan kepadanya), dan net_amount (bagian merchant setelah biaya Baiyar). net_amount masuk ke saldo tertunda setelah pembayaran berhasil, lalu pindah ke saldo tersedia setelah settlement provider.

3. Bayar di sandbox

Gunakan test key untuk menentukan hasil pembayaran sandbox. Cara ini tidak menagih pembayar:

curl "$BAIYAR_API/v1/sandbox/payments/pay_01k7…/simulate" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

outcome bisa paid, failed, atau expired. Endpoint ini hanya ada untuk test key.

4. Baca hasilnya

curl "$BAIYAR_API/v1/payments/pay_01k7…" -H "Authorization: Bearer $BAIYAR_KEY"

data.status sekarang paid. Di kodemu sendiri, jangan polling: daftarkan endpoint webhook dan tangani payment.succeeded.

Hal yang sama di Node.js

const api = "https://api.baiyar.com";
const headers = { Authorization: `Bearer ${process.env.BAIYAR_KEY}`, "Content-Type": "application/json" };

const created = await fetch(`${api}/v1/payments`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "order-1001-attempt-1" },
  body: JSON.stringify({ amount: 1_000_000, currency: "IDR", payment_method: "payment.qris" }),
});
if (!created.ok) throw new Error((await created.json()).error.code);
const { data: payment } = await created.json();
console.log(payment.id, payment.status, payment.instruction);

await fetch(`${api}/v1/sandbox/payments/${payment.id}/simulate`, {
  method: "POST",
  headers,
  body: JSON.stringify({ outcome: "paid" }),
});

Setiap request di atas juga bisa dijalankan dari referensi API: setiap operasi punya tombol Coba yang membuka klien request di browser, ke sandbox.

Go live

Live butuh proyek yang sudah disetujui untuk live dan akun yang terverifikasi. Buat live key, dan kodenya tetap sama: hanya key yang berganti.