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

# Vending

> Purchase airtime, data bundles, electricity, and cable TV in Nigeria.

## Overview

The Vending API lets you sell airtime, data bundles, electricity tokens, and cable TV subscriptions from one API. The catalog endpoints return the currently supported products, prices, limits, and customer-facing product codes to use when purchasing.

## Supported Services

<CardGroup cols={2}>
  <Card title="Airtime Vending" icon="phone">
    * Purchase airtime for all major Nigerian networks
    * Real-time airtime top-up
    * Instant delivery to recipient phone numbers
  </Card>

  <Card title="Data Vending" icon="wifi">
    * Purchase data bundles for all major Nigerian networks
    * Various data plans with different validity periods
    * Flexible data amounts and durations
  </Card>

  <Card title="Electricity Vending" icon="bolt">
    * Purchase electricity tokens for all DisCos
    * Pre-validate meter details before purchase
    * Receive 20-digit recharge tokens instantly
  </Card>

  <Card title="Cable TV Vending" icon="tv">
    * Subscribe to DSTV, GOTV, and Startimes
    * Validate smartcards before transaction
    * Instant subscription activation
  </Card>
</CardGroup>

## Availability

Vending products are served from the active Bleeprs catalog. Always fetch the latest catalog before presenting product options to customers, because available plans, prices, and limits can change.

If a purchase cannot be completed immediately, the API may return a pending response with a `requestReference`. Store this reference and call the Requery Transaction endpoint to confirm the final status before retrying or refunding the customer.

## Transaction Lifecycle

Every vending purchase moves through the same three phases:

1. **Submit.** The purchase endpoint validates the request and debits your vending wallet. A `requestReference` is returned regardless of the final outcome — store it for every purchase.
2. **Process.** Airtime and data batches are queued and completed within a few seconds. Electricity and cable TV return a `200` with token or bouquet details once the provider confirms the purchase, or a `202` with `gatewayStatus: "01"` if the provider is still processing.
3. **Reconcile.** If the response was pending, wait at least **2 minutes** after the original purchase and call [Requery Transaction](/api-reference/endpoint/requeryvendingtransaction) with the `requestReference`. If a purchase ultimately fails, the debited amount is refunded to your wallet automatically.

Do not resubmit a purchase while it is still `PENDING` — use requery instead.

## Batch Purchases

`POST /purchaseAirtime` and `POST /purchaseData` both accept an **array** of items so you can submit multiple purchases in one request. The response includes a `references` array with one reference per item, in the same order as the request.

## Rate Limits & Concurrency

* A short rate limit is applied per API key across all vending endpoints. Space out requests to avoid `429` responses.
* Only one purchase can be in progress at a time for the same combination of target (phone number or meter) and amount. Duplicate submissions while the first is still processing receive a `429` — either wait for the first to complete or submit with a different amount.

## Supported Networks & Providers

<CardGroup cols={2}>
  <Card title="Telecoms" icon="signal">
    MTN, Airtel, Globacom (Glo), 9mobile
  </Card>

  <Card title="Electricity DisCos" icon="bolt">
    Ikeja Electric, Eko Electric, Abuja Electric, and more
  </Card>

  <Card title="Cable TV" icon="tv">
    DSTV, GOTV, Startimes
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="List Available Providers">
    Get the supported airtime networks, electricity DisCos, cable TV providers, and available product codes.

    ```bash theme={null}
    GET /AirtimeList
    GET /DataList
    GET /ElectricityList
    GET /CableTVList
    ```
  </Step>

  <Step title="Purchase Airtime">
    Buy airtime for any phone number on a supported network.

    ```bash theme={null}
    POST /purchaseAirtime
    ```
  </Step>

  <Step title="List Data Plans">
    Browse available data bundles. You can filter by network.

    ```bash theme={null}
    GET /DataList?network=MTN
    ```
  </Step>

  <Step title="Purchase Data">
    Buy data bundles using a product code from the data catalog.

    ```bash theme={null}
    POST /purchaseData
    ```
  </Step>

  <Step title="Validate Meter or Smartcard">
    Verify electricity meter or cable TV smartcard details before payment.

    ```bash theme={null}
    POST /validateMeter
    POST /validateSmartcard
    ```
  </Step>

  <Step title="Purchase Utilities">
    Pay for electricity or cable TV using validated customer details and catalog product codes.

    ```bash theme={null}
    POST /purchaseElectricity
    POST /purchaseCableTV
    ```
  </Step>

  <Step title="View Statistics">
    Monitor your vending performance and account balance

    ```bash theme={null}
    GET /statistics
    ```
  </Step>

  <Step title="Check Logs">
    Review transaction history and status across airtime, data, electricity, and cable TV.

    ```bash theme={null}
    GET /logEntries
    ```
  </Step>

  <Step title="Requery Transaction">
    Confirm the final status of a pending airtime, data, electricity, or cable TV purchase.

    ```bash theme={null}
    GET /requeryTransaction/{orderId}
    ```
  </Step>
</Steps>

## Authentication

<Warning>
  All vending endpoints require authentication using your API key. Include your API key in the `Authorization` header.
</Warning>

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Base URL

<Info>
  All vending endpoints are available at the following base URL:
</Info>

```bash theme={null}
https://api.bleeprs.com/api
```

## Response Format

<Info>
  All vending endpoints return responses in a consistent JSON envelope:
</Info>

```json theme={null}
{
  "gatewayStatus": "00",
  "gatewayMessage": "Successfully Processed",
  "requestReference": "bpr_req_a1b2c3d4e5f6",
  "data": { }
}
```

<AccordionGroup>
  <Accordion title="Response Fields">
    * **`gatewayStatus`**: `"00"` indicates success. Any other value indicates an error.
    * **`gatewayMessage`**: Human-readable status message.
    * **`requestReference`**: Unique identifier for the request. Use it to reconcile, requery, or contact support.
    * **`data`**: The response body. Can be an object, an array, or a string, depending on the endpoint — see each endpoint page for the exact shape.
  </Accordion>
</AccordionGroup>

## Testing in the Playground

Each endpoint page in this documentation has a live request panel. To test end-to-end:

1. Paste your API key into the `Authorization` header once — it is preserved across pages.
2. Send a purchase request and copy the `requestReference` from the response.
3. Open [Requery Transaction](/api-reference/endpoint/requeryvendingtransaction), paste the reference into `orderId`, and send.