Skip to main content
Handle provides a unified, provider-abstracted Bill Payment & Value-Added Services (VAS) engine. Instead of integrating separate protocols for each utility, telecom, and biller aggregator, developers integrate once with Handle’s REST API.

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:
  1. Debits the customer’s linked bank account via active Direct Debit mandate.
  2. Dispatches fulfillment to the primary provider.
  3. Triggers margin-guarded failover if the primary provider is unreachable.
  4. 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:
  1. Handle’s VasOrchestratorService intercepts the error within 3 seconds.
  2. It evaluates configured backup routes in ProviderRoutingConfig.
  3. If cost difference is within maxMarginTolerancePercent, the transaction is seamlessly fulfilled by the backup provider.
  4. The user receives a successful receipt without duplicate debits or manual intervention.