Quickstart
Integrasi BITS Pay dalam 3 langkah: buat charge, tampilkan QRIS, konfirmasi pembayaran.
0. Dapatkan API key
Istilah: aplikasi (di dashboard) = app di API; transaksi =
payment.
Daftar di dashboard (panduan lengkap: Panduan Dashboard),
buat aplikasi di workspace kamu. API key (sk_...) hanya
ditampilkan sekali saat create/rotate — simpan di tempat aman. Semua
request /v1/* pakai header:
Authorization: Bearer sk_xxxxxxxxxxxxxxxx
Base URL: https://api.pay.bits.co.id. Response sukses selalu
{ "success": true, "data": ... }, error
{ "success": false, "error": { "code", "message" } }.
400 qris_not_configured — lihat
Panduan Dashboard §3.
1. Buat charge (QRIS dinamis)
1POST /v1/charges
Kirim order_id (unik per aplikasi — kirim ulang order_id yang
sama ditolak 409, jadi aman retry tanpa double charge) dan
amount (minimal Rp 100). API mengembalikan QRIS dinamis dengan
kode unik: amount_due = amount + fee + unique_code (fee
= biaya admin opsional, dikirim di request — default 0).
const res = await fetch('https://api.pay.bits.co.id/v1/charges', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
order_id: 'ORD-001',
amount: 150000,
description: 'Pembayaran invoice #001',
}),
});
const { success, data, error } = await res.json();
if (!success) throw new Error(`${error.code}: ${error.message}`);
const id = data.id; // payment ID — dipakai di langkah 2 & 3
console.log(data.amount_due); // 150001
console.log(data.qr_image); // data:image/svg+xml;base64,...
console.log(data.expired_at); // batas bayar, ISO-8601 UTC: "2026-09-02T12:45:00Z"
curl -X POST https://api.pay.bits.co.id/v1/charges \
-H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"order_id":"ORD-001","amount":150000,"description":"Pembayaran invoice #001"}'
# Response: { "success": true, "data": { "id": "...", "amount_due": 150001,
# "qr_image": "data:image/svg+xml;base64,...", "expired_at": "2026-09-02T12:45:00Z" } }
# Simpan data.id — dipakai di langkah 2 & 3.
<?php
$ch = curl_init('https://api.pay.bits.co.id/v1/charges');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sk_xxxxxxxxxxxxxxxx',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'order_id' => 'ORD-001',
'amount' => 150000,
'description' => 'Pembayaran invoice #001',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
if (!$body['success']) {
throw new RuntimeException($body['error']['code'] . ': ' . $body['error']['message']);
}
$id = $body['data']['id']; // payment ID — dipakai di langkah 2 & 3
echo $body['data']['amount_due']; // 150001
echo $body['data']['qr_image']; // data:image/svg+xml;base64,...
echo $body['data']['expired_at']; // batas bayar, ISO-8601 UTC
import requests
res = requests.post(
'https://api.pay.bits.co.id/v1/charges',
headers={'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxx'},
json={
'order_id': 'ORD-001',
'amount': 150000,
'description': 'Pembayaran invoice #001',
},
)
body = res.json()
if not body['success']:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data = body['data']
payment_id = data['id'] # payment ID — dipakai di langkah 2 & 3
print(data['amount_due']) # 150001
print(data['qr_image']) # data:image/svg+xml;base64,...
print(data['expired_at']) # batas bayar, ISO-8601 UTC
Tampilkan data.qr_image sebagai <img src> ke pelanggan.
Pelanggan bayar nominal persis amount_due.
2. Cek status pembayaran
2GET /v1/payments/:id
Poll status transaksi, atau terima update real-time via
webhook. Untuk rekonsiliasi massal pakai
GET /v1/payments (filter order_id/status,
paginated).
const res = await fetch(`https://api.pay.bits.co.id/v1/payments/${id}`, {
headers: { Authorization: 'Bearer sk_xxxxxxxxxxxxxxxx' },
});
const { data } = await res.json();
// data.status: 'pending' | 'success' | 'failed' | 'expired' | 'pending_review'
curl https://api.pay.bits.co.id/v1/payments/PAYMENT_ID \
-H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx"
# data.status: 'pending' | 'success' | 'failed' | 'expired' | 'pending_review'
<?php
$ch = curl_init('https://api.pay.bits.co.id/v1/payments/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_xxxxxxxxxxxxxxxx'],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// $body['data']['status']: 'pending' | 'success' | 'failed' | 'expired' | 'pending_review'
res = requests.get(
f'https://api.pay.bits.co.id/v1/payments/{payment_id}',
headers={'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxx'},
)
status = res.json()['data']['status']
# 'pending' | 'success' | 'failed' | 'expired' | 'pending_review'
3. Konfirmasi pembayaran
3POST /v1/payments/:id/confirm
Kirim multipart/form-data berisi amount (harus sama persis
dengan amount_due) dan opsional proof_image (JPG/PNG, maks 5MB)
untuk auto-confirm via OCR.
const form = new FormData();
form.append('amount', '150001'); // = amount_due
form.append('proof_image', fileInput.files[0]); // opsional
const res = await fetch(`https://api.pay.bits.co.id/v1/payments/${id}/confirm`, {
method: 'POST',
headers: { Authorization: 'Bearer sk_xxxxxxxxxxxxxxxx' },
body: form,
});
const { data } = await res.json();
// Request valid SELALU HTTP 200 — cek data.status:
// 'success' → auto_confirm (lunas)
// 'pending_review' → perlu review manual admin (OCR meragukan / nominal besar)
// 'failed' → nominal tidak cocok / bukti tidak disertakan
curl -X POST https://api.pay.bits.co.id/v1/payments/PAYMENT_ID/confirm \
-H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx" \
-F "amount=150001" \
-F "proof_image=@/path/ke/bukti.jpg"
# Request valid SELALU HTTP 200 — cek data.status:
# 'success' → auto_confirm (lunas) | 'pending_review' → direview admin
# 'failed' → nominal tidak cocok / bukti tidak disertakan
<?php
$ch = curl_init('https://api.pay.bits.co.id/v1/payments/' . $id . '/confirm');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_xxxxxxxxxxxxxxxx'],
CURLOPT_POSTFIELDS => [
'amount' => '150001', // = amount_due
'proof_image' => new CURLFile('/path/ke/bukti.jpg'), // opsional
],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Request valid SELALU HTTP 200 — cek $body['data']['status']:
// 'success' → auto_confirm (lunas) | 'pending_review' → direview admin
// 'failed' → nominal tidak cocok / bukti tidak disertakan
with open('/path/ke/bukti.jpg', 'rb') as proof:
res = requests.post(
f'https://api.pay.bits.co.id/v1/payments/{payment_id}/confirm',
headers={'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxx'},
data={'amount': '150001'}, # = amount_due
files={'proof_image': proof}, # opsional
)
status = res.json()['data']['status']
# Request valid SELALU HTTP 200 — cek status:
# 'success' → auto_confirm (lunas) | 'pending_review' → direview admin
# 'failed' → nominal tidak cocok / bukti tidak disertakan
Error handling
Daftar lengkap error untuk endpoint publik (/v1/*). Referensi kanonik
per-endpoint (termasuk error.details): lihat
Referensi API.
| Code | HTTP | Arti |
|---|---|---|
validation_error |
400 | Body tidak valid (cek error.details) |
expired |
400 | Transaksi kedaluwarsa |
qris_not_configured |
400 | QRIS statis belum dipasang di pengaturan aplikasi |
invalid_status |
400 | Aksi tidak cocok dengan status transaksi (mis. konfirmasi transaksi yang sudah lunas / sedang direview) |
invalid_proof |
400 | File bukti bukan JPG/PNG yang valid |
proof_too_large |
400 | Bukti bayar melebihi 5MB |
too_many_attempts |
400 | Percobaan konfirmasi habis — transaksi menunggu review admin |
tier_limit |
400 | Kuota tier tercapai (transaksi harian / bulanan) |
no_unique_code |
400/409 | Kode unik habis / gagal dialokasikan — coba lagi |
unauthorized |
401 | API key salah / aplikasi nonaktif |
not_found |
404 | Transaksi tidak ditemukan |
duplicate_order |
409 | order_id sudah dipakai transaksi aktif |
duplicate_hash |
409 | Bukti bayar sudah dipakai |
payload_too_large |
413 | Body request melebihi batas ukuran |
unsupported_media_type |
415 | Content-Type tidak didukung |
rate_limited |
429 | Rate limit terlampaui — tunggu sesuai header Retry-After |
internal_error |
500 | Kesalahan server — coba lagi, hubungi support bila berulang |
X-RateLimit-Limit, X-RateLimit-Remaining, dan
X-RateLimit-Reset.