Tahap pengembanganVersi kontrak 0.1.0

Dokumentasi API

Buat tagihan retribusi dan ikuti status pembayarannya dari backend aplikasi Anda. Panduan ini menjelaskan request, respons, dan langkah penanganan untuk API SIMPUL PAD Kabupaten Garut.

Mulai integrasi Ajukan akses API

Akses memerlukan persetujuan BAPENDA

Aplikasi, layanan retribusi, dan ruang lingkup akses harus disetujui sebelum API key dapat digunakan. Simpan API key dan signing secret webhook di backend Anda.

Mulai cepat

Siapkan aplikasi yang disetujui, API key aktif, dan ID layanan retribusi. Contoh memakai VA dengan nominal Rp25.000. Ganti nominal sesuai tarif layanan Anda.

Siapkan kredensial
Buka portal pengembang, pilih aplikasi, lalu ambil API key dan ID layanan yang disetujui.
Atur variabel backend
Ganti placeholder pada contoh terminal. Tentukan satu key untuk satu invoice dan simpan waktu kedaluwarsa untuk digunakan saat retry.
Kirim request pembuatan
Gunakan POST /api/v1/bills. Simpan data.id dari respons. HTTP 202 berarti tagihan diterima dan metode pembayaran sedang diterbitkan.
Baca hasil dan ikuti pembayaran
Gunakan GET tagihan atau webhook. Tampilkan metode pembayaran aktif. Tandai lunas saat status paid telah terkonfirmasi.

Persiapan terminal

# Jalankan di terminal backend dengan shell Bash.
export BASE_URL="https://simpul-pad.bapenda.garutkab.go.id"
export SIMPUL_API_KEY="<API_KEY_APLIKASI_ANDA>"
export SERVICE_ID="<UUID_LAYANAN_YANG_DISETUJUI>"
export IDEMPOTENCY_KEY="invoice-2026-00000001"

# Gunakan Node.js untuk membuat waktu kedaluwarsa 24 jam ke depan.
# Jalankan sekali, lalu simpan nilainya untuk request dan retry.
export EXPIRES_AT="$(node -e 'process.stdout.write(new Date(Date.now() + 86400000).toISOString())')"

cURL, Node.js, dan Python pada referensi endpoint menggunakan variabel ini. Untuk lingkungan lain, sesuaikan BASE_URL dengan alamat SIMPUL PAD yang diberikan operator. ID, nomor pembayaran, dan waktu pada contoh respons hanya ilustrasi.

Autentikasi

Setiap endpoint tagihan memerlukan API key aplikasi pada header Authorization. Key memiliki awalan sp_ dan hanya ditampilkan sekali saat dibuat di portal pengembang.

AuthorizationheaderWajib: Bearer diikuti satu spasi dan API key aktif. Akses dibatasi ke aplikasi dan layanan yang disetujui.
Content-Typeheader · POSTWajib: application/json. Wajib pada pembuatan dan pembatalan tagihan.
Idempotency-Keyheader · buat tagihanWajib: 16–100 karakter: A-Z, a-z, 0-9, titik, garis bawah, titik dua, dan tanda hubung. Gunakan key yang sama untuk retry invoice yang sama.
X-Request-IdheaderOpsional: ID pelacakan opsional, 8–100 karakter dengan karakter yang sama seperti Idempotency-Key. Simpan request_id dari respons untuk penelusuran masalah.

Header request pembuatan

Authorization: Bearer <API_KEY_APLIKASI_ANDA>
Content-Type: application/json
Idempotency-Key: invoice-2026-00000001
X-Request-Id: request-2026-00000001

Panggil API dari backend

Jangan menyertakan API key dalam JavaScript browser, aplikasi mobile, URL, atau log. Jika key bocor, cabut key di portal pengembang dan buat penggantinya.

Format data

JSONrequest & respons: Kirim body sebagai objek JSON. Field yang tidak dikenal ditolak, termasuk field tambahan di dalam payer.
Rupiahstring digit: Gunakan "25000", bukan 25000, "25.000", "25000.00", atau "Rp25.000". Simpan nilai rupiah tanpa konversi floating point.
TanggalISO 8601 · UTC: Gunakan akhiran Z, misalnya 2026-10-09T06:30:00.000Z. Ubah ke waktu lokal hanya saat ditampilkan. Untuk Asia/Jakarta, contoh tersebut adalah 9 Oktober 2026 pukul 13.30 WIB.

Alur satu tagihan

POST → 202 / issuing
Tagihan tersimpan, metode pembayaran belum siap.
GET → 200 / unpaid
Metode pembayaran aktif dapat ditampilkan.
Webhook / GET → paid
Pembayaran penuh sudah tercatat.

HTTP sukses menjelaskan hasil request. data.status menjelaskan keadaan tagihan. Jangan menyimpulkan pembayaran lunas dari HTTP 200 atau 202 saja.

Buat tagihan

POST/api/v1/bills

Buat tagihan untuk layanan yang disetujui. SIMPUL PAD memvalidasi tarif dan menyimpan tagihan, lalu menerbitkan VA atau QRIS secara asinkron. Semua request memerlukan header autentikasi dan Idempotency-Key.

Body request

service_idstring · UUIDWajib: ID layanan retribusi yang telah disetujui untuk aplikasi Anda. Ambil dari detail aplikasi di portal pengembang.
payment_methodstringOpsional: Pilihan "virtual_account" atau "qris". Default "virtual_account". QRIS memerlukan konfigurasi QRIS bank BJB oleh operator.
external_referencestringOpsional: Referensi invoice dari sistem Anda, maksimal 100 karakter. Karakter yang diterima: A-Z, a-z, 0-9, titik, garis bawah, titik dua, garis miring, dan tanda hubung. Tidak menggantikan Idempotency-Key.
payerobjectWajib: Identitas wajib retribusi. Isi payer.name dan, jika tersedia, payer.address.
amount_rupiahstringWajib: Nominal rupiah bulat, 1–12 digit, lebih besar dari nol, tanpa nol di awal. Contoh: "25000". Harus sesuai tarif atau batas nominal layanan yang disetujui.
expires_atstring · UTCWajib: Waktu kedaluwarsa ISO 8601 dengan akhiran Z. Minimal 5 menit dan maksimal 366 hari setelah waktu request. Contoh: 2026-10-09T06:30:00.000Z.

Field di dalam payer

payer.namestringWajib: Nama wajib retribusi, 1–255 karakter setelah spasi di awal dan akhir dihapus.
payer.addressstringOpsional: Alamat wajib retribusi, 1–255 karakter jika diisi. Hilangkan field ini jika tidak tersedia.

202 berarti diterima, belum lunas

Respons awal berstatus issuing dan payment_methods dapat kosong. Simpan data.id, lalu baca tagihan atau tunggu event bill.payment_method_ready sebelum menampilkan instruksi pembayaran.

Request buat tagihan

curl -i -X POST "$BASE_URL/api/v1/bills" \
  -H "Authorization: Bearer $SIMPUL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data @- <<JSON
{
  "service_id": "$SERVICE_ID",
  "external_reference": "invoice/2026/001",
  "payer": {
    "name": "Wajib Retribusi",
    "address": "Garut"
  },
  "amount_rupiah": "25000",
  "payment_method": "virtual_account",
  "expires_at": "$EXPIRES_AT"
}
JSON

202 Accepted · tagihan baru

{
  "data": {
    "id": "018f0f79-16ea-7ad0-a9dd-120a8c001001",
    "billing_number": "3512345678901234",
    "status": "issuing",
    "amount_rupiah": "25000",
    "paid_rupiah": "0",
    "expires_at": "2026-10-09T06:30:00.000Z",
    "payment_methods": [],
    "created_at": "2026-10-08T06:30:00.000Z"
  },
  "request_id": "request-01",
  "replayed": false
}

Header Location berisi URL untuk membaca tagihan. Retry dengan key dan payload sama mengembalikan HTTP 200 dan replayed: true. Lihat aturan idempotensi.

Ambil tagihan

GET/api/v1/bills/{id}

Baca status terbaru dan metode pembayaran tagihan milik aplikasi Anda. Gunakan endpoint ini setelah pembuatan, saat menerima webhook, atau ketika perlu memastikan hasil transaksi.

idpath · UUIDWajib: Gunakan data.id dari respons pembuatan. Jangan gunakan billing_number atau external_reference.

Gunakan variabel BILL_ID pada contoh. Endpoint ini tidak memerlukan body atau Idempotency-Key.

Atur ID tagihan

export BILL_ID="<DATA_ID_DARI_RESPONS_PEMBUATAN>"

Tampilkan metode pembayaran yang aktif

payment_methods hanya berisi metode aktif dan belum kedaluwarsa. Untuk VA, gunakan display_value sebagai nomor pembayaran. Untuk QRIS, gunakan qr_content, qr_url, atau qr_image yang tersedia.

HTTP 404 berarti tagihan tidak ditemukan atau berada di luar akses aplikasi Anda. Daftar field respons ada pada objek tagihan.

Request ambil tagihan

curl -i -X GET "$BASE_URL/api/v1/bills/$BILL_ID" \
  -H "Authorization: Bearer $SIMPUL_API_KEY"

200 OK · metode pembayaran siap

{
  "data": {
    "id": "018f0f79-16ea-7ad0-a9dd-120a8c001001",
    "billing_number": "3512345678901234",
    "status": "unpaid",
    "amount_rupiah": "25000",
    "paid_rupiah": "0",
    "expires_at": "2026-10-09T06:30:00.000Z",
    "payment_methods": [
      {
        "type": "virtual_account",
        "provider": "bank_bjb",
        "display_value": "8881234567890123",
        "status": "active",
        "expires_at": "2026-10-09T06:30:00.000Z"
      }
    ],
    "created_at": "2026-10-08T06:30:00.000Z"
  },
  "request_id": "request-02"
}

Batalkan tagihan

POST/api/v1/bills/{id}/cancel

Batalkan tagihan sebelum proses penerbitan metode pembayaran dimulai, atau setelah penerbitan gagal secara pasti. SIMPUL PAD tetap menyimpan tagihan dan riwayat transaksi.

idpath · UUIDWajib: ID tagihan milik aplikasi Anda. Gunakan variabel BILL_ID seperti pada contoh GET.
reasonbody · stringWajib: Alasan pembatalan, 10–1.000 karakter. Alasan pertama yang diterima disimpan untuk audit. Body hanya menerima field reason.

Gunakan Authorization dan Content-Type: application/json. Pembatalan tidak memerlukan Idempotency-Key. Pengulangan pembatalan yang sudah berhasil mengembalikan HTTP 200 dengan replayed: true.

Pembatalan dapat ditolak dengan 409

Tagihan dengan pembayaran tercatat, penerbitan yang sedang berjalan, VA atau QRIS yang sudah terbit, atau kebutuhan rekonsiliasi tidak dapat langsung dibatalkan. Periksa kode error dan status tagihan sebelum mengambil tindakan.

Request batalkan tagihan

curl -i -X POST "$BASE_URL/api/v1/bills/$BILL_ID/cancel" \
  -H "Authorization: Bearer $SIMPUL_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{ "reason": "Invoice dibatalkan oleh sistem sumber." }
JSON

200 OK · pembatalan berhasil

{
  "data": {
    "id": "018f0f79-16ea-7ad0-a9dd-120a8c001001",
    "billing_number": "3512345678901234",
    "status": "cancelled",
    "amount_rupiah": "25000",
    "paid_rupiah": "0",
    "expires_at": "2026-10-09T06:30:00.000Z",
    "payment_methods": [],
    "created_at": "2026-10-08T06:30:00.000Z"
  },
  "request_id": "request-03",
  "replayed": false
}

Objek tagihan

Respons sukses berisi data, yaitu objek tagihan di bawah, dan request_id untuk pelacakan. Pembuatan dan pembatalan juga menyertakan replayed. Respons GET tidak menyertakan field tersebut.

idstring · UUID: ID tagihan untuk endpoint GET dan pembatalan. Simpan di sistem Anda.
billing_numberstring: Nomor tagihan SIMPUL PAD. Berbeda dari nomor virtual account untuk pembayaran.
statusstring: Status tagihan saat dibaca. Lihat daftar status untuk menentukan tindakan aplikasi.
amount_rupiahstring: Nominal tagihan dalam rupiah bulat.
paid_rupiahstring: Total pembayaran yang sudah tercatat dalam rupiah bulat.
expires_atstring · UTC: Waktu kedaluwarsa tagihan.
payment_methodsarray: Metode pembayaran aktif dan belum kedaluwarsa. Dapat kosong selama penerbitan. Ambil nomor VA dari display_value, bukan billing_number.
created_atstring · UTC: Waktu tagihan dibuat.

Objek dalam payment_methods

typestring: virtual_account atau qris.
providerstring: Penyedia pembayaran, misalnya bank_bjb.
display_valuestring: Nilai untuk instruksi pembayaran. Untuk VA, nilai ini adalah nomor virtual account.
statusstring: active. Respons GET hanya menampilkan metode yang aktif.
expires_atstring · UTC: Batas waktu metode pembayaran. Metode yang kedaluwarsa tidak ditampilkan pada GET.
qr_content / qr_url / qr_imagestring | null · QRIS: Data QRIS dari bank. Field ini hanya disertakan untuk QRIS dan dapat bernilai null. Gunakan data yang tersedia untuk menampilkan QR pembayaran.

Status tagihan

Baca status dari respons GET untuk menentukan tindakan aplikasi. Webhook memberi tahu perubahan, lalu GET membantu memastikan keadaan terbaru jika event diterima berulang atau terlambat.

Status	Arti	Tindakan aplikasi
`draft`	Tagihan belum masuk proses penerbitan.	Tagihan baru dari API dimulai pada status issuing.
`issuing`	Metode pembayaran sedang diterbitkan.	Tunggu webhook atau baca kembali dengan GET. Jangan tandai lunas.
`unpaid`	Metode pembayaran siap, belum ada pembayaran.	Tampilkan metode pembayaran aktif dari respons GET.
`partially_paid`	Sebagian nominal sudah dibayar.	Gunakan paid_rupiah untuk menampilkan jumlah yang sudah tercatat.
`paid`	Pembayaran penuh sudah tercatat.	Tandai invoice lunas setelah verifikasi webhook atau pembacaan GET.
`expired`	Batas waktu tagihan sudah lewat.	Hentikan penawaran pembayaran untuk tagihan ini.
`cancelled`	Tagihan dibatalkan.	Hentikan pembayaran, simpan riwayat invoice.
`failed`	Penerbitan metode pembayaran gagal.	Periksa tagihan dan hubungi operator sebelum membuat pengganti.
`needs_reconciliation`	Hasil transaksi memerlukan pemeriksaan operator.	Tahan perubahan status akhir dan hubungi operator. Jangan membuat tagihan pengganti otomatis.

Pembayaran sebagian yang melewati batas waktu dapat menghasilkan needs_reconciliation. Gunakan status dari API, jangan menghitung status akhir hanya dari waktu kedaluwarsa.

Idempotensi dan retry

Gunakan satu Idempotency-Key stabil untuk satu invoice. Key berlaku dalam aplikasi Anda. SIMPUL PAD membandingkan isi request untuk mencegah tagihan ganda saat koneksi terputus atau request diulang.

Key baru dan payload valid menghasilkan tagihan baru, HTTP 202, dan replayed: false.
Key dan payload yang sama mengembalikan tagihan yang sama, HTTP 200, dan replayed: true.
Key yang sama dengan payload berbeda menghasilkan HTTP 409 IDEMPOTENCY_CONFLICT.

Simpan payload sebelum request pertama

Simpan service_id, identitas payer, nominal, metode pembayaran, external_reference, dan expires_at bersama key. Jangan menghitung ulang expires_at atau mengganti key ketika terjadi timeout. Payload yang berubah bukan retry yang sama.

Saat timeout, koneksi terputus, atau HTTP 503, coba kembali dengan key dan payload asli. Gunakan jeda yang bertambah antarpercobaan dan batasi jumlah percobaan di aplikasi Anda. Jika respons sudah berisi data.id, baca tagihan dengan GET.

Untuk HTTP 400, 401, 404, 409, 413, 415, dan 422, periksa kode error sebelum mengulang request.

Retry pembuatan tetap melalui validasi waktu kedaluwarsa. Jika expires_at tidak lagi memenuhi batas minimal 5 menit ke depan, gunakan GET dengan ID tagihan yang tersimpan. Jika ID belum diketahui, hubungi operator untuk memeriksa hasil request sebelum membuat tagihan pengganti.

Webhook

Daftarkan URL HTTPS backend Anda pada detail aplikasi di portal pengembang. Simpan signing secret yang ditampilkan sekali. Endpoint harus berhasil menerima event verifikasi sebelum menerima event pembayaran.

Header pengiriman

X-Simpul-Deliverystring: ID delivery. Simpan untuk mencegah pemrosesan ulang pada retry pengiriman.
X-Simpul-Eventstring: Jenis event, misalnya bill.payment_method_ready atau payment.paid.
X-Simpul-Timestampepoch detik: Waktu penandatanganan. Periksa selisih terhadap waktu server Anda. Contoh verifikasi menggunakan toleransi 5 menit.
X-Simpul-Signaturestring: v1= diikuti digest HMAC-SHA256 heksadesimal. Pesan yang ditandatangani adalah timestamp + titik + body mentah. Gunakan signing secret sebagai key HMAC.

Urutan penerimaan

Baca body asli. Verifikasi timestamp dan signature sebelum JSON.parse(). Bandingkan signature dengan perbandingan waktu konstan.
Setelah valid, baca event. Simpan delivery ID dan id event untuk menghindari efek ganda, termasuk saat replay manual.
Simpan event atau masukkan ke antrean pemrosesan secara persisten, lalu kembalikan HTTP 2xx. Jika event sudah diproses, tetap kembalikan 2xx.
Untuk perubahan pembayaran, gunakan data.bill_id dan baca tagihan dengan GET sebelum menyelaraskan status invoice.

Verifikasi signature · Node.js

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

// rawBody harus berupa body asli, sebelum JSON.parse().
// headers adalah objek Headers dari request webhook.
export function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers.get("X-Simpul-Timestamp");
  const signature = headers.get("X-Simpul-Signature");
  if (!secret || !timestamp || !/^\d+$/.test(timestamp)) return false;
  if (!signature || !/^v1=[a-f0-9]{64}$/i.test(signature)) return false;

  const seconds = Number(timestamp);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isSafeInteger(seconds) || Math.abs(now - seconds) > 300) {
    return false;
  }

  const expected = createHmac("sha256", secret)
    .update(`${seconds}.${rawBody}`, "utf8")
    .digest();
  const received = Buffer.from(signature.slice(3), "hex");
  return received.length === expected.length &&
    timingSafeEqual(received, expected);
}

Contoh event metode pembayaran siap

{
  "id": "bill_018f0f79-16ea-7ad0-a9dd-120a8c001001_unpaid",
  "type": "bill.payment_method_ready",
  "created_at": "2026-10-08T06:31:00.000Z",
  "data": {
    "bill_id": "018f0f79-16ea-7ad0-a9dd-120a8c001001",
    "billing_number": "3512345678901234",
    "status": "unpaid",
    "expires_at": "2026-10-09T06:30:00.000Z",
    "payment_methods": [
      {
        "type": "virtual_account",
        "provider": "bank_bjb",
        "display_value": "8881234567890123",
        "expires_at": "2026-10-09T06:30:00.000Z"
      }
    ]
  }
}

Bentuk data mengikuti jenis event. Contoh ini adalah bill.payment_method_ready. Fungsi di atas hanya memverifikasi signature. Tambahkan penyimpanan event dan deduplikasi pada handler Anda.

Jenis event

webhook.endpoint_verification: Permintaan verifikasi endpoint. Kembalikan 2xx setelah signature valid agar endpoint dapat menerima event berikutnya.
bill.payment_method_ready: Metode pembayaran VA atau QRIS berhasil diterbitkan. Ambil tagihan dengan GET untuk membaca metode yang masih aktif.
bill.failed: Penerbitan metode pembayaran gagal.
bill.needs_reconciliation: Hasil penerbitan memerlukan pemeriksaan operator.
bill.expired: Tagihan mencapai batas waktu pembayaran.
payment.partially_paid: Pembayaran sebagian sudah tercatat.
payment.paid: Pembayaran penuh sudah tercatat.

Retry pengiriman

Respons 2xx menandai delivery berhasil. Gangguan jaringan, HTTP 408, 425, 429, dan 5xx dapat dicoba kembali sampai total 12 percobaan dengan jeda yang bertambah. Jeda dimulai sekitar 15 detik dan dibatasi 6 jam. Respons lain dianggap gagal permanen. Periksa riwayat delivery di portal pengembang untuk pengiriman yang gagal dan replay setelah masalah diperbaiki.

Error dan troubleshooting

Respons error memiliki error.code, error.message, dan request_id. Field error.field disertakan bila error terkait field tertentu. Gunakan kode error untuk logika aplikasi, lalu gunakan pesan untuk penelusuran.

Simpan status HTTP, kode error, ID tagihan, dan request_id saat menghubungi operator BAPENDA. Hindari menyertakan API key, signing secret, atau data pribadi wajib retribusi dalam log.

400 Bad Request · waktu kedaluwarsa tidak valid

{
  "error": {
    "code": "INVALID_BILL_REQUEST",
    "message": "expires_at must be between five minutes and 366 days in the future.",
    "field": "expires_at"
  },
  "request_id": "request-04"
}

HTTP	Kode error	Cara menangani
400	`INVALID_BILL_REQUEST / INVALID_JSON / INVALID_BILL_ID / INVALID_CANCELLATION_REQUEST`	Perbaiki JSON, field yang disebut pada error.field, UUID, atau alasan pembatalan. Field yang tidak dikenal juga ditolak.
401	`INVALID_API_CREDENTIAL`	Periksa Bearer key. Pastikan aplikasi disetujui dan key aktif, belum kedaluwarsa, serta belum dicabut.
404	`BILL_NOT_FOUND / RETRIBUTION_SERVICE_NOT_FOUND`	Periksa ID dan akses aplikasi ke tagihan atau layanan. Tagihan aplikasi lain tidak dapat dibaca.
409	`IDEMPOTENCY_CONFLICT`	Key sudah dipakai dengan payload berbeda. Gunakan kembali payload asli, atau key baru untuk invoice baru.
409	`PAYMENT_ALREADY_RECORDED / PROVIDER_CANCELLATION_UNAVAILABLE / PROVIDER_OUTCOME_PENDING / RECONCILIATION_REQUIRED / BILL_NOT_CANCELLABLE`	Pembatalan ditolak. Baca status tagihan dan hubungi operator jika perlu pemeriksaan transaksi.
413	`BODY_TOO_LARGE`	Kurangi ukuran body. Batas body JSON adalah 64 KiB.
415	`UNSUPPORTED_MEDIA_TYPE`	Kirim Content-Type: application/json pada request POST.
422	`AMOUNT_OUTSIDE_TARIFF`	Sesuaikan amount_rupiah dengan tarif atau batas nominal layanan.
503	`BILLING_UNAVAILABLE / TARIFF_CONFIGURATION_UNAVAILABLE`	Coba kembali dengan jeda bertambah. Untuk pembuatan, gunakan key dan payload asli. Hubungi operator jika berulang.

Ruang lingkup API pengembang

Panduan ini mencakup pembuatan, pembacaan, dan pembatalan tagihan serta webhook. Callback bank, refund, reversal, dan endpoint administratif mengikuti kewenangan internal dan tidak tersedia sebagai API pengembang.

Kembali ke awal dokumentasi Kelola aplikasi pengembang

Dokumentasi API

Buat tagihan retribusi dan ikuti status pembayarannya dari backend aplikasi Anda. Panduan ini menjelaskan request, respons, dan langkah penanganan untuk API SIMPUL PAD Kabupaten Garut.

Akses memerlukan persetujuan BAPENDA

Aplikasi, layanan retribusi, dan ruang lingkup akses harus disetujui sebelum API key dapat digunakan. Simpan API key dan signing secret webhook di backend Anda.

# Jalankan di terminal backend dengan shell Bash. export BASE_URL="https://simpul-pad.bapenda.garutkab.go.id" export SIMPUL_API_KEY="<API_KEY_APLIKASI_ANDA>" export SERVICE_ID="<UUID_LAYANAN_YANG_DISETUJUI>" export IDEMPOTENCY_KEY="invoice-2026-00000001" # Gunakan Node.js untuk membuat waktu kedaluwarsa 24 jam ke depan. # Jalankan sekali, lalu simpan nilainya untuk request dan retry. export EXPIRES_AT="$(node -e 'process.stdout.write(new Date(Date.now() + 86400000).toISOString())')"

curl -i -X POST "$BASE_URL/api/v1/bills" \ -H "Authorization: Bearer $SIMPUL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ --data @- <<JSON { "service_id": "$SERVICE_ID", "external_reference": "invoice/2026/001", "payer": { "name": "Wajib Retribusi", "address": "Garut" }, "amount_rupiah": "25000", "payment_method": "virtual_account", "expires_at": "$EXPIRES_AT" } JSON

{ "data": { "id": "018f0f79-16ea-7ad0-a9dd-120a8c001001", "billing_number": "3512345678901234", "status": "issuing", "amount_rupiah": "25000", "paid_rupiah": "0", "expires_at": "2026-10-09T06:30:00.000Z", "payment_methods": [], "created_at": "2026-10-08T06:30:00.000Z" }, "request_id": "request-01", "replayed": false }

{ "data": { "id": "018f0f79-16ea-7ad0-a9dd-120a8c001001", "billing_number": "3512345678901234", "status": "unpaid", "amount_rupiah": "25000", "paid_rupiah": "0", "expires_at": "2026-10-09T06:30:00.000Z", "payment_methods": [ { "type": "virtual_account", "provider": "bank_bjb", "display_value": "8881234567890123", "status": "active", "expires_at": "2026-10-09T06:30:00.000Z" } ], "created_at": "2026-10-08T06:30:00.000Z" }, "request_id": "request-02" }

curl -i -X POST "$BASE_URL/api/v1/bills/$BILL_ID/cancel" \ -H "Authorization: Bearer $SIMPUL_API_KEY" \ -H "Content-Type: application/json" \ --data @- <<JSON { "reason": "Invoice dibatalkan oleh sistem sumber." } JSON

{ "data": { "id": "018f0f79-16ea-7ad0-a9dd-120a8c001001", "billing_number": "3512345678901234", "status": "cancelled", "amount_rupiah": "25000", "paid_rupiah": "0", "expires_at": "2026-10-09T06:30:00.000Z", "payment_methods": [], "created_at": "2026-10-08T06:30:00.000Z" }, "request_id": "request-03", "replayed": false }

Status

Arti

Tindakan aplikasi

draft

Tagihan belum masuk proses penerbitan.

Tagihan baru dari API dimulai pada status issuing.

issuing

Metode pembayaran sedang diterbitkan.

Tunggu webhook atau baca kembali dengan GET. Jangan tandai lunas.

unpaid

Metode pembayaran siap, belum ada pembayaran.

Tampilkan metode pembayaran aktif dari respons GET.

partially_paid

Sebagian nominal sudah dibayar.

Gunakan paid_rupiah untuk menampilkan jumlah yang sudah tercatat.

paid

Pembayaran penuh sudah tercatat.

Tandai invoice lunas setelah verifikasi webhook atau pembacaan GET.

expired

Batas waktu tagihan sudah lewat.

Hentikan penawaran pembayaran untuk tagihan ini.

cancelled

Tagihan dibatalkan.

Hentikan pembayaran, simpan riwayat invoice.

failed

Penerbitan metode pembayaran gagal.

Periksa tagihan dan hubungi operator sebelum membuat pengganti.

needs_reconciliation

Hasil transaksi memerlukan pemeriksaan operator.

Tahan perubahan status akhir dan hubungi operator. Jangan membuat tagihan pengganti otomatis.

import { createHmac, timingSafeEqual } from "node:crypto"; // rawBody harus berupa body asli, sebelum JSON.parse(). // headers adalah objek Headers dari request webhook. export function verifyWebhook(rawBody, headers, secret) { const timestamp = headers.get("X-Simpul-Timestamp"); const signature = headers.get("X-Simpul-Signature"); if (!secret || !timestamp || !/^\d+$/.test(timestamp)) return false; if (!signature || !/^v1=[a-f0-9]{64}$/i.test(signature)) return false; const seconds = Number(timestamp); const now = Math.floor(Date.now() / 1000); if (!Number.isSafeInteger(seconds) || Math.abs(now - seconds) > 300) { return false; } const expected = createHmac("sha256", secret) .update(`${seconds}.${rawBody}`, "utf8") .digest(); const received = Buffer.from(signature.slice(3), "hex"); return received.length === expected.length && timingSafeEqual(received, expected); }

{ "id": "bill_018f0f79-16ea-7ad0-a9dd-120a8c001001_unpaid", "type": "bill.payment_method_ready", "created_at": "2026-10-08T06:31:00.000Z", "data": { "bill_id": "018f0f79-16ea-7ad0-a9dd-120a8c001001", "billing_number": "3512345678901234", "status": "unpaid", "expires_at": "2026-10-09T06:30:00.000Z", "payment_methods": [ { "type": "virtual_account", "provider": "bank_bjb", "display_value": "8881234567890123", "expires_at": "2026-10-09T06:30:00.000Z" } ] } }

HTTP

Kode error

Cara menangani

400

INVALID_BILL_REQUEST / INVALID_JSON / INVALID_BILL_ID / INVALID_CANCELLATION_REQUEST

Perbaiki JSON, field yang disebut pada error.field, UUID, atau alasan pembatalan. Field yang tidak dikenal juga ditolak.

401

INVALID_API_CREDENTIAL

Periksa Bearer key. Pastikan aplikasi disetujui dan key aktif, belum kedaluwarsa, serta belum dicabut.

404

BILL_NOT_FOUND / RETRIBUTION_SERVICE_NOT_FOUND

Periksa ID dan akses aplikasi ke tagihan atau layanan. Tagihan aplikasi lain tidak dapat dibaca.

409

IDEMPOTENCY_CONFLICT

Key sudah dipakai dengan payload berbeda. Gunakan kembali payload asli, atau key baru untuk invoice baru.

409

PAYMENT_ALREADY_RECORDED / PROVIDER_CANCELLATION_UNAVAILABLE / PROVIDER_OUTCOME_PENDING / RECONCILIATION_REQUIRED / BILL_NOT_CANCELLABLE

Pembatalan ditolak. Baca status tagihan dan hubungi operator jika perlu pemeriksaan transaksi.

413

BODY_TOO_LARGE

Kurangi ukuran body. Batas body JSON adalah 64 KiB.

415

UNSUPPORTED_MEDIA_TYPE

Kirim Content-Type: application/json pada request POST.

422

AMOUNT_OUTSIDE_TARIFF

Sesuaikan amount_rupiah dengan tarif atau batas nominal layanan.

503

BILLING_UNAVAILABLE / TARIFF_CONFIGURATION_UNAVAILABLE

Coba kembali dengan jeda bertambah. Untuk pembuatan, gunakan key dan payload asli. Hubungi operator jika berulang.

Dokumentasi API

Mulai cepat

Siapkan kredensial

Atur variabel backend

Kirim request pembuatan

Baca hasil dan ikuti pembayaran

Autentikasi

Format data

Alur satu tagihan

Buat tagihan

Body request

Field di dalam payer

Ambil tagihan

Batalkan tagihan

Objek tagihan

Objek dalam payment_methods

Status tagihan

Idempotensi dan retry

Webhook

Header pengiriman

Urutan penerimaan

Jenis event

Retry pengiriman

Error dan troubleshooting

Dokumentasi API

Mulai cepat

Siapkan kredensial

Atur variabel backend

Kirim request pembuatan

Baca hasil dan ikuti pembayaran

Autentikasi

Format data

Alur satu tagihan

Buat tagihan

Body request

Field di dalam payer

Ambil tagihan

Batalkan tagihan

Objek tagihan

Objek dalam payment_methods

Status tagihan

Idempotensi dan retry

Webhook

Header pengiriman

Urutan penerimaan

Jenis event

Retry pengiriman

Error dan troubleshooting