API v1 · tahap pengembangan

Integrasikan pembayaran Retribusi tanpa kehilangan jejak transaksi

API ini digunakan oleh aplikasi Retribusi yang identitas, layanan, dan ruang lingkupnya telah disetujui BAPENDA Kabupaten Garut.

Buka OpenAPI 3.1 JSON Ajukan akses integrasi

API key berscope

Kunci hanya berlaku untuk aplikasi dan layanan yang telah disetujui.

Idempoten

Key yang sama dan payload identik mengembalikan tagihan yang sama.

Nominal tervalidasi

Tarif tetap atau batas sistem authoritative diverifikasi di server.

Endpoint

Permukaan API yang tersedia

POST/api/v1/bills

Reservasi tagihan dan mulai penerbitan metode pembayaran.

GET/api/v1/bills/{id}

Baca status kanonik dan metode pembayaran yang aman ditampilkan.

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

Batalkan sebelum penerbitan VA dimulai; VA yang sudah terbit ditolak sampai kontrak disable bank tersedia.

Membuat tagihan

Simpan API key hanya di backend. Nominal Rupiah wajib berupa digit string.

curl -X POST "$BASE_URL/api/v1/bills" \
  -H "Authorization: Bearer $SIMPUL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-00000001" \
  -d '{
    "service_id": "123e4567-e89b-42d3-a456-426614174000",
    "external_reference": "invoice/2026/001",
    "payer": { "name": "Wajib Retribusi", "address": "Garut" },
    "amount_rupiah": "25000",
    "expires_at": "2026-08-03T00:00:00.000Z"
  }'

Respons asynchronous

HTTP 202 berarti tersimpan dan sedang menerbitkan metode pembayaran, bukan sudah dibayar.

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

Aturan idempotensi

Gunakan satu key stabil untuk satu invoice pada sistem sumber.

Replay identik aman dan mengembalikan resource yang sama.

Payload berbeda dengan key yang sama menghasilkan HTTP 409.

Verifikasi webhook

Verifikasi signature terhadap body mentah sebelum JSON diparse, lalu deduplikasi delivery ID.

X-Simpul-DeliveryID delivery unikX-Simpul-EventJenis event, termasuk webhook.endpoint_verificationX-Simpul-TimestampEpoch detikX-Simpul-Signaturev1=HMAC_SHA256(secret, timestamp.rawBody)

Signing secret ditampilkan sekali saat endpoint didaftarkan. Simpan hanya di backend, verifikasi body mentah dan timestamp, deduplikasi delivery ID, lalu kembalikan 2xx. Endpoint tidak menerima event pembayaran sampai event verifikasi berhasil.

bill.payment_method_ready: VA berhasil diterbitkan dan tagihan siap dibayar.
bill.failed: Penerbitan metode pembayaran gagal secara pasti.
bill.needs_reconciliation: Outcome penerbitan tidak dapat dibuktikan dengan aman.
bill.expired: Tagihan mencapai batas waktu tanpa pembayaran penuh.
payment.partially_paid: Pembayaran sebagian sudah masuk ke ledger.
payment.paid: Pembayaran penuh sudah masuk ke ledger.

Pembatalan tidak menghapus tagihan atau ledger. API bank-facing, callback, disable VA, reversal, refund, dan endpoint administratif tidak dipublikasikan sebagai API developer. Kontrak tersebut mengikuti hasil SIT dan kewenangan internal pemerintah daerah.