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

# VAS & Collections Overview

> Architecture, authentication, and execution lifecycle for Value Added Services (VAS) and Remita Retrieval Reference (RRR) biller collections on Handle.

# Value Added Services & Biller Collections

Handle provides a unified, provider-abstracted Value Added Services (VAS) and Remita Retrieval Reference (RRR) Biller Collection platform. It enables merchants and client applications to vend utility tokens, purchase airtime/data, and collect government & biller payments directly.

```mermaid theme={null}
flowchart LR
    Client([Client / App]) --> Gateway[Handle VAS Engine]
    Gateway --> Discovery[1. Catalog & Providers Discovery]
    Gateway --> Validation[2. Meter / Account Validation]
    Gateway --> Execution[3. Transaction Execution]
    Gateway --> Requery[4. Requery & Token Retrieval]
    Execution --> Remita[SystemSpecs Connect Gateway]
```

***

## Environments & Base URLs

All requests require the `secretKey` header to authenticate.

| Environment | Base URL | Usage |
| :- | :- | :- |
| **Sandbox / Demo (UAT)** | `https://api-demo.systemspecsng.com/services/connect-gateway/api/v1` | Testing, meter validation, simulated vending |
| **Production (Live)** | `https://api-gateway.remita.net/api/v1` | Real money movement & live token generation |

### Authentication Header

```http theme={null}
secretKey: sk_test_l/pQgOLgziOTzb+7pcUXVH2iX1MlpROsePDkNi/g/QmMs2c8P0DPr1vUP7xESiGG
Content-Type: application/json
```

***

## 4-Step Transaction Lifecycle

**1. Discovery**

Call `GET /vending/categories`, `GET /vending/providers`, or `GET /vending/products` to fetch available billers, packages, and tariff structures.

**2. Validation (Required for Electricity & Cable TV)**

Call `POST /vending/validate` with the customer's meter or smartcard number and biller `productCode`. This verifies the customer's name, address, and account status before taking payment.

**3. Execution**

Call `POST /vending/transactions` with your unique `clientReference`, `productCode`, `amount`, and recipient details.

**4. Requery & Token Confirmation**

If the network times out or returns `PENDING` (`03`), call `GET /vending/query-transaction/{reference}` to retrieve the final status, 20-digit token, and units without double-charging.

***

## Status Codes Reference

| Status Code | Status Name | Meaning | Recommended Action |
| :- | :- | :- | :- |
| **`00`** | `SUCCESS` | Approved or completed successfully. | Token / Receipt generated. Complete user order. |
| **`03`** | `PENDING` | Transaction in progress with downstream provider. | Initiate polling on `GET /vending/query-transaction/{reference}`. |
| **`81`** | `INSUFFICIENT_FUNDS` | Gateway wallet balance is insufficient. | Top up master wallet balance. |
| **`99`** | `FAILED` | Transaction failed or invalid parameters. | Review validation parameters or prompt customer. |


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