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
Dasar

Autentikasi & signature

Setiap request ke API Bisadagang Bisnis membawa API key dan signature HMAC-SHA256 yang dihitung dengan API secret. Secret tidak pernah dikirim.

Header wajib#

Kirim empat header ini di setiap request. Hanya HTTPS yang diterima.

Header
Isi
X-Bisadagang-Key
API key. bdk_live_… untuk production, bdk_test_… untuk sandbox. Environment ditentukan oleh key.
X-Bisadagang-Timestamp
Waktu Unix dalam detik (bukan milidetik). Selisihnya dengan waktu server paling banyak 300 detik.
X-Bisadagang-Nonce
String acak 16–64 karakter (A-Z a-z 0-9 _ -), baru untuk setiap request. Nonce yang sama ditolak selama 10 menit.
X-Bisadagang-Signature
Hex huruf kecil dari HMAC-SHA256 atas string canonical (lihat di bawah).

Menghitung signature#

Gabungkan lima bagian dengan baris baru (\n) menjadi string canonical, lalu hitung HMAC-SHA256 dengan API secret sebagai kunci. Hasilnya ditulis sebagai hex huruf kecil.

canonical
METHOD
PATH_DENGAN_QUERY
TIMESTAMP
NONCE
HEX_SHA256_BODY
  • METHOD: huruf besar, mis. GET.
  • PATH_DENGAN_QUERY: path dan query string persis seperti dikirim, tanpa domain, mis. /h2h/v1/products?category=Pulsa. Jika query di-encode (mis. %20), tanda tangani versi yang sudah di-encode.
  • TIMESTAMP dan NONCE: sama persis dengan isi header.
  • HEX_SHA256_BODY: SHA-256 (hex huruf kecil) dari byte body yang dikirim. Untuk GET, body kosong, jadi hasilnya SHA-256 dari string kosong.

Contoh kode#

Fungsi siap pakai yang membuat keempat header, beserta satu panggilan ke /h2h/v1/balance. Key dan secret dibaca dari environment variable BISADAGANG_API_KEY dan BISADAGANG_API_SECRET.

# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/balance"
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"

Contoh JavaScript untuk Node.js 18 ke atas. Contoh Python memakai library requests.

Contoh uji#

Pakai nilai tetap ini untuk memastikan fungsi signature Anda benar. Secret di sini hanya contoh.

Input
Nilai
secret
rahasia-contoh
method
GET
path
/h2h/v1/products?category=Pulsa
timestamp
1763337600
nonce
0123456789abcdef0123456789abcdef
body
kosong

String canonical

canonical
GET
/h2h/v1/products?category=Pulsa
1763337600
0123456789abcdef0123456789abcdef
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Signature yang benar

X-Bisadagang-Signature
1c70ec830551bf90d017616759d563f395be4fbf5528f0beeb01ac5fad71cae6

Request dengan body#

Endpoint GET tidak membawa body. Endpoint transaksi memakai POST dengan body JSON, dan aturannya:

  • Kirim JSON dengan Content-Type: application/json. Jenis lain ditolak dengan UNSUPPORTED_CONTENT_TYPE.
  • Signaturei byte body yang benar-benar dikirim. Buat string JSON sekali, lalu pakai string yang sama untuk signature dan untuk body request.

Whitelist IP#

  • Key production hanya diterima dari IP yang didaftarkan di dashboard. Selama daftar masih kosong, semua request production ditolak.
  • Key sandbox bisa dipakai dari IP mana saja, kecuali Anda mengisi daftar IP sandbox.
  • IP dicocokkan persis, tanpa rentang atau CIDR. Jika server Anda keluar lewat IPv6, daftarkan alamat IPv6-nya juga.

Error IP_NOT_WHITELISTED menyertakan IP yang terlihat oleh Bisadagang di error.details.ip:

403 · IP_NOT_WHITELISTED
{
  "success": false,
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "IP 203.0.113.10 tidak terdaftar untuk API key ini.",
    "details": { "ip": "203.0.113.10" }
  },
  "request_id": "a1b2c3d4e5"
}

Error autentikasi#

Pemeriksaan berjalan berurutan; error pertama yang ditemukan yang dikembalikan.

Kode
HTTP
Penyebab
HTTPS_REQUIRED403
403
Request dikirim lewat HTTP.
INVALID_API_KEY401
401
Header key kosong, key tidak dikenal, atau key sudah dicabut.
TIMESTAMP_OUT_OF_RANGE401
401
Timestamp bukan detik Unix atau selisihnya lebih dari 300 detik.
UNSUPPORTED_CONTENT_TYPE415
415
Request membawa body yang bukan JSON.
INVALID_SIGNATURE401
401
Signature tidak cocok, atau format nonce/signature salah.
NONCE_REUSED401
401
Nonce sudah pernah dipakai. Buat nonce baru di setiap request, termasuk saat mengulang.
PARTNER_NOT_ACTIVE403
403
Akun Mitra Bisnis belum aktif.
PARTNER_SUSPENDED403
403
Akun Mitra Bisnis dibekukan. Hubungi Bisadagang.
IP_NOT_WHITELISTED403
403
IP server tidak ada di whitelist key ini.
Mengulang request yang gagal? Hitung ulang timestamp, nonce, dan signature. Mengirim ulang header yang sama akan ditolak dengan NONCE_REUSED. Format semua error ada di Format respons & kode error.
Sebelumnya
Quick start
Berikutnya
Format respons & kode error
Butuh bantuan?
Tanya soal integrasi teknis lewat WhatsApp.
Chat di WhatsApp
Di halaman ini
  • Header wajib
  • Menghitung signature
  • Contoh kode
  • Contoh uji
  • Request dengan body
  • Whitelist IP
  • Error autentikasi