Billing, Collection & Disbursement — Host-to-Host Integration

Purpose of Host-to-Host

Automate end-to-end premium billing, collection, and refund flows with banks and payment gateways.
Support auto-debit mandates, virtual accounts (VA), cards, e-wallets, and real-time disbursements.
Provide immediate payment status updates to PAS/CRM and generate receipts automatically.

Core Data Objects

Invoice: invoiceNo, policyNo, period, dueDate, amount, currency, method, status
Mandate: bank, account token, consent, start/end, limits
Payment Order: orderId, invoiceRef, channel (auto-debit/VA/card/wallet), OTP/3DS
Settlement: success/fail, fees, net amount, batchRef, bankRef
Refund: refundId, reason, amount, related order
Payout: beneficiary, bank, account, amount, purpose, schedule
Events: invoiceIssued, orderInitiated, paymentSuccess, paymentFailed, refundProcessed, payoutSettled

Example API Endpoints

POST /invoices
Create premium invoice (single or batch)

POST /mandates
Register auto-debit mandate with bank tokenization

POST /payments/initiate
Start payment (auto-debit/VA/card/wallet)

POST /payments/notify
Bank/PG callback for result and settlement refs

POST /refunds
Create refund; return refundId and status

POST /payouts/initiate
Create disbursement batch to beneficiaries

POST /payouts/notify
Bank callback per payout item

GET /recon/statement
Retrieve daily statement (CSV/JSON) for reconciliation

Sample Payment Initiation

POST /payments/initiate
{
  "invoiceNo":"INV-2025-008812",
  "method":"AUTO_DEBIT",
  "amount": 1250000,
  "currency":"IDR",
  "mandateId":"MDT-55621",
  "metadata":{"policyNo":"POL-2025-001122"}
}

Sample Bank Callback

POST /payments/notify
{
  "orderId":"ORD-99123",
  "status":"SUCCESS",
  "settlement":{"bankRef":"BK-884712","fee":2500,"net":1247500},
  "invoiceNo":"INV-2025-008812",
  "signature":"base64-jws-signature"
}

Reference Flows

Invoice to Auto-Debit

PAS creates invoice → /invoices
System initiates auto-debit → /payments/initiate
Bank posts /payments/notify → receipt issued; policy status updated

Virtual Account (VA)

Issue VA number & expiry to customer
Customer pays via ATM/mobile banking
Bank posts success via /payments/notify with bankRef

Refund & Chargeback

CSR triggers /refunds when overpayment/cancel
Gateway processes; status pushed to PAS
Reconciliation logs reversal in sub-ledger

Disbursement (Claims)

Claims creates payout batch → /payouts/initiate
Bank processes each item → /payouts/notify
Receipts & letters archived; BI updated

Daily Reconciliation

Pull /recon/statement; match invoices/orders
Post differences; investigate exceptions
Close day; export to GL/BI

Security & Controls

mTLS, OAuth2/JWT; IP allow-list; JWS signatures; idempotency keys.
Tokenization for PAN/account numbers; PCI & PII masking; signed URLs.
Maker-checker for refunds and payouts; per-role limits & approvals.
Replay protection and rate limiting for callbacks.

Monitoring & Audit

Reconciliation KPIs: success rate, pending, exceptions, aging.
Callback retry depth; unmatched transactions; fee variance.
Audit trail for invoices, orders, refunds, and payouts.

What You Get

OpenAPI + bank/gateway mapping sheets; sample payloads.
Reconciliation templates (CSV/JSON) and dashboards.
Receipt & letter templates (PDF) and webhooks examples.
Annual maintenance incl. change requests; on-prem or cloud.