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.
bdk_live_… untuk production, bdk_test_… untuk sandbox. Environment ditentukan oleh key.A-Z a-z 0-9 _ -), baru untuk setiap request. Nonce yang sama ditolak selama 10 menit.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.
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.
rahasia-contohGET/h2h/v1/products?category=Pulsa17633376000123456789abcdef0123456789abcdefString canonical
GET
/h2h/v1/products?category=Pulsa
1763337600
0123456789abcdef0123456789abcdef
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855Signature yang benar
1c70ec830551bf90d017616759d563f395be4fbf5528f0beeb01ac5fad71cae6Request 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 denganUNSUPPORTED_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:
{
"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.
NONCE_REUSED. Format semua error ada di Format respons & kode error.