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

Komplain

Beri pelanggan Anda tombol “ajukan komplain” yang langsung terhubung ke tim Bisadagang, tanpa membuka dashboard.

Ringkasan#

Komplain lewat API dan lewat dashboard masuk ke antrean yang sama di tim Bisadagang dan tampil bersama di menu Komplain. Perubahan statusnya dikirim ke webhook Anda.

Endpoint
Per menit
Kegunaan
POST /h2h/v1/complaints60
60
Ajukan komplain untuk satu transaksi.
GET /h2h/v1/complaints/{complaint_id}120
120
Cek status dan percakapan satu komplain.
GET /h2h/v1/complaints120
120
Daftar komplain, terbaru dulu.
POST /h2h/v1/complaints/{complaint_id}/messages60
60
Kirim balasan atau info tambahan.
  • Autentikasi dan signature sama dengan endpoint lain; lihat Autentikasi & signature. Request POST membawa body JSON yang ikut diberi signature. Tidak perlu Idempotency-Key: komplain yang sama tidak bisa dibuat dua kali (lihat COMPLAINT_EXISTS).
  • Key production hanya melihat komplain production, key sandbox hanya komplain sandbox.
  • Respons sukses memakai 200 OK dan format yang sama dengan endpoint lain; lihat Format respons & kode error.

Aturan komplain#

  • Pending bisa dikomplain langsung, tanpa menunggu lama. Anda yang menilai kapan pelanggan sudah menunggu terlalu lama.
  • Sukses tetapi belum masuk ke pelanggan juga bisa dikomplain (pulsa belum masuk, SN atau token tidak valid).
  • Gagal tidak bisa dikomplain. Saldo sudah dikembalikan otomatis.
  • Batas pengajuan H+7: 7 × 24 jam sejak transaksi dibuat (created_at transaksi). Setelahnya komplain ditolak.
  • Satu komplain aktif per transaksi. Selama komplain berstatus open atau processing, mengajukan lagi dijawab COMPLAINT_EXISTS. Setelah resolved, Anda boleh mengajukan lagi selama masih dalam batas H+7.
Status transaksi
Alasan (reason) yang boleh
pending
pending_too_long (pending terlalu lama) atau other.
success
success_not_received (sukses tapi belum masuk), invalid_sn (SN atau token tidak valid), atau other.
failed
Tidak ada. Dijawab COMPLAINT_NOT_ALLOWED.

Buat komplain#

POST/h2h/v1/complaints

Body

Field
Tipe
Keterangan
ref_idstring
string
Salah satu dari ref_id atau transaction_id, tidak keduanya dan tidak kosong. ref_id adalah referensi dari sistem Anda saat membuat transaksi.
transaction_idstring
string
ID transaksi dari Bisadagang (data.transaction_id di respons transaksi). Gunakan ini atau ref_id.
reasonstring
string
Wajib. pending_too_long, success_not_received, invalid_sn, atau other. Harus cocok dengan status transaksi; lihat Aturan komplain.
notestring
string
Opsional, maksimal 1000 karakter. Wajib minimal 10 karakter jika reason adalah other. Jadi pesan pertama di percakapan.

Request

# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints"
BODY='{"ref_id":"INV-20261119-0001","reason":"pending_too_long","note":"Pelanggan sudah menunggu lebih dari 2 jam."}'
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"

Respons

Komplain langsung berstatus open dan masuk antrean tim.

200 OK
{
  "success": true,
  "data": {
    "complaint_id": "KMP1763527331A1K7",
    "transaction_id": "PL1763522142AB12",
    "ref_id": "INV-20261119-0001",
    "product_code": "TSEL10",
    "product_name": "Telkomsel 10.000",
    "customer_no": "081200000001",
    "price": 10450,
    "reason": "pending_too_long",
    "status": "open",
    "result": null,
    "source": "api",
    "environment": "production",
    "created_at": "2026-11-19T05:20:00.000Z",
    "messages": [
      {
        "from": "partner",
        "text": "Pelanggan sudah menunggu lebih dari 2 jam.",
        "created_at": "2026-11-19T05:20:00.000Z"
      }
    ]
  },
  "request_id": "a1b2c3d4e5"
}
409 · COMPLAINT_EXISTS
{
  "success": false,
  "error": {
    "code": "COMPLAINT_EXISTS",
    "message": "Transaksi ini masih punya komplain yang belum selesai.",
    "details": { "complaint_id": "KMP1763527331A1K7" }
  },
  "request_id": "a1b2c3d4e5"
}
422 · COMPLAINT_WINDOW_CLOSED
{
  "success": false,
  "error": {
    "code": "COMPLAINT_WINDOW_CLOSED",
    "message": "Batas pengajuan komplain (7 hari sejak transaksi) sudah lewat.",
    "details": { "deadline": "2026-11-12T09:15:30.000Z" }
  },
  "request_id": "a1b2c3d4e5"
}
422 · COMPLAINT_NOT_ALLOWED
{
  "success": false,
  "error": {
    "code": "COMPLAINT_NOT_ALLOWED",
    "message": "Transaksi gagal tidak perlu dikomplain. Saldo sudah dikembalikan.",
    "details": { "status": "failed", "allowed_reasons": [] }
  },
  "request_id": "a1b2c3d4e5"
}

Objek komplain#

Semua endpoint komplain mengembalikan objek ini (atau daftarnya) di dalam data.

Field
Tipe
Keterangan
complaint_idstring
string
ID komplain, mis. KMP1763527331A1K7. Anggap sebagai teks acak; jangan menebak formatnya.
transaction_idstring
string
ID transaksi dari Bisadagang.
ref_idstring
string
ref_id Anda untuk transaksi itu.
product_codestring
string
Kode produk.
product_namestring
string
Nama produk.
customer_nostring
string
Nomor tujuan.
priceinteger
integer
Harga transaksi, rupiah.
reasonstring
string
pending_too_long, success_not_received, invalid_sn, atau other.
statusstring
string
open, processing, atau resolved. Lihat Status.
resultstring | null
string | null
Saat resolved: success atau failed. Selain itu null.
sourcestring
string
api atau dashboard: dari mana komplain diajukan.
environmentstring
string
production atau sandbox.
created_atstring
string
Waktu komplain dibuat, ISO 8601 UTC.
messagesarray
array
Percakapan, yang lama dulu. Pesan pertama adalah note Anda jika diisi; tanpa note, messages kosong sampai ada balasan.
messages[].fromstring
string
partner (Anda), team (tim Bisadagang), atau system (otomatis, mis. saat selesai).
messages[].textstring
string
Isi pesan.
messages[].created_atstring
string
Waktu pesan, ISO 8601 UTC.

Cek komplain#

GET/h2h/v1/complaints/{complaint_id}
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints/KMP1763527331A1K7"
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 · resolved
{
  "success": true,
  "data": {
    "complaint_id": "KMP1763527331A1K7",
    "transaction_id": "PL1763522142AB12",
    "ref_id": "INV-20261119-0001",
    "product_code": "TSEL10",
    "product_name": "Telkomsel 10.000",
    "customer_no": "081200000001",
    "price": 10450,
    "reason": "pending_too_long",
    "status": "resolved",
    "result": "success",
    "source": "api",
    "environment": "production",
    "created_at": "2026-11-19T05:20:00.000Z",
    "messages": [
      {
        "from": "partner",
        "text": "Pelanggan sudah menunggu lebih dari 2 jam.",
        "created_at": "2026-11-19T05:20:00.000Z"
      },
      {
        "from": "team",
        "text": "Sudah kami cek ke penyedia, pulsa masuk.",
        "created_at": "2026-11-19T05:41:12.000Z"
      },
      {
        "from": "system",
        "text": "Komplain selesai. Transaksi berstatus sukses.",
        "created_at": "2026-11-19T05:41:13.000Z"
      }
    ]
  },
  "request_id": "a1b2c3d4e5"
}

Komplain yang tidak ada atau milik Mitra Bisnis lain dijawab 404 NOT_FOUND.

Daftar komplain#

GET/h2h/v1/complaints

Komplain dari API dan dashboard muncul bersama, terbaru dulu.

Parameter
Keterangan
status
Opsional. open, processing, atau resolved.
ref_id
Opsional. Hanya komplain untuk transaksi dengan ref_id ini.
transaction_id
Opsional. Hanya komplain untuk transaksi ini.
limit
Opsional. 1 sampai 100, default 50.
cursor
Opsional. Isi dengan next_cursor dari respons sebelumnya untuk halaman berikutnya.
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints?status=open&limit=20"
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
{
  "success": true,
  "data": {
    "complaints": [
      {
          "complaint_id": "KMP1763527331A1K7",
          "transaction_id": "PL1763522142AB12",
          "ref_id": "INV-20261119-0001",
          "product_code": "TSEL10",
          "product_name": "Telkomsel 10.000",
          "customer_no": "081200000001",
          "price": 10450,
          "reason": "pending_too_long",
          "status": "open",
          "result": null,
          "source": "api",
          "environment": "production",
          "created_at": "2026-11-19T05:20:00.000Z",
          "messages": [
            {
              "from": "partner",
              "text": "Pelanggan sudah menunggu lebih dari 2 jam.",
              "created_at": "2026-11-19T05:20:00.000Z"
            }
          ]
        }
    ],
    "next_cursor": null
  },
  "request_id": "a1b2c3d4e5"
}

next_cursor bernilai null di halaman terakhir. Jangan menyusun isinya sendiri.

Balas komplain#

POST/h2h/v1/complaints/{complaint_id}/messages

Kirim info tambahan atau jawaban untuk tim, misalnya bukti dari pelanggan. Balasan hanya diterima selama komplain open atau processing.

Field
Tipe
Keterangan
textstring
string
Wajib, 1 sampai 1000 karakter.
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints/KMP1763527331A1K7/messages"
BODY='{"text":"Pelanggan mengirim bukti struk, bisa kami lampirkan?"}'
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"

Respons 200 OK berisi objek komplain lengkap dengan balasan Anda di messages. Komplain yang sudah resolved dijawab 422 COMPLAINT_CLOSED; ajukan komplain baru jika masalahnya muncul lagi dan masih dalam batas H+7.

Status#

Status
Arti
open
Diterima, belum diambil tim.
processing
Sedang ditangani tim. Balasan pertama tim pada komplain open juga mengubahnya menjadi processing, dalam satu event webhook.
resolved
Selesai. result mengikuti status akhir transaksi: success jika transaksi sukses, atau failed jika transaksi gagal dan saldo sudah dikembalikan. Komplain pada transaksi yang masih pending baru bisa selesai setelah transaksinya final. Pesan penutup dari system menyebut hasilnya. Pantau juga transaction.updated.

Webhook complaint.updated#

Event complaint.updated dikirim setiap status komplain berubah dan setiap kali tim atau sistem menambah pesan. Komplain yang Anda ajukan dan balasan yang Anda kirim sendiri tidak memicu event. Event ini tidak selalu aktif: pilih di menu Webhook di dashboard. Signature, retry, dan idempotensi sama dengan event lain; lihat Webhook untuk tabel field-nya.

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"
    }
  }
}

Sandbox#

  • Key sandbox bisa mengajukan komplain untuk transaksi sandbox dengan aturan dan format yang sama.
  • Komplain sandbox tidak diteruskan ke tim. Sekitar 30 detik setelah dibuat, sistem otomatis menyelesaikannya (resolved, result success) dan mengirim complaint.updated ke URL webhook sandbox Anda.

Kode error#

Kode
HTTP
Arti
VALIDATION_ERROR400
400
Body atau parameter tidak valid: ref_id dan transaction_id keduanya diisi atau keduanya kosong, reason tidak dikenal, note atau text lebih dari 1000 karakter, note kurang dari 10 karakter untuk other, atau text kosong.
NOT_FOUND404
404
Transaksi atau komplain tidak ditemukan, atau bukan milik Anda.
COMPLAINT_EXISTS409
409
Transaksi masih punya komplain open atau processing. ID-nya ada di details.complaint_id.
COMPLAINT_NOT_ALLOWED422
422
Transaksi gagal (saldo sudah dikembalikan), atau reason tidak cocok dengan status transaksi. details.status berisi status transaksi dan details.allowed_reasons daftar alasan yang boleh.
COMPLAINT_WINDOW_CLOSED422
422
Sudah lewat H+7. Batasnya ada di details.deadline.
COMPLAINT_CLOSED422
422
Balasan ke komplain yang sudah resolved. Ajukan komplain baru.
Kode error umum (autentikasi, RATE_LIMITED, INTERNAL_ERROR) ada di Format respons & kode error. Tangani kode yang belum Anda kenal berdasarkan status HTTP-nya.
Sebelumnya
Transaksi
Berikutnya
Webhook
Butuh bantuan?
Tanya soal integrasi teknis lewat WhatsApp.
Chat di WhatsApp
Di halaman ini
  • Ringkasan
  • Aturan komplain
  • Buat komplain
  • Objek komplain
  • Cek komplain
  • Daftar komplain
  • Balas komplain
  • Status
  • Webhook complaint.updated
  • Sandbox
  • Kode error