Skip to main content

​
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

Airtime Vending

  • Purchase airtime for all major Nigerian networks
  • Real-time airtime top-up
  • Instant delivery to recipient phone numbers

Data Vending

  • Purchase data bundles for all major Nigerian networks
  • Various data plans with different validity periods
  • Flexible data amounts and durations

Electricity Vending

  • Purchase electricity tokens for all DisCos
  • Pre-validate meter details before purchase
  • Receive 20-digit recharge tokens instantly

Cable TV Vending

  • Subscribe to DSTV, GOTV, and Startimes
  • Validate smartcards before transaction
  • Instant subscription activation

​
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 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

Telecoms

MTN, Airtel, Globacom (Glo), 9mobile

Electricity DisCos

Ikeja Electric, Eko Electric, Abuja Electric, and more

Cable TV

DSTV, GOTV, Startimes

​
Getting Started

1

List Available Providers

Get the supported airtime networks, electricity DisCos, cable TV providers, and available product codes.
2

Purchase Airtime

Buy airtime for any phone number on a supported network.
3

List Data Plans

Browse available data bundles. You can filter by network.
4

Purchase Data

Buy data bundles using a product code from the data catalog.
5

Validate Meter or Smartcard

Verify electricity meter or cable TV smartcard details before payment.
6

Purchase Utilities

Pay for electricity or cable TV using validated customer details and catalog product codes.
7

View Statistics

Monitor your vending performance and account balance
8

Check Logs

Review transaction history and status across airtime, data, electricity, and cable TV.
9

Requery Transaction

Confirm the final status of a pending airtime, data, electricity, or cable TV purchase.

​
Authentication

All vending endpoints require authentication using your API key. Include your API key in the Authorization header.

​
Base URL

All vending endpoints are available at the following base URL:

​
Response Format

All vending endpoints return responses in a consistent JSON envelope:
  • 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.

​
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, paste the reference into orderId, and send.