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

Webhook

Bisadagang mengirim POST dengan signature ke server Anda setiap ada perubahan, jadi Anda tidak perlu terus-menerus cek status.

Ringkasan#

  • Kami mengirim POST dengan body JSON ke URL HTTPS Anda. Setiap request diberi signature dengan HMAC-SHA256 memakai secret whsec_… milik Anda.
  • Balas dengan status 2xx secepatnya (maksimal 10 detik), lalu proses di belakang. Selain 2xx, atau tidak ada balasan, kami kirim ulang sampai 8 percobaan.
  • Event bisa datang lebih dari sekali. Simpan event_id dan abaikan yang sudah pernah Anda terima.
  • Webhook sandbox dan production punya URL dan secret sendiri.
Webhook adalah jalur utama untuk status akhir. Cek status (GET /h2h/v1/transactions/{ref_id}) tetap tersedia sebagai cadangan, misalnya jika server Anda mati cukup lama.

URL dan secret#

Atur di dashboard, menu Webhook. Pilih environment (sandbox atau production), isi URL HTTPS lengkap, pilih event yang ingin diterima, lalu simpan.

  • Hanya https://. URL tanpa HTTPS ditolak saat disimpan.
  • Secret whsec_… dibuat otomatis saat URL pertama disimpan, terpisah untuk setiap environment, dan terpisah dari API secret. Lihat dengan tombol Lihat, simpan di environment variable (mis. BISADAGANG_WEBHOOK_SECRET), jangan di kode atau commit.
  • transaction.updated selalu aktif. Event lain bisa dipilih.

Header#

Header
Isi
Content-Type
application/json
X-Bisadagang-Event
Nama event, mis. transaction.updated.
X-Bisadagang-Delivery
ID pengiriman, sama dengan event_id di body. Tetap sama di setiap percobaan ulang.
X-Bisadagang-Timestamp
Waktu Unix dalam detik saat request ini diberi signature.
X-Bisadagang-Signature
Hex huruf kecil dari HMAC-SHA256. Saat rotasi secret berisi dua signature dipisah koma.

Event dan payload#

Semua event memakai amplop yang sama. Field data berbeda menurut event.

Field
Isi
event_id
ID unik pengiriman. Kunci idempotensi Anda.
event
Nama event.
environment
production atau sandbox.
created_at
Waktu event dibuat, ISO 8601 UTC.
data
Objek event, lihat di bawah.
Event
Dikirim saat
transaction.updated
Status transaksi berubah (pending, sukses, atau gagal). Selalu aktif.
complaint.updated
Status komplain berubah atau tim membalas.
product.auto_disabled
Produk dinonaktifkan otomatis karena success rate di bawah batas Anda.
product.auto_enabled
Produk aktif lagi otomatis setelah pulih.
product.created
Produk baru masuk katalog.
price.changed
Harga satu atau lebih produk berubah.
balance.low
Saldo turun di bawah batas peringatan Anda.

Setiap event di bawah punya tabel field data dan contoh lengkap dengan amplopnya. Tipe | null berarti field selalu ada, nilainya bisa null. Anggap field baru bisa muncul kapan saja dan abaikan field yang tidak Anda kenal.

transaction.updated

data berisi pesanan seperti respons cek status. Cocokkan dengan ref_id Anda. Event pending dikirim paling banyak satu kali untuk satu rentang pending, lalu satu event lagi untuk status akhirnya (sukses atau gagal).

Field data
Tipe
Isi
transaction_idstring
string
ID transaksi dari Bisadagang.
ref_idstring
string
ref_id dari Anda. Pakai ini untuk mencocokkan pesanan.
product_codestring
string
Kode produk.
customer_nostring
string
Nomor tujuan.
priceinteger
integer
Harga yang dipotong, dalam rupiah.
statusstring
string
pending, success, atau failed.
snstring | null
string | null
Serial number atau token. Terisi saat sukses jika produk punya SN.
messagestring | null
string | null
Keterangan dari penyedia, mis. alasan gagal.
transaction.updated
{
  "event_id": "whd_7Hq2Xn4K",
  "event": "transaction.updated",
  "environment": "sandbox",
  "created_at": "2026-11-19T03:15:42Z",
  "data": {
    "transaction_id": "PL1763522142AB12",
    "ref_id": "INV-20261119-0001",
    "product_code": "TSEL10",
    "customer_no": "081200000001",
    "price": 10450,
    "status": "success",
    "sn": "1234567890123456",
    "message": null
  }
}

complaint.updated

Dikirim saat status komplain berubah atau tim membalas. Balasan dan komplain yang Anda kirim sendiri tidak memicu event. Lihat API Komplain.

Field data
Tipe
Isi
complaint_idstring
string
ID komplain.
transaction_idstring
string
ID transaksi yang dikomplain.
ref_idstring
string
ref_id dari Anda.
statusstring
string
open, processing, atau resolved.
resultstring | null
string | null
Saat resolved: success atau failed. Selain itu null.
messageobject | null
object | null
Pesan terbaru dari tim atau sistem yang memicu event ini, atau null jika hanya status yang berubah.
message.fromstring
string
team atau system.
message.textstring
string
Isi pesan.
message.created_atstring
string
Waktu pesan, ISO 8601 UTC.
complaint.updated
{
  "event_id": "whd_Rk3Lm9Pa",
  "event": "complaint.updated",
  "environment": "production",
  "created_at": "2026-11-19T05:41:13Z",
  "data": {
    "complaint_id": "KMP1763527331A1K7",
    "transaction_id": "PL1763522142AB12",
    "ref_id": "INV-20261119-0001",
    "status": "resolved",
    "result": "success",
    "message": {
      "from": "system",
      "text": "Komplain selesai. Transaksi berstatus sukses.",
      "created_at": "2026-11-19T05:41:13.000Z"
    }
  }
}

product.auto_disabled

Hanya production. Dikirim saat success rate 24 jam sebuah produk turun di bawah batas Anda dan jumlah transaksi minimalnya terpenuhi. Produknya langsung nonaktif untuk akun Anda.

Field data
Tipe
Isi
product_codestring
string
Kode produk yang dinonaktifkan.
product_namestring
string
Nama produk.
categorystring
string
Kategori produk.
success_ratenumber
number
Success rate 24 jam terakhir, 0–100.
thresholdnumber
number
Batas success rate yang Anda atur, 0–100.
transactionsinteger
integer
Jumlah transaksi final dalam 24 jam yang dihitung.
min_transactionsinteger
integer
Jumlah transaksi minimal yang Anda atur agar aturan berlaku.
disabled_atstring
string
Waktu produk dinonaktifkan, ISO 8601 UTC.
product.auto_disabled
{
  "event_id": "whd_Tz8Vb2Qe",
  "event": "product.auto_disabled",
  "environment": "production",
  "created_at": "2026-11-19T06:10:00Z",
  "data": {
    "product_code": "AXIS10",
    "product_name": "Axis 10.000",
    "category": "Pulsa",
    "success_rate": 71.2,
    "threshold": 90,
    "transactions": 38,
    "min_transactions": 20,
    "disabled_at": "2026-11-19T06:10:00Z"
  }
}

product.auto_enabled

Hanya production. Dikirim saat produk yang dinonaktifkan otomatis pulih di atas batas dan aktif lagi. Produk yang Anda nonaktifkan sendiri tidak diaktifkan lagi dan tidak memicu event.
Aturan aktif lagi: produk sudah nonaktif minimal 1 jam, lalu success rate 24 jam mencapai batas Anda ditambah 5 poin (maksimal 100). Jika selama 24 jam tidak ada cukup transaksi final untuk dinilai (kurang dari minimal Anda), produk diaktifkan lagi dan success_rate bernilai 0. Jika Anda mematikan aturan nonaktif otomatis, produk yang tertahan aktif lagi tanpa event ini. Produk yang Anda aktifkan sendiri setelah dinonaktifkan otomatis dikecualikan dari nonaktif otomatis selama 1 jam.

Field data
Tipe
Isi
product_codestring
string
Kode produk yang aktif lagi.
product_namestring
string
Nama produk.
categorystring
string
Kategori produk.
success_ratenumber
number
Success rate 24 jam terakhir, 0–100.
thresholdnumber
number
Batas success rate yang Anda atur, 0–100.
enabled_atstring
string
Waktu produk diaktifkan lagi, ISO 8601 UTC.
product.auto_enabled
{
  "event_id": "whd_Ym4Ns7Cw",
  "event": "product.auto_enabled",
  "environment": "production",
  "created_at": "2026-11-19T09:35:00Z",
  "data": {
    "product_code": "AXIS10",
    "product_name": "Axis 10.000",
    "category": "Pulsa",
    "success_rate": 94.5,
    "threshold": 90,
    "enabled_at": "2026-11-19T09:35:00Z"
  }
}

product.created

Satu event untuk satu kali produk baru masuk katalog, bisa berisi beberapa produk. Field produk sama dengan daftar produk, ditambah active.

Field data
Tipe
Isi
totalinteger
integer
Jumlah produk baru di event ini.
productsarray
array
Produk baru. Maksimal 100 per event; lebih dari itu dikirim sebagai beberapa event.
products[].codestring
string
Kode produk.
products[].product_namestring
string
Nama produk.
products[].categorystring
string
Kategori.
products[].brandstring
string
Brand.
products[].typestring
string
Tipe produk, mis. Umum.
products[].product_typestring
string
prepaid atau postpaid.
products[].is_open_amountboolean
boolean
true untuk produk nominal bebas.
products[].statusstring
string
normal atau gangguan.
products[].priceinteger | null
integer | null
Harga untuk Anda (prabayar). Null untuk pascabayar.
products[].feeinteger | null
integer | null
Biaya tetap produk nominal bebas, jika ada.
products[].admin_feeinteger | null
integer | null
Biaya admin pascabayar.
products[].commissioninteger | null
integer | null
Komisi pascabayar untuk Anda.
products[].activeboolean
boolean
Apakah produk langsung aktif untuk akun Anda. Produk baru nonaktif kecuali kategorinya diatur aktif otomatis.
product.created
{
  "event_id": "whd_Df6Hj1Kx",
  "event": "product.created",
  "environment": "production",
  "created_at": "2026-11-19T07:00:00Z",
  "data": {
    "total": 2,
    "products": [
      {
        "code": "TSEL15",
        "product_name": "Telkomsel 15.000",
        "category": "Pulsa",
        "brand": "TELKOMSEL",
        "type": "Umum",
        "product_type": "prepaid",
        "is_open_amount": false,
        "status": "normal",
        "price": 15420,
        "fee": null,
        "admin_fee": null,
        "commission": null,
        "active": false
      },
      {
        "code": "BPJSKES",
        "product_name": "BPJS Kesehatan",
        "category": "Pascabayar",
        "brand": "BPJS KESEHATAN",
        "type": "Umum",
        "product_type": "postpaid",
        "is_open_amount": false,
        "status": "normal",
        "price": null,
        "fee": null,
        "admin_fee": 2500,
        "commission": 800,
        "active": true
      }
    ]
  }
}

price.changed

Satu event untuk satu kali pembaruan harga, bisa berisi beberapa produk. Hanya produk yang aktif untuk akun Anda yang dilaporkan, dan hanya field yang berubah di changes.

Field data
Tipe
Isi
totalinteger
integer
Jumlah produk yang harganya berubah di event ini.
productsarray
array
Produk yang berubah. Maksimal 100 per event; lebih dari itu dikirim sebagai beberapa event.
products[].codestring
string
Kode produk.
products[].product_namestring
string
Nama produk.
products[].product_typestring
string
prepaid atau postpaid.
products[].changesobject
object
Hanya field yang berubah: price, fee, admin_fee, dan/atau commission. Masing-masing berisi old dan new (rupiah).
products[].changes.price.oldinteger
integer
Harga prabayar sebelumnya.
products[].changes.price.newinteger
integer
Harga prabayar sekarang.
products[].changes.fee.oldinteger
integer
Biaya tetap sebelumnya, untuk produk nominal bebas (transfer bank, e-wallet nominal bebas).
products[].changes.fee.newinteger
integer
Biaya tetap sekarang.
products[].changes.admin_fee.oldinteger
integer
Biaya admin pascabayar sebelumnya.
products[].changes.admin_fee.newinteger
integer
Biaya admin pascabayar sekarang.
products[].changes.commission.oldinteger
integer
Komisi pascabayar sebelumnya.
products[].changes.commission.newinteger
integer
Komisi pascabayar sekarang.
price.changed
{
  "event_id": "whd_Lp9Wc3Rd",
  "event": "price.changed",
  "environment": "production",
  "created_at": "2026-11-19T08:00:00Z",
  "data": {
    "total": 3,
    "products": [
      {
        "code": "TSEL10",
        "product_name": "Telkomsel 10.000",
        "product_type": "prepaid",
        "changes": {
          "price": {
            "old": 10450,
            "new": 10520
          }
        }
      },
      {
        "code": "TFBCA",
        "product_name": "Transfer Bank BCA",
        "product_type": "prepaid",
        "changes": {
          "fee": {
            "old": 2500,
            "new": 3000
          }
        }
      },
      {
        "code": "PLNPASCA",
        "product_name": "PLN Pascabayar",
        "product_type": "postpaid",
        "changes": {
          "admin_fee": {
            "old": 2750,
            "new": 3000
          },
          "commission": {
            "old": 1200,
            "new": 1100
          }
        }
      }
    ]
  }
}

balance.low

Hanya production. Dikirim sekali saat saldo turun di bawah batas peringatan Anda (atur di dashboard, menu Saldo), dan baru dikirim lagi setelah saldo naik di atas batas lalu turun lagi.

Field data
Tipe
Isi
balanceinteger
integer
Saldo saat ini, dalam rupiah.
thresholdinteger
integer
Batas peringatan yang Anda atur di dashboard.
currencystring
string
IDR.
balance.low
{
  "event_id": "whd_Gu5Xa8Ne",
  "event": "balance.low",
  "environment": "production",
  "created_at": "2026-11-19T10:22:00Z",
  "data": {
    "balance": 480000,
    "threshold": 500000,
    "currency": "IDR"
  }
}

Verifikasi signature#

Selalu verifikasi sebelum memproses. Tanpa ini siapa pun yang tahu URL Anda bisa mengirim status palsu.

  1. Ambil body mentah persis seperti diterima, sebelum di-parse menjadi JSON.
  2. Susun teks timestamp + "." + body, dengan timestamp dari header X-Bisadagang-Timestamp.
  3. Hitung HMAC-SHA256 dengan seluruh secret whsec_… sebagai kunci, hasilnya hex huruf kecil.
  4. Bandingkan dengan header X-Bisadagang-Signature secara constant-time.
  5. Tolak jika timestamp lebih dari 300 detik dari jam server Anda (mencegah request lama dipakai ulang).

Contoh uji

Pakai nilai tetap ini untuk memastikan fungsi Anda benar. Secret ini hanya contoh dan tidak pernah dipakai.

Input
Nilai
secret
whsec_contoh_rahasia_jangan_dipakai
timestamp
1763522142
body
Payload transaction.updated di atas, ditulis dalam satu baris tanpa spasi tambahan.
signature
16587d07452dff66f95860bd51f9cc322d41cbe5b31e89ad9c9fea3f58277ef2

Contoh kode

import { createHmac, timingSafeEqual } from 'node:crypto';

// true jika salah satu signature di header cocok (dua signature dipisah koma saat rotasi secret)
export function verifySignature(secret, timestamp, rawBody, signatureHeader) {
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return String(signatureHeader)
    .split(',')
    .some(sig => {
      const given = Buffer.from(sig.trim(), 'hex');
      const want = Buffer.from(expected, 'hex');
      return given.length === want.length && timingSafeEqual(given, want);
    });
}

import express from 'express';

const app = express();

// Pakai body mentah. Jangan verifikasi hasil JSON.parse, karena susunan teksnya bisa berubah.
app.post('/webhooks/bisadagang', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.get('X-Bisadagang-Timestamp');
  const signature = req.get('X-Bisadagang-Signature');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const valid = verifySignature(process.env.BISADAGANG_WEBHOOK_SECRET, timestamp, rawBody, signature);
  if (!fresh || !valid) return res.sendStatus(401);

  const event = JSON.parse(rawBody);
  // Simpan event.event_id dengan aturan unik. Jika sudah ada, abaikan (event duplikat).
  // Proses di belakang (antrean atau worker), jangan di sini.
  res.sendStatus(200);
});

app.listen(3000);

Contoh JavaScript untuk Node.js 18 ke atas dengan Express, contoh Python dengan Flask. Fungsi verifikasinya (verifySignature, verify_signature di Python) diuji dengan nilai contoh di atas.

Cara membalas#

  • Balas 2xx (biasanya 200) tanpa menunggu pekerjaan selesai. Body balasan tidak dipakai.
  • Simpan event ke database atau antrean, balas, lalu proses di worker. Proses yang lambat di dalam handler membuat kami menunggu, lalu menganggap gagal setelah 10 detik.
  • Signature salah atau timestamp lebih dari 300 detik dari jam server Anda: balas 401. Jangan balas 2xx untuk request yang tidak lolos verifikasi.
  • Balasan 3xx tidak diikuti dan dihitung gagal. Daftarkan URL akhir.

Jadwal kirim ulang#

Pengiriman dianggap berhasil hanya jika server Anda membalas 2xx. Jika tidak, kami mencoba lagi dengan jeda yang makin panjang, total 8 percobaan dalam sekitar 24 jam. Waktu di bawah adalah perkiraan, dihitung dari event dibuat.

Percobaan
Waktu
1
Langsung
2
±1 menit
3
±6 menit
4
±21 menit
5
±1 jam 21 menit
6
±3 jam 21 menit
7
±9 jam 21 menit
8
±24 jam

Setelah percobaan ke-8gagal, kami berhenti dan menampilkan peringatan di dashboard (dan email jika notifikasi “webhook gagal” aktif). Event itu tetap ada di log selama 30 hari dan bisa dikirim ulang manual.

Idempotensi#

  • Satu event bisa tiba lebih dari sekali: percobaan ulang setelah balasan Anda terlambat, atau kirim ulang manual. Semuanya membawa event_id yang sama.
  • Simpan event_id dengan aturan unik. Jika sudah ada, balas 200 dan lewati.
  • Satu transaksi bisa menghasilkan beberapa event (pending paling banyak sekali per rentang pending, lalu status akhir) dengan event_id berbeda, dan urutan tiba tidak dijamin. Gunakan data.status dan created_at, dan jangan menurunkan transaksi yang sudah final.

Kirim tes dan log#

  • Kirim tes di dashboard mengirim satu event bernama webhook.test, bertanda tangan, ke URL environment yang dipilih, lalu menampilkan kode balasan dan lamanya. Balas 2xx seperti event biasa. Event tes tidak masuk log pengiriman dan tidak dikirim ulang. Isidata-nya selalu { "message": "Tes webhook dari Bisadagang Bisnis." }; abaikan setelah signature lolos.
  • Log pengiriman menyimpan 30 hari terakhir: filter Gagal dan per event, detail request (header, body) dan balasan server Anda (dipotong 2 KB), serta semua percobaan.
  • Kirim ulang menambah satu percobaan dengan ID pengiriman yang sama, dari log atau dari halaman detail transaksi.
  • Di sandbox, nomor tujuan skenario (lihat Sandbox) memicu event sungguhan ke URL sandbox Anda.

Rotasi secret#

Rotasi di dashboard jika secret bocor atau orang yang tahu sudah keluar. Mulai saat itu webhook diberi signature dengan secret baru; secret lama tetap berlaku 24 jam lagi. Selama itu header X-Bisadagang-Signature membawa dua signature dipisah koma, dan contoh kode di atas menerima salah satunya. Perbarui environment variable di server Anda dalam jangka waktu tersebut.

Sebelumnya
Komplain
Berikutnya
Sandbox
Butuh bantuan?
Tanya soal integrasi teknis lewat WhatsApp.
Chat di WhatsApp
Di halaman ini
  • Ringkasan
  • URL dan secret
  • Header
  • Event dan payload
  • Verifikasi signature
  • Cara membalas
  • Jadwal kirim ulang
  • Idempotensi
  • Kirim tes dan log
  • Rotasi secret