Buy Bulk Airtime - PAYBETA API

Top up many phone numbers in one request. Send a JSON list of recipients; Paybeta checks the whole list, confirms your wallet covers it, then processes each number on its own — one failed number never holds up the rest.

Authentication

Every request is authenticated with your live API key in the P-API-KEY header. No transaction PIN is needed. See Authentication details.

How it works

Submit the list. Every recipient is validated up front; if any row is invalid the whole request is rejected with the row in the error key (e.g. recipients.3.phone_number) and nothing is queued.

The priced total (total_charge, after your API commission) must be covered by your wallet balance.

Each recipient is then processed in turn (a few seconds apart): priced with your API commission, debited from your wallet, sent to the network once, and reported to your webhook like any airtime purchase.

A recipient that can't be charged (e.g. balance ran out mid-way, network down) is marked failed and not debited. An unconfirmed network response stays pending until it is confirmed (delivered) or refunded (reversed).

The same phone number appearing twice in one request is topped up at least 5 minutes apart.

Rules

Up to 1,000 recipients per request; total of all amounts at least NGN100.

biller: mtn, glo, airtel or 9mobile (mtn_vtu etc. also accepted).

phone_number: 234 + 10 digits (e.g. 2348031234567); 08031234567 is also accepted.

amount: NGN50 – NGN20,000 per recipient; a phone number can receive at most NGN50,000 airtime per day.

reference (request): yours, required, 5-40 chars (letters, numbers, . _ -), unique per account.

recipients[].reference: optional, 5-60 chars, unique. Defaults to <reference>-<row> (e.g. PAYROLL-OCT-2). No reference may have been used for an earlier transaction.

Tracking a number

Each recipient is its own transaction: query it with POST /v2/transaction/query and the recipient's reference, or watch your webhook — data.reference is the recipient reference, plus batchReference, batchId and row.

Statuses

Batch: queued → processing → completed, or cancelled. Recipient: queued, processing, delivered, pending, failed (not charged), reversed (refunded), cancelled (skipped).

Response formats

Success Response
HTTP Status: 200 OK (or 201 Created)

Error Response

HTTP Status: 4xx

HTTP Status Codes

Code	Status	Trigger / Description
401	Unauthorized	Missing or invalid API key
404	Not Found	Requested resource not found
422	Unprocessable Entity	Validation failed or action not allowed in current state

Bulk Airtime

Authentication#

How it works#

Rules#

Tracking a number#

Statuses#

Response formats#

Error Response#

HTTP Status Codes#