API Reference

Base URL

https://bukasir.biz.id

Autentikasi

Sebagian besar endpoint memerlukan header berikut:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Format Response

Semua response menggunakan format JSON flat (tanpa wrapper success atau data). Contoh response sukses:

{
  "order_id": "ORDER-001",
  "status": "pending",
  "amount": 50000
}

Response error selalu menggunakan format:

{
  "status": "error",
  "message": "Deskripsi error"
}

POST /api/charge

Buat transaksi pembayaran baru. Endpoint ini mengembalikan URL pembayaran hosted yang harus dibuka oleh customer untuk menyelesaikan pembayaran.

Mode Pembayaran

Ada dua cara menggunakan endpoint ini:

Mode	Cara	Perilaku
Single	Kirim payment_method	Langsung charge ke Midtrans. Customer dibuka ke halaman QR/VA/deeplink.
Multi	Tidak kirim payment_method	Customer memilih sendiri metode di halaman pembayaran. Fee dihitung saat customer memilih.

Metode Pembayaran Aktif

payment_method	Keterangan	Field tambahan
qris	QRIS — scan dari semua e-wallet & m-banking	—
gopay	GoPay — deeplink & QR	—
bank_transfer	Virtual Account — BNI, BRI, Mandiri, Permata, CIMB	bank wajib

Request Body

Field	Type	Required	Description
order_id	string	Ya	ID unik pesanan dari merchant (maks 50 karakter, a-z 0-9 - _ . /)
amount	integer	Ya	Jumlah pembayaran dalam Rupiah (minimum 100, tanpa desimal)
payment_method	string	Tidak wajib	Jika dikosongkan → mode multi (customer pilih sendiri). Pilihan: qris, gopay, bank_transfer
bank	string	Hanya untuk bank_transfer	Nama bank: bni, bri, mandiri, permata, cimb

Contoh Request — Single Mode (cURL)

curl -X POST https://bukasir.biz.id/api/charge \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORDER-001",
    "amount": 50000,
    "payment_method": "qris"
  }'

Contoh Request — Multi Mode (cURL)

curl -X POST https://bukasir.biz.id/api/charge \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORDER-002",
    "amount": 50000
  }'

Response — Single Mode (200 OK)

{
  "order_id": "ORDER-001",
  "status": "pending",
  "payment_method": "qris",
  "amount": 50000,
  "fee": 350,
  "payment_url": "https://bukasir.biz.id/pay/slug/ORDER-001",
  "expired_at": "2026-07-23 15:30:00"
}

Response — Multi Mode (200 OK)

{
  "order_id": "ORDER-002",
  "status": "awaiting_method",
  "payment_method": "multi",
  "amount": 50000,
  "fee": 0,
  "payment_url": "https://bukasir.biz.id/pay/slug/ORDER-002",
  "expired_at": "2026-07-24 15:30:00"
}

Error Response (400 Bad Request)

{
  "status": "error",
  "message": "payment_method tidak valid. Pilihan: qris, bank_transfer, gopay, shopeepay, dana, ovo"
}

GET /api/status/{order_id}

Cek status terkini dari sebuah transaksi. Order ID dikirim sebagai bagian dari URL path.

URL Parameter

Field	Type	Required	Description
order_id	string	Ya	Order ID transaksi (bagian dari URL path)

Contoh Request

curl "https://bukasir.biz.id/api/status/ORDER-001" \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response (200 OK)

{
  "order_id": "ORDER-001",
  "status": "pending",
  "amount": 50000.0,
  "fee": 350.0,
  "payment_method": "qris",
  "bank": null,
  "payment_url": "https://bukasir.biz.id/pay/slug/ORDER-001",
  "expired_at": "2026-07-23 15:30:00",
  "paid_at": null,
  "created_at": "2026-07-23 14:00:00",
  "updated_at": "2026-07-23 14:00:00"
}

POST /api/cancel/{order_id}

Batalkan transaksi yang masih berstatus pending atau awaiting_method. Transaksi awaiting_method belum diproses ke Midtrans sehingga langsung dibatalkan secara lokal. Transaksi dengan status completed, expired, cancelled, atau failed tidak dapat dibatalkan.

URL Parameter

Field	Type	Required	Description
order_id	string	Ya	Order ID transaksi yang ingin dibatalkan (bagian dari URL path)

Contoh Request

curl -X POST "https://bukasir.biz.id/api/cancel/ORDER-001" \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response (200 OK)

{
  "order_id": "ORDER-001",
  "status": "cancelled",
  "amount": 50000.0,
  "payment_method": "qris",
  "cancelled_at": "2026-07-23 14:30:00"
}

Error Response (409 Conflict)

{
  "status": "error",
  "message": "Transaksi tidak bisa dibatalkan. Status saat ini: completed."
}

GET /api/fee-estimate

Dapatkan estimasi biaya (fee) sebelum melakukan transaksi. Berguna untuk menampilkan total yang harus dibayar ke customer.

Query Parameters

Field	Type	Required	Description
amount	integer	Ya	Jumlah dalam Rupiah
payment_method	string	Ya	Metode pembayaran

Contoh Request

curl "https://bukasir.biz.id/api/fee-estimate?amount=50000&payment_method=qris"

Response (200 OK)

{
  "amount": 50000,
  "payment_method": "qris",
  "fee": 350,
  "total": 50350,
  "fee_type": "percentage",
  "fee_value": "0.70",
  "formatted": "0.7% (Rp 350)"
}

Strategi Error Handling

Semua response menggunakan HTTP status code yang konsisten:

Status Code	Deskripsi
200	Request berhasil
400	Parameter tidak valid atau data tidak lengkap
401	API key tidak valid atau tidak disertakan
403	Akses ditolak (akun belum terverifikasi)
404	Resource tidak ditemukan
405	Method tidak diizinkan (misalnya GET ke endpoint POST)
409	Conflict (misalnya membatalkan transaksi yang sudah completed)
422	Unprocessable Entity (misalnya order_id tidak ada di URL path)
429	Rate limit terlampaui
502	Bad Gateway (gagal terhubung ke payment gateway Midtrans)