Core Architectural Pillars
1. Zero-Latency Catalog & Canonical Keys
Handle indexes all supported billers and packages into normalized Canonical Keys stored in PostgreSQL.2. The 3-Step Lifecycle
1
1. Query Catalog
Query
GET /api/v1/bill-payment/catalog with a category filter (e.g. category=ELECTRICITY). Returns all packages, face values, and provider codes instantly from PostgreSQL.2
2. Validate Customer Identifier
Call
POST /api/v1/bill-payment/validate-customer with the customer’s meter number, smartcard IUC, or student matric number. Handle verifies identity and current arrears against upstream servers.3
3. Purchase & Vend
Call
POST /api/v1/bill-payment/purchase. Handle automatically:- Debits the customer’s linked bank account via active Direct Debit mandate.
- Dispatches fulfillment to the primary provider.
- Triggers margin-guarded failover if the primary provider is unreachable.
- Delivers the generated electricity token, data top-up, or receipt.
3. Margin-Guarded Failover Engine
If Remita or Kuda experiences downstream timeouts or infrastructure downtime:- Handle’s
VasOrchestratorServiceintercepts the error within 3 seconds. - It evaluates configured backup routes in
ProviderRoutingConfig. - If cost difference is within
maxMarginTolerancePercent, the transaction is seamlessly fulfilled by the backup provider. - The user receives a successful receipt without duplicate debits or manual intervention.