Bisadagang BisnisBisadagang BisnisDocs
HargaMasukDaftar gratis
Mulai
  • Pengenalan
  • Quick start
Dasar
  • Autentikasi & signature
  • Format respons & kode error
Referensi API
  • GETCek saldo
  • GETDaftar harga & produk
  • Transaksi
  • Komplain
  • Webhook
Panduan
  • Sandbox
  • Panduan vibe coder
Butuh bantuan?

Tim teknis kami siap membantu integrasi lewat WhatsApp.

Chat tim teknis
Syarat dan ketentuanKebijakan privasi
Mulai
  • Pengenalan
  • Quick start
Dasar
  • Autentikasi & signature
  • Format respons & kode error
Referensi API
  • GETCek saldo
  • GETDaftar harga & produk
  • Transaksi
  • Komplain
  • Webhook
Panduan
  • Sandbox
  • Panduan vibe coder
Referensi API

Transaksi

Beli produk prabayar, cek statusnya, dan bayar tagihan pascabayar. Saldo dipotong saat transaksi dibuat dan dikembalikan otomatis jika transaksi gagal.

Ringkasan#

Alurnya sama untuk semua produk: Bisadagang memotong saldo Anda, mengirim pesanan ke penyedia produk, lalu Anda membaca hasilnya lewat cek status. Respons pembuatan transaksi hampir selalu berstatus pending; status akhirnya menyusul.

Endpoint
Per menit
Kegunaan
POST /h2h/v1/transactions300
300
Beli produk prabayar.
GET /h2h/v1/transactions/{ref_id}120
120
Cek status transaksi prabayar dan pembayaran pascabayar.
POST /h2h/v1/bills/inquiry60
60
Cek tagihan pascabayar, gratis.
POST /h2h/v1/bills/payment300
300
Bayar tagihan dari hasil inquiry.
POST /h2h/v1/account-check60
60
Cek nama pemilik rekening atau e-wallet, gratis.

Kolom Per menit adalah batas default per Mitra Bisnis dan per environment. Nilai yang berlaku untuk akun Anda ada di header respons; lihat Batas request.

  • Request POST membawa body JSON yang ikut diberi signature. Lihat Request dengan body.
  • Semua nominal dalam rupiah, bilangan bulat.
  • Pembuatan transaksi dan pembayaran membalas 200 OK, bukan 201 atau 202. Baca data.status untuk tahu hasilnya.
Sandbox tersedia. Key sandbox memakai endpoint dan format yang sama, dengan saldo sandbox sendiri. Hasilnya ditentukan oleh 4 digit terakhir nomor tujuan; lihat Sandbox.

Transaksi prabayar#

POST/h2h/v1/transactions

Membeli satu produk prabayar bernominal tetap, misalnya pulsa atau token. Ambil kode produk dari Daftar harga & produk. Produk pascabayar tidak bisa dibeli lewat endpoint ini dan dijawab PRODUCT_NOT_SUPPORTED. Produk dengan nominal bebas (is_open_amount bernilai true) memakai dua field tambahan; lihat Transfer bank / e-wallet nominal bebas.

Header

Header
Isi
Content-Type
application/json
Idempotency-Key
Wajib. Teks unik per transaksi, 8–100 karakter (A-Z a-z 0-9 . _ : -). Tidak ikut diberi signature. Lihat ref_id dan Idempotency-Key.
X-Bisadagang-…
Empat header autentikasi seperti biasa. Lihat Autentikasi & signature.

Body

Field
Tipe
Keterangan
product_codestring
string
Wajib. Kode produk Bisadagang: huruf besar dan angka, maksimal 20 karakter. Huruf kecil diubah menjadi huruf besar.
customer_nostring
string
Wajib. Nomor tujuan (nomor HP, nomor pelanggan, dan sebagainya): 4–20 angka. Kirim sebagai string supaya angka 0 di depan tidak hilang.
ref_idstring
string
Wajib. Referensi unik dari sistem Anda, 1–50 karakter (A-Z a-z 0-9 . _ -). Lihat ref_id dan Idempotency-Key.
max_priceinteger
integer
Opsional. Batas harga dalam rupiah (1 sampai 100.000.000). Jika harga yang akan dipotong lebih tinggi, transaksi ditolak dengan PRICE_CHANGED dan saldo tidak terpotong.

Harga tidak dikirim di request. Bisadagang menghitungnya saat transaksi dibuat dari harga terbaru, jadi bisa berbeda dari daftar harga yang Anda simpan. Pakai max_price untuk membatasinya.

Request

# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/transactions"
BODY='{"product_code":"TSEL10","customer_no":"081234567890","ref_id":"INV-20261118-0001"}'
IDEMPOTENCY_KEY="trx-INV-20261118-0001"
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')

curl -X POST "https://api.bisadagang.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
  -H "X-Bisadagang-Timestamp: $TS" \
  -H "X-Bisadagang-Nonce: $NONCE" \
  -H "X-Bisadagang-Signature: $SIGNATURE" \
  --data "$BODY"

Respons

Saldo sudah terpotong saat respons ini diterima. Pesanan dikirim ke penyedia satu kali sesudahnya, jadi status awalnya hampir selalu pending.

200 OK
{
  "success": true,
  "data": {
    "ref_id": "INV-20261118-0001",
    "transaction_id": "PL1794993330AB42",
    "product_code": "TSEL10",
    "product_type": "prepaid",
    "customer_no": "081234567890",
    "price": 10357,
    "status": "pending",
    "sn": null,
    "message": null,
    "created_at": "2026-11-18T09:15:30.000Z"
  },
  "request_id": "a1b2c3d4e5"
}
422 · PRICE_CHANGED
{
  "success": false,
  "error": {
    "code": "PRICE_CHANGED",
    "message": "Harga produk melebihi max_price.",
    "details": { "price": 10357, "max_price": 10300 }
  },
  "request_id": "a1b2c3d4e5"
}

Field transaksi

Field yang sama dipakai oleh respons pembuatan, cek status, dan pembayaran pascabayar.

Field
Tipe
Keterangan
ref_idstring
string
Referensi dari sistem Anda.
transaction_idstring
string
ID transaksi di Bisadagang. Sertakan saat menghubungi tim Bisadagang.
product_codestring
string
Kode produk.
product_typestring
string
prepaid atau postpaid.
customer_nostring
string
Nomor tujuan.
pricenumber
number
Rupiah yang dipotong dari saldo. Untuk pascabayar, sudah dikurangi komisi.
statusstring
string
pending, success, atau failed. Lihat Status transaksi.
snstring | null
string | null
Serial number atau token dari penyedia. Hanya terisi jika status adalah success.
messagestring | null
string | null
Keterangan untuk manusia. Teksnya bisa berubah, jangan dipakai untuk logika.
created_atstring
string
Waktu transaksi dibuat (ISO 8601, UTC).
inquiry_idstring
string
Hanya pascabayar: inquiry yang dibayar.
commissionnumber
number
Hanya pascabayar: komisi Anda, sudah dikurangkan dari price.
amountnumber
number
Hanya nominal bebas: nominal yang dikirim ke tujuan.
account_namestring
string
Hanya nominal bebas: nama pemilik tujuan hasil cek nama.

ref_id dan Idempotency-Key#

Dua mekanisme ini melindungi Anda dari pemotongan saldo ganda saat request diulang.

  • ref_id: satu ref_id hanya untuk satu transaksi, prabayar maupun pembayaran pascabayar, unik per Mitra Bisnis dan per environment. Jika ref_id sudah pernah dipakai, Bisadagang mengembalikan transaksi yang sudah ada dengan status terkininya dan tidak memotong saldo lagi.
  • Idempotency-Key: wajib di pembuatan transaksi dan pembayaran. Request dengan key dan body yang sama mengembalikan respons pertama apa adanya, termasuk status pending saat itu; untuk status terbaru, pakai cek status. Key yang sama dengan body berbeda dijawab 422 IDEMPOTENCY_KEY_REUSED. Jika request pertama masih berjalan, jawabannya 409 REQUEST_IN_PROGRESS: tunggu beberapa detik lalu kirim ulang. Key hanya disimpan untuk request yang berhasil, jadi setelah error key yang sama boleh dipakai lagi.
Request gagal atau timeout, tidak tahu transaksinya terbuat atau tidak? Kirim ulang dengan ref_id, Idempotency-Key, dan body yang persis sama, tetapi dengan timestamp, nonce, dan signature baru. Hasilnya aman: transaksi yang sudah terbuat dikembalikan, yang belum terbuat dibuat sekali. Anda juga bisa cek status dulu: 404 NOT_FOUND berarti belum terbuat. Jangan ganti ref_id untuk mengulang, karena itu bisa membeli dua kali.

Hati-hati dengan ref_id yang terpakai ulang secara tidak sengaja. Request kedua dengan ref_id yang sama dijawab dengan transaksi yang lama, walaupun product_code, customer_no, atau max_price-nya berbeda, dan isi request kedua diabaikan. Selalu buat ref_id baru untuk transaksi baru, dan cocokkan product_code serta customer_no di respons dengan yang Anda kirim.

Status transaksi#

Status
Arti
pending
Transaksi diterima dan saldo sudah terpotong, tetapi hasil akhirnya belum ada. Pending bukan gagal: jangan kirim ulang dengan ref_id baru, dan saldo belum dikembalikan.
success
Transaksi berhasil. sn terisi jika penyedia memberikannya.
failed
Transaksi gagal. Saldo sebesar price dikembalikan otomatis, satu kali. Tidak ada tindakan yang perlu Anda lakukan.

Bagaimana pending diselesaikan

Setelah saldo terpotong, Bisadagang mengirim pesanan ke penyedia satu kali. Hasilnya salah satu dari tiga:

  • Penyedia menjawab berhasil: status menjadi success.
  • Penyedia menjawab gagal dengan jelas: status menjadi failed dan saldo dikembalikan otomatis.
  • Tidak ada jawaban, atau jawabannya belum final: status tetap pending. Bisadagang tidak menandainya gagal hanya karena jawaban terlambat, tidak mengirim ulang sebagai pesanan baru, dan tidak mengembalikan saldo selama hasil akhirnya belum ada. Bisadagang terus memeriksa ke penyedia, dan transaksi yang tidak kunjung selesai diselesaikan secara manual oleh tim Bisadagang. Status berubah begitu hasil akhirnya diterima.

Jalur utama untuk status akhir adalah webhook. Sebagai cadangan, cek status secara berkala, misalnya setiap 30 detik, dan berhenti begitu status bukan pending.

Pesanan yang tidak sempat dikirim dalam 30 menit

Ada satu kasus yang pasti berakhir failed: pesanan yang saldonya sudah terpotong tetapi belum juga dikirim ke penyedia setelah 30 menit, misalnya karena gangguan panjang di sisi Bisadagang. Pesanan seperti ini tidak pernah dikirim terlambat, karena pasti belum sampai ke penyedia. Statusnya menjadi failed, saldo dikembalikan otomatis, dan message berisi Transaksi tidak terkirim ke supplier. Dana dikembalikan.

200 OK · status failed
{
  "success": true,
  "data": {
    "ref_id": "INV-20261118-0001",
    "transaction_id": "PL1794993330AB42",
    "product_code": "TSEL10",
    "product_type": "prepaid",
    "customer_no": "081234567890",
    "price": 10357,
    "status": "failed",
    "sn": null,
    "message": "Transaksi tidak terkirim ke supplier. Dana dikembalikan.",
    "created_at": "2026-11-18T09:15:30.000Z"
  },
  "request_id": "a1b2c3d4e5"
}

Ini berbeda dari pending. Pending berarti pesanan sudah dikirim dan hasilnya belum ada, sehingga saldo ditahan sampai hasil akhir.

Cek status#

GET/h2h/v1/transactions/{ref_id}

Ganti {ref_id} dengan ref_id yang Anda kirim saat membuat transaksi. Berlaku untuk transaksi prabayar dan pembayaran pascabayar. Endpoint ini tetap bisa dipakai saat layanan sedang pemeliharaan, dan termasuk kelompok batas baca (default 120 request per menit).

# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/transactions/INV-20261118-0001"
BODY=""
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "GET" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')

curl "https://api.bisadagang.com$REQ_PATH" \
  -H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
  -H "X-Bisadagang-Timestamp: $TS" \
  -H "X-Bisadagang-Nonce: $NONCE" \
  -H "X-Bisadagang-Signature: $SIGNATURE"
200 OK · status success
{
  "success": true,
  "data": {
    "ref_id": "INV-20261118-0001",
    "transaction_id": "PL1794993330AB42",
    "product_code": "TSEL10",
    "product_type": "prepaid",
    "customer_no": "081234567890",
    "price": 10357,
    "status": "success",
    "sn": "1234567890123456",
    "message": "Transaksi Sukses",
    "created_at": "2026-11-18T09:15:30.000Z"
  },
  "request_id": "a1b2c3d4e5"
}

Isi data sama dengan respons pembuatan transaksi (lihat Field transaksi). Jika ref_id tidak dikenal, jawabannya 404 NOT_FOUND.

Tagihan pascabayar#

Tagihan dibayar dalam dua langkah: inquiry untuk melihat tagihan (gratis), lalu pembayaran. Hanya produk dengan product_type postpaid yang bisa dipakai; produk lain dijawab PRODUCT_NOT_SUPPORTED.

1. Inquiry

POST/h2h/v1/bills/inquiry
Field
Tipe
Keterangan
product_codestring
string
Wajib. Kode produk pascabayar.
customer_nostring
string
Wajib. Nomor pelanggan atau ID tagihan, 4–20 angka, dikirim sebagai string.
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/bills/inquiry"
BODY='{"product_code":"PLNPASCA","customer_no":"512345678901"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')

curl -X POST "https://api.bisadagang.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
  -H "X-Bisadagang-Timestamp: $TS" \
  -H "X-Bisadagang-Nonce: $NONCE" \
  -H "X-Bisadagang-Signature: $SIGNATURE" \
  --data "$BODY"
200 OK
{
  "success": true,
  "data": {
    "inquiry_id": "3f1c9a52-7b1e-4d0a-9c53-2d8e6a4b7f10",
    "product_code": "PLNPASCA",
    "customer_no": "512345678901",
    "customer_name": "BUDI CONTOH",
    "bill_total": 102750,
    "admin_fee": 2750,
    "commission": 1200,
    "price": 101550,
    "details": { "lembar_tagihan": 1 },
    "expires_at": "2026-11-18T09:45:30.000Z"
  },
  "request_id": "a1b2c3d4e5"
}
Field
Tipe
Keterangan
inquiry_idstring
string
ID inquiry. Dipakai untuk membayar.
product_codestring
string
Kode produk.
customer_nostring
string
Nomor pelanggan.
customer_namestring | null
string | null
Nama pelanggan dari penyedia tagihan. Tampilkan ke pelanggan Anda dan minta konfirmasi sebelum membayar. null jika penyedia tidak mengirim nama.
bill_totalnumber
number
Tagihan ditambah biaya admin: jumlah yang harus dibayar pelanggan.
admin_feenumber
number
Biaya admin, sudah termasuk di bill_total.
commissionnumber
number
Komisi Anda untuk tagihan ini, ditampilkan terpisah. Lihat Komisi pascabayar.
pricenumber
number
Rupiah yang akan dipotong dari saldo: bill_total dikurangi commission.
detailsobject | null
object | null
Rincian tagihan dari penyedia, mis. periode. Isinya berbeda per produk, jangan dijadikan dasar logika. Contoh di atas hanya ilustrasi.
expires_atstring
string
Batas waktu untuk membayar inquiry ini (ISO 8601, UTC).
  • Gratis. Inquiry tidak memotong saldo dan tidak membuat transaksi.
  • Batas. Inquiry punya batas sendiri, default 60 per menit. Setiap request dihitung, termasuk yang dijawab dari hasil sebelumnya.
  • Hasil dipakai ulang 5 menit. Inquiry untuk produk dan nomor yang sama dalam 5 menit mengembalikan inquiry sebelumnya (inquiry_id dan expires_at sama) tanpa bertanya ke penyedia. Setelah itu terbit inquiry baru dengan inquiry_id baru. Inquiry yang sudah dibayar tidak dipakai ulang.
  • Berlaku 30 menit. Setelah expires_at, pembayaran dijawab INQUIRY_EXPIRED: lakukan inquiry ulang.
  • Tidak ada tagihan. Jika penyedia menyatakan tidak ada tagihan yang bisa dibayar (misalnya sudah lunas atau nomor salah), jawabannya 422 INQUIRY_FAILED dengan keterangan dari penyedia. Jika penyedia belum menjawab, jawabannya 503 SUPPLIER_UNAVAILABLE; tidak ada yang terpotong dan aman diulang.

2. Pembayaran

POST/h2h/v1/bills/payment

Header sama dengan transaksi prabayar, termasuk Idempotency-Key yang wajib.

Field
Tipe
Keterangan
inquiry_idstring
string
Wajib. inquiry_id dari inquiry yang masih berlaku.
ref_idstring
string
Wajib. Aturannya sama dengan transaksi prabayar dan berbagi ruang yang sama: satu ref_id hanya untuk satu transaksi. Lihat ref_id dan Idempotency-Key.
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/bills/payment"
BODY='{"inquiry_id":"3f1c9a52-7b1e-4d0a-9c53-2d8e6a4b7f10","ref_id":"INV-20261118-0002"}'
IDEMPOTENCY_KEY="pay-INV-20261118-0002"
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')

curl -X POST "https://api.bisadagang.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
  -H "X-Bisadagang-Timestamp: $TS" \
  -H "X-Bisadagang-Nonce: $NONCE" \
  -H "X-Bisadagang-Signature: $SIGNATURE" \
  --data "$BODY"
200 OK
{
  "success": true,
  "data": {
    "ref_id": "INV-20261118-0002",
    "transaction_id": "PB1794993330CD17",
    "product_code": "PLNPASCA",
    "product_type": "postpaid",
    "customer_no": "512345678901",
    "price": 101550,
    "status": "pending",
    "sn": null,
    "message": null,
    "created_at": "2026-11-18T09:20:10.000Z",
    "inquiry_id": "3f1c9a52-7b1e-4d0a-9c53-2d8e6a4b7f10",
    "commission": 1200
  },
  "request_id": "a1b2c3d4e5"
}
  • Jumlah yang dipotong. Saldo dipotong sebesar price pada inquiry, tidak dihitung ulang. Jika saldo kurang, jawabannya INSUFFICIENT_BALANCE dan tidak ada yang terpotong.
  • ID inquiry menjadi ID transaksi. Penyedia mewajibkan pembayaran memakai referensi yang sama dengan inquiry. Karena itu ID transaksi pembayaran sudah dipesan saat inquiry dibuat, lalu muncul sebagai transaction_id di respons pembayaran. Satu inquiry tidak pernah menghasilkan lebih dari satu transaksi, dan inquiry baru memesan ID yang baru.
  • Satu inquiry, satu pembayaran. Membayar ulang dengan ref_id yang sama mengembalikan transaksi yang ada. Membayar inquiry yang sama dengan ref_id lain dijawab 422 INQUIRY_ALREADY_PAID, dan details.ref_id berisi ref_id yang sudah memakainya.
  • Status akhir. Respons awalnya pending. Cek dengan cek status memakai ref_id pembayaran. Penjelasan status transaksi, pending, dan pengembalian saldo berlaku sama.
  • Ditolak saat membayar. Produk yang sedang gangguan atau dinonaktifkan sejak inquiry tetap ditolak saat membayar. Inquiry milik akun lain atau yang tidak dikenal dijawab 404 NOT_FOUND.
422 · INQUIRY_ALREADY_PAID
{
  "success": false,
  "error": {
    "code": "INQUIRY_ALREADY_PAID",
    "message": "Tagihan dari inquiry ini sudah dibayar.",
    "details": { "ref_id": "INV-20261118-0002" }
  },
  "request_id": "a1b2c3d4e5"
}

Komisi pascabayar#

Pascabayar tidak memakai margin tetap seperti prabayar. Penyedia memberi komisi untuk setiap tagihan yang dibayar, dan sebagian komisi itu menjadi milik Anda.

  • Bagian Anda 70% dari komisi tagihan itu, dibulatkan ke bawah ke rupiah penuh. Persentase 70% adalah standar; bisa berbeda per Mitra Bisnis atau kategori jika ada kesepakatan khusus.
  • Komisi tidak dibayar terpisah. Langsung dikurangkan dari tagihan: price sama dengan bill_total dikurangi commission. Saldo yang dipotong tidak pernah lebih besar dari bill_total.
  • Komisi tidak pernah melebihi yang diberikan penyedia. Jika untuk tagihan tertentu penyedia memberi komisi lebih kecil dari biasanya, komisi Anda ikut lebih kecil. Karena itu commission di inquiry bisa lebih rendah dari commission di daftar produk. Pakai angka dari inquiry, bukan dari daftar produk.
  • Jika pembayaran gagal, seluruh price dikembalikan dan tidak ada komisi.

Contoh hitungan (angka ilustrasi):

Komponen
Rupiah
Tagihan
100.000
Biaya admin
2.750
bill_total (tagihan + biaya admin)
102.750
Komisi dari penyedia untuk tagihan ini
1.715
commission (70% = 1.200,5, dibulatkan ke bawah)
1.200
price (dipotong dari saldo)
101.550

Jika pelanggan Anda membayar sebesar bill_total, selisih Rp1.200 itulah komisi Anda.

Cek nama rekening / e-wallet#

POST/h2h/v1/account-check

Melihat nama pemilik rekening bank atau e-wallet sebelum Anda mengirim uang. Gratis dan tidak memotong saldo. Hanya untuk produk transfer bank dan e-wallet; produk lain dijawab PRODUCT_NOT_SUPPORTED. Hasil cek nama diperlukan untuk transaksi nominal bebas.

Field
Tipe
Keterangan
product_codestring
string
Wajib. Kode produk transfer bank atau e-wallet, mis. TFBCA.
customer_nostring
string
Wajib. Nomor rekening atau nomor HP e-wallet, 4–20 angka, dikirim sebagai string.
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/account-check"
BODY='{"product_code":"TFBCA","customer_no":"1234567890"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')

curl -X POST "https://api.bisadagang.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
  -H "X-Bisadagang-Timestamp: $TS" \
  -H "X-Bisadagang-Nonce: $NONCE" \
  -H "X-Bisadagang-Signature: $SIGNATURE" \
  --data "$BODY"
200 OK
{
  "success": true,
  "data": {
    "check_id": "8b7d4c1e-2a36-4f5b-9e08-6c1d3f2a9b47",
    "product_code": "TFBCA",
    "customer_no": "1234567890",
    "account_name": "BUDI CONTOH",
    "expires_at": "2026-11-18T10:05:30.000Z"
  },
  "request_id": "a1b2c3d4e5"
}
Field
Tipe
Keterangan
check_idstring
string
ID hasil cek. Kirim sebagai account_check_id di transaksi nominal bebas.
product_codestring
string
Kode produk.
customer_nostring
string
Nomor yang dicek.
account_namestring
string
Nama pemilik. Tampilkan ke pelanggan Anda dan minta konfirmasi sebelum mengirim uang.
expires_atstring
string
Hasil cek berlaku sampai waktu ini (30 menit, ISO 8601, UTC).
  • Memakai kelompok batas inquiry (default 60 per menit), sama dengan inquiry pascabayar.
  • Hasil cek hanya berlaku untuk produk dan nomor tujuan yang sama persis dengan yang dicek.
  • Nama tidak ditemukan: 422 ACCOUNT_NOT_FOUND. Penyedia belum menjawab: 503 SUPPLIER_UNAVAILABLE; tidak ada yang terpotong dan aman diulang.

Transfer bank / e-wallet nominal bebas#

Produk dengan is_open_amount bernilai true (transfer bank dan sebagian e-wallet) dibeli lewat POST /h2h/v1/transactions yang sama, dengan dua field tambahan. Header, ref_id, Idempotency-Key, status, dan cek status berlaku sama seperti transaksi prabayar.

  1. Lakukan cek nama dan simpan check_id.
  2. Kirim transaksi dengan amount dan account_check_id tersebut.
Field
Tipe
Keterangan
amountinteger
integer
Wajib untuk nominal bebas. Nominal rupiah yang dikirim ke tujuan, dalam batas di bawah.
account_check_idstring
string
Wajib untuk nominal bebas. check_id dari cek nama untuk produk dan customer_no yang sama, yang belum lewat 30 menit. Satu cek nama bisa dipakai untuk beberapa transaksi ke tujuan yang sama selama masih berlaku.

Field lain sama dengan transaksi prabayar.

# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/transactions"
BODY='{"product_code":"TFBCA","customer_no":"1234567890","amount":150000,"account_check_id":"8b7d4c1e-2a36-4f5b-9e08-6c1d3f2a9b47","ref_id":"INV-20261118-0003"}'
IDEMPOTENCY_KEY="trx-INV-20261118-0003"
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')

curl -X POST "https://api.bisadagang.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
  -H "X-Bisadagang-Timestamp: $TS" \
  -H "X-Bisadagang-Nonce: $NONCE" \
  -H "X-Bisadagang-Signature: $SIGNATURE" \
  --data "$BODY"
200 OK
{
  "success": true,
  "data": {
    "ref_id": "INV-20261118-0003",
    "transaction_id": "TF1794994800EF31",
    "product_code": "TFBCA",
    "product_type": "prepaid",
    "customer_no": "1234567890",
    "price": 152900,
    "status": "pending",
    "sn": null,
    "message": null,
    "created_at": "2026-11-18T09:35:00.000Z",
    "amount": 150000,
    "account_name": "BUDI CONTOH"
  },
  "request_id": "a1b2c3d4e5"
}
  • Harga. price adalah amount ditambah biaya (fee di daftar produk); angka di contoh hanya ilustrasi. max_price dibandingkan dengan total ini. Respons juga memuat amount dan account_name.
  • Hanya untuk nominal bebas. Mengirim amount atau account_check_id untuk produk bernominal tetap dijawab 400 VALIDATION_ERROR. Sebaliknya, produk nominal bebas tanpa amount juga dijawab VALIDATION_ERROR.

Batas nominal

Produk
Minimum
Maksimum
Transfer bankRp10.000
Rp10.000
Rp2.000.000
E-wallet DANARp1.000
Rp1.000
Rp500.000
E-wallet OVORp10.000
Rp10.000
Rp1.000.000
E-wallet GoPayRp20.000
Rp20.000
Rp1.000.000
E-wallet ShopeePayRp20.000
Rp20.000
Rp1.000.000
E-wallet LinkAjaRp20.000
Rp20.000
Rp1.000.000

Nominal di luar batas ditolak sebelum saldo dipotong. Produk nominal bebas yang batasnya belum ditetapkan tidak dijual dan dijawab PRODUCT_NOT_SUPPORTED.

422 · VALIDATION_ERROR
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Nominal harus antara Rp10.000 dan Rp2.000.000.",
    "details": { "min": 10000, "max": 2000000 }
  },
  "request_id": "a1b2c3d4e5"
}
422 · ACCOUNT_CHECK_REQUIRED
{
  "success": false,
  "error": {
    "code": "ACCOUNT_CHECK_REQUIRED",
    "message": "Cek nama tujuan dulu (POST /h2h/v1/account-check) dan kirim check_id-nya sebagai account_check_id. Cek nama berlaku 30 menit untuk produk dan tujuan yang sama.",
    "details": null
  },
  "request_id": "a1b2c3d4e5"
}

Kode error#

Format error, serta kode umum untuk autentikasi, validasi, dan batas request, ada di Format respons & kode error. Tabel di bawah hanya memuat kode yang khas untuk endpoint transaksi.

Kode
HTTP
Arti
VALIDATION_ERROR400
400
Body tidak valid, header Idempotency-Key kosong atau formatnya salah, atau amount/account_check_id dikirim untuk produk yang bukan nominal bebas. Nominal di luar batas dijawab dengan kode ini juga, tetapi HTTP 422 dan details berisi min dan max.
NOT_FOUND404
404
Cek status: ref_id tidak dikenal. Pembayaran: inquiry_id tidak dikenal atau bukan milik Anda.
PRODUCT_NOT_FOUND404
404
Kode produk tidak ada atau tidak tersedia.
REQUEST_IN_PROGRESS409
409
Request dengan Idempotency-Key yang sama masih diproses. Tunggu beberapa detik lalu kirim ulang.
PRODUCT_NOT_SUPPORTED422
422
Produk tidak bisa dipakai di endpoint ini: pascabayar di pembuatan transaksi, prabayar di inquiry, atau cek nama untuk produk selain transfer bank dan e-wallet. Produk nominal bebas yang belum dijual juga dijawab kode ini.
PRODUCT_DISRUPTED422
422
Produk sedang gangguan.
PRODUCT_DISABLED422
422
Produk tidak aktif untuk akun Anda. Aktifkan di dashboard. Jika produk dinonaktifkan otomatis karena success rate 24 jam di bawah batas Anda, details.reason bernilai auto_disabled, dan details juga berisi success_rate (saat dinonaktifkan; bisa null), threshold (batas Anda), dan disabled_at(ISO 8601 UTC). Pesannya: "Produk dinonaktifkan otomatis: success rate 24 jam di bawah batas Anda (90%). Produk aktif lagi otomatis setelah pulih, atau aktifkan sendiri di dashboard." Angka 90% mengikuti batas Anda. Produk yang Anda nonaktifkan sendiri dijawab tanpa details.
DESTINATION_BLOCKED422
422
Nomor tujuan tidak dapat diproses.
DESTINATION_LIMIT_REACHED422
422
Batas transaksi ke nomor tujuan itu sudah tercapai. Berlaku untuk e-wallet dan transfer bank. details.reason bernilai DAILY_LIMIT_EXCEEDED atau MONTHLY_LIMIT_EXCEEDED.
PRICE_CHANGED422
422
Harga melebihi max_price. Harga saat ini ada di details.price. Saldo tidak terpotong.
INSUFFICIENT_BALANCE422
422
Saldo kurang. Lihat Saldo tidak cukup.
IDEMPOTENCY_KEY_REUSED422
422
Idempotency-Key yang sama dipakai dengan body berbeda.
ACCOUNT_NOT_FOUND422
422
Cek nama: tidak ada nama pemilik untuk tujuan itu. Periksa nomornya.
ACCOUNT_CHECK_REQUIRED422
422
Transaksi nominal bebas tanpa account_check_id yang valid: tidak dikirim, tidak cocok dengan produk dan tujuan, atau sudah lewat 30 menit. Lakukan cek nama lagi.
INQUIRY_EXPIRED422
422
Inquiry sudah lewat 30 menit, atau tidak bisa dibayar lagi. Lakukan inquiry ulang.
INQUIRY_FAILED422
422
Penyedia menyatakan tidak ada tagihan yang bisa dibayar, misalnya sudah lunas atau nomor salah.
INQUIRY_ALREADY_PAID422
422
Inquiry ini sudah dibayar dengan ref_id lain, yang ada di details.ref_id.
SUPPLIER_UNAVAILABLE503
503
Penyedia belum menjawab inquiry. Tidak ada yang terpotong, aman diulang.
SERVICE_MAINTENANCE503
503
Layanan sedang pemeliharaan. Pembuatan transaksi, inquiry, dan pembayaran ditolak; cek status tetap bisa dipakai.
SANDBOX_NOT_AVAILABLE503
503
Tidak dipakai lagi: key sandbox kini bisa untuk transaksi, inquiry, pembayaran, dan cek nama.
  • Error 4xx pada pembuatan transaksi atau pembayaran berarti saldo tidak terpotong dan tidak ada transaksi yang dibuat.
  • Untuk 5xx atau timeout, kirim ulang dengan ref_id dan Idempotency-Key yang sama, atau cek status dulu. Lihat ref_id dan Idempotency-Key.
Sebelumnya
Daftar harga & produk
Berikutnya
Komplain
Butuh bantuan?
Tanya soal integrasi teknis lewat WhatsApp.
Chat di WhatsApp
Di halaman ini
  • Ringkasan
  • Transaksi prabayar
  • ref_id dan Idempotency-Key
  • Status transaksi
  • Cek status
  • Tagihan pascabayar
  • Komisi pascabayar
  • Cek nama rekening / e-wallet
  • Transfer bank / e-wallet nominal bebas
  • Kode error