> ## 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.
# Purchase Airtime
> Purchase airtime for a phone number
## Overview
Purchase airtime for any Nigerian phone number on supported networks. The airtime will be credited instantly to the recipient's phone.
## Request Body
Send an array with one or more airtime purchases.
Amount of airtime to purchase in Naira.
Recipient phone number. Accepted formats: `08012345678` (11 digits), `2348012345678` (international), or `8012345678` (10 digits). All are normalized to the 11-digit local format.
Recipient network.
Product code from the airtime catalog.
Voucher code from the airtime catalog, when provided.
Operator value returned by the airtime catalog. Pass it back verbatim.
Region value returned by the airtime catalog (e.g. `NG`). Pass it back verbatim when provided.
## Response Fields
Reference to store for reconciliation and support.
Details of the accepted batch.
Confirmation that the request was accepted for processing.
One reference per item in the submitted batch. Store these to reconcile or requery individual purchases.
## Status Codes
| Code | Meaning |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `202` | Batch accepted for processing. Airtime is credited within a few seconds; use each reference in `data.references` to track individual items. |
| `400` | The request could not be processed. Common causes: invalid payload, empty body, unrecognised network, or amount outside the airtime catalog range. |
| `422` | Your organisation is not yet configured for vending, or an individual item in the batch could not be posted. |
| `429` | Another purchase for the same phone number and amount is already in progress. Retry after a short delay or with a different amount. |
| `503` | Airtime vending is temporarily unavailable across all providers. Retry after a short delay. |
## Supported Networks
* **MTN** - MTN Nigeria
* **AIRTEL** - Airtel Nigeria
* **GLOBACOM** - Glo Nigeria
* **9MOBILE** - 9mobile Nigeria
## Notes
* Airtime is credited instantly to the recipient's phone
* The minimum purchase amount is `₦100`; refer to the airtime catalog for network-specific limits.
* Maximum purchase amounts are returned by the airtime catalog
* Phone numbers are accepted as `080...`, `23480...`, or `80...` and normalized to the 11-digit local format; non-Nigerian mobile numbers are rejected before any charge
* Transaction processing may take a few seconds
* Store the `requestReference` returned by the API for reconciliation and support
## OpenAPI
````yaml POST /purchaseAirtime
openapi: 3.0.3
info:
title: Bleeprs API Specification 0.1
version: 1.0.0
contact: {}
servers:
- url: https://api.bleeprs.com/api
security:
- bearerAuth: []
paths:
/purchaseAirtime:
post:
tags:
- Vending
summary: Purchase Airtime
description: >-
Purchase airtime for one or more Nigerian phone numbers. Use product
details returned by the airtime catalog.
operationId: purchaseAirtime
requestBody:
content:
application/json:
schema:
type: array
items:
type: object
properties:
amount:
type: number
description: Amount of airtime to purchase (in Naira)
example: 50
phoneNumber:
type: string
description: >-
Recipient's phone number. Accepted as 08012345678,
2348012345678, or 8012345678 — normalized to the 11-digit
local format.
example: '08107176819'
network:
type: string
description: Network provider
enum:
- MTN
- AIRTEL
- GLOBACOM
- 9MOBILE
example: MTN
productCode:
type: string
description: Product code returned by the Airtime catalog
example: MTN_AIRTIME_PRODUCT_CODE
voucherCode:
type: string
description: >-
Voucher code returned by the Airtime catalog, when
provided
example: ''
operator:
type: string
description: Operator value returned by the Airtime catalog
example: MTN
region:
type: string
description: Region value returned by the Airtime catalog
example: NG
required:
- amount
- phoneNumber
- network
- productCode
minItems: 1
default:
- amount: 1000
phoneNumber: '08107176819'
network: MTN
productCode: MTN_AIRTIME_PRODUCT_CODE
responses:
'202':
description: >-
Batch accepted for processing. Airtime is credited within a few
seconds; use each reference in data.references to track individual
items.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '00'
gatewayMessage:
type: string
example: Successfully Processed
requestReference:
type: string
example: JJqI1HCxemtGpMOWOESU
data:
type: object
properties:
message:
type: string
example: Vending Request Sent
references:
type: array
items:
type: string
example:
- bpr_req_a1b2c3d4e5f6
'400':
description: >-
The request could not be processed. Common causes: invalid payload,
empty body, unrecognised network, or amount outside the airtime
catalog range.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '88'
gatewayMessage:
type: string
example: Unsucessfull
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: string
example: Amount out of range for MTN
'422':
description: >-
Your organisation is not yet configured for vending, or an
individual item in the batch could not be posted.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '88'
gatewayMessage:
type: string
example: Unsucessfull
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: string
example: Vending account not configured
'429':
description: >-
Another purchase for the same phone number and amount is already in
progress. Retry after a short delay or with a different amount.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '88'
gatewayMessage:
type: string
example: Unsucessfull
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: string
example: >-
Transaction in progress for this number and amount. Please
wait.
'503':
description: >-
Airtime vending is temporarily unavailable across all providers.
Retry after a short delay.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '88'
gatewayMessage:
type: string
example: Unsucessfull
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: string
example: >-
Airtime vending is temporarily unavailable across all
servers. Please try again later.
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````