> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendpadi.com/llms.txt > Use this file to discover all available pages before exploring further. # List billers > Discover VAS providers/plans, or eSIM destinations and packages. Pick a category; for eSIM use locationCode only when listing packages. Scope: `vas:read`. > [!NOTE] > > **What this endpoint is for:** catalog discovery before any VAS purchase. You do not buy here — you only fetch ids/codes to send on the write endpoints. > **Bill payments (airtime, data, cable, electricity, betting, internet)** > > Set `category` to the product (or `all`). Response is under `data.` (e.g. `data.betting.providers`, `data.data.plans`). Then call the matching **Purchase** endpoint with the provider/plan fields from this response. > **Data plans (`category=data`)** > > Response shape: `data.data.providers[]` + `data.data.plans[]`. > > For **Purchase data**, send `plans[].planId` (slug, e.g. `mtn_1gb_7d`) as `planId` — not the UUID in `plans[].id`. > > ```json theme={null} > { > "success": true, > "data": { > "data": { > "providers": [ > { > "id": "MTN", > "name": "MTN", > "displayName": "MTN Nigeria" > }, > { > "id": "AIRTEL", > "name": "AIRTEL", > "displayName": "Airtel Nigeria" > }, > { > "id": "GLO", > "name": "GLO", > "displayName": "Globacom Nigeria" > }, > { > "id": "NINE_MOBILE", > "name": "NINE_MOBILE", > "displayName": "9mobile Nigeria" > } > ], > "plans": [ > { > "id": "dd03df88-1bb6-4354-a2b9-2405fa657ffd", > "provider": "GLO", > "dataSize": "1.5GB", > "planId": "glo_1_5gb_1d", > "validity": "1 day", > "price": 345, > "isActive": true > }, > { > "id": "760aa80d-9e33-4d20-894d-dda0c1616109", > "provider": "MTN", > "dataSize": "1GB", > "planId": "mtn_1gb_7d", > "validity": "7 days", > "price": 500, > "isActive": true > }, > { > "id": "550e8400-e29b-41d4-a716-446655440004", > "provider": "AIRTEL", > "dataSize": "1GB", > "planId": "airtel_1gb_3d", > "validity": "3 days", > "price": 430, > "isActive": true, > "description": "Airtel 1GB data plan" > } > ] > } > } > } > ``` > **Electricity (`category=electricity`)** > > Response shape: `data.electricity.providers[]` + `data.electricity.plans[]`. > > Each plan has a slug `planId` (e.g. `ekedc_prepaid`) and `electricityType` (`PREPAID` | `POSTPAID`). > > For **Validate electricity** / **Pay electricity**, send `plans[].planId` — not `plans[].id` and not `providers.name`. > > ```json theme={null} > { > "success": true, > "data": { > "electricity": { > "providers": [ > { > "id": "550e8400-e29b-41d4-a716-446655440609", > "name": "EKEDC", > "displayName": "Ekedc" > }, > { > "id": "e8dd900e-fed0-4afe-b039-9079e0204ed6", > "name": "IKEDC", > "displayName": "Ikedc" > }, > { > "id": "a48cd509-c792-453d-87a5-2a5310d0b256", > "name": "EEDC", > "displayName": "Eedc" > } > ], > "plans": [ > { > "id": "810aac40-39c5-4579-92a0-13e155ed155e", > "provider": "EKEDC", > "planId": "ekedc_prepaid", > "electricityType": "PREPAID", > "isActive": true > }, > { > "id": "cc5d1edd-6a61-43e6-92a5-7ff9df7bf36c", > "provider": "EKEDC", > "planId": "ekedc_postpaid", > "electricityType": "POSTPAID", > "isActive": true > }, > { > "id": "7b80e370-45b6-41e7-8178-3ad1914250a7", > "provider": "IKEDC", > "planId": "ikedc_prepaid", > "electricityType": "PREPAID", > "isActive": true > } > ] > } > } > } > ``` > **eSIM destinations and packages** > > **1. 1. List destinations** > > `GET /api/v1/merchant/vas/billers?category=esim` (**omit** `locationCode`) → `data.esim.locations[]`. Find your country and copy its `locationCode`. > > ```json theme={null} > { > "success": true, > "data": { > "esim": { > "locations": [ > { > "id": "c60414cc-f392-4a6c-ab9b-5a28bd5e9f3b", > "locationName": "Nigeria", > "locationCode": "NG", > "countryFlagUrl": "https://static.redteago.com/img/flags/ng.png", > "isActive": true, > "sortOrder": 103 > }, > { > "id": "bb44d901-65f9-4033-9f8b-fd7ea4a8b25f", > "locationName": "Spain", > "locationCode": "ES", > "countryFlagUrl": "https://static.redteago.com/img/flags/es.png", > "isActive": true, > "sortOrder": 1 > } > ] > } > } > } > ``` > > **2. 2. List packages for that country** > > `GET /api/v1/merchant/vas/billers?category=esim&locationCode=NG` → `data.esim.packages[]` (full response in the playground sample below). Sort or filter by `price` to show your customers the options. > > **3. 3. Purchase** > > Send `packages[].id` (UUID) as `packageId` to **Purchase eSIM**. Do **not** send `packageCode` (e.g. `P0Q24KI1C`) as `packageId`. > > **Package fields** > > | Field | Description | > | - | - | > | `id` | Package UUID. Send this as `packageId` on Purchase eSIM. | > | `packageCode` | Provider reference, for display/support only. Not accepted as `packageId`. | > | `packageName` | Display name, e.g. `Nigeria 100MB 7Days`. | > | `dataSizeDisplay` | Data allowance, e.g. `100.00 MB`. Per-day plans show the daily allowance. | > | `validityDisplay` | Validity, e.g. `7 days`. | > | `price` | Your merchant price in **USD** (`currencyCode` is always `USD`). Your NGN wallet is debited the equivalent at the current rate on purchase. | > | `isActive` | Whether the package can be bought. | > > > [!NOTE] > > > > Use **country** codes. Regional codes in the destinations list (e.g. `EU-42`, `GL-139`) currently return an empty `packages` array. Multi-country bundles (Europe, Global, etc.) are currently listed under one country they cover — e.g. Europe bundles appear under `NO`. > [!NOTE] > > `locationCode` does nothing for non-eSIM categories. Playground sample below uses `category=esim&locationCode=NG` (packages). For data, call with `category=data`. ## OpenAPI ````yaml GET /api/v1/merchant/vas/billers openapi: 3.1.0 info: title: SendPadi Merchant API version: 1.0.0 description: >- Merchant REST API. Authenticate with HMAC headers (`X-Api-Key`, `X-Timestamp`, `X-Signature`). Generate playground headers with [Sign requests (playground)](/guides/sign-requests). servers: - url: https://api.sendpadi.com description: Production (test + live keys) security: [] paths: /api/v1/merchant/vas/billers: get: tags: - vas summary: List billers description: >- Discover VAS providers/plans, or eSIM destinations and packages. Pick a category; for eSIM use locationCode only when listing packages. **Scope:** `vas:read`. operationId: api-reference_vas_list-billers parameters: - name: X-Timestamp in: header required: true description: Unix time in seconds schema: type: string - name: X-Signature in: header required: true description: HMAC-SHA256 signature schema: type: string - name: category in: query required: false schema: type: string enum: - airtime - data - cable - electricity - betting - internet - esim - all description: >- Product to list. Use `esim` for travel eSIM destinations/packages; other values return that bill payment catalog. example: esim description: >- Product to list. Use `esim` for travel eSIM destinations/packages; other values return that bill payment catalog. - name: locationCode in: query required: false schema: type: string description: >- eSIM only: ISO country code from `data.esim.locations[].locationCode` (e.g. NG, US, ES). Omit to list destinations (`data.esim.locations`). Pass to list packages for that country (`data.esim.packages`). Case-insensitive. Ignored for non-eSIM categories. example: NG description: >- eSIM only: ISO country code from `data.esim.locations[].locationCode` (e.g. NG, US, ES). Omit to list destinations (`data.esim.locations`). Pass to list packages for that country (`data.esim.packages`). Case-insensitive. Ignored for non-eSIM categories. responses: '200': description: OK content: application/json: schema: type: object additionalProperties: true example: success: true data: esim: locationCode: NG currency: null location: id: c60414cc-f392-4a6c-ab9b-5a28bd5e9f3b locationName: Nigeria locationCode: NG countryFlagUrl: https://static.redteago.com/img/flags/ng.png isActive: true sortOrder: 103 packages: - id: 129285fd-553a-455e-a1f8-8f0d79d30aad packageCode: P0Q24KI1C packageName: Nigeria 100MB 7Days dataSizeDisplay: 100.00 MB validityDisplay: 7 days price: 0.7755 currencyCode: USD isActive: true - id: 8d4b1529-4aa6-4972-ac34-dee06033a562 packageCode: PESYLCUYL packageName: Nigeria 500MB/Day dataSizeDisplay: 500.00 MB validityDisplay: 1 day price: 2.739 currencyCode: USD isActive: true examples: success: summary: Success value: success: true data: esim: locationCode: NG currency: null location: id: c60414cc-f392-4a6c-ab9b-5a28bd5e9f3b locationName: Nigeria locationCode: NG countryFlagUrl: https://static.redteago.com/img/flags/ng.png isActive: true sortOrder: 103 packages: - id: 129285fd-553a-455e-a1f8-8f0d79d30aad packageCode: P0Q24KI1C packageName: Nigeria 100MB 7Days dataSizeDisplay: 100.00 MB validityDisplay: 7 days price: 0.7755 currencyCode: USD isActive: true - id: 8d4b1529-4aa6-4972-ac34-dee06033a562 packageCode: PESYLCUYL packageName: Nigeria 500MB/Day dataSizeDisplay: 500.00 MB validityDisplay: 1 day price: 2.739 currencyCode: USD isActive: true security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: API key id (sp_test_… / sp_live_…) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.