> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handle.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle VAS Architecture & Integration Guide

> How Handle abstracts upstream VAS providers (Remita, Kuda, OnePipe) into a unified, high-availability bill payment API.

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

```mermaid theme={null}
graph TD
    Client["Client / Merchant App"] -->|1. Request with Canonical Key| HandleAPI["Handle Gateway (api.handle.ng)"]
    HandleAPI -->|2. Zero-Latency Cache| DB[("PostgreSQL Catalog")]
    HandleAPI -->|3. Verify Mandate & Debit| OnePipe["OnePipe Direct Debit"]
    HandleAPI -->|4. Primary Dispatch| Router{"Smart Routing & Failover"}
    Router -->|Priority 1| Remita["Remita SystemSpecs"]
    Router -->|Fallback 2| Kuda["Kuda VAS Engine"]
    Router -->|Fallback 3| OnePipeVAS["OnePipe VAS"]
```

***

## 1. Zero-Latency Catalog & Canonical Keys

Handle indexes all supported billers and packages into normalized **Canonical Keys** stored in PostgreSQL.

| VAS Category | Canonical Key Pattern | Example |
| :- | :- | :- |
| **Electricity** | `electricity:{billerCode}:{meterType}` | `electricity:aedc:prepaid` |
| **Data** | `data:{network}:{bundleCode}` | `data:mtn:daily_110mb` |
| **Airtime** | `airtime:{network}` | `airtime:glo` |
| **Cable TV** | `cable-tv:{provider}:{packageName}` | `cable-tv:dstv:compact_plus` |
| **Education** | `education:{billerCode}:{examType}` | `education:waec:pin` |

***

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.