Vend Airtime

How to vend Airtime using this API

Vend airtime via the parent account

POST /v2/bill/topup

Request body

amount · integer · required

Amount

phoneNumber · string · required

Phone number of the user who is to receive the value

network · string · required

Network (e.g. MTN, AIRTEL, GLO, 9MOBILE, etc)

merchantTxRef · string · required

Merchant Transaction Reference (a unique reference to identify this transaction on your system)

senderName · string · required

The name of the person to be attached to this transaction

Response body

code · string · required

Response code

description · string · required

Response description

data · object

Hide object

amount · string · required

Amount

meta · object

Show object

merchantTxRef · string

Merchant Transaction Reference

rrn · string

Retrieval Reference Number (RRN)

timeCreated · string · required

Date and Time of the transaction

type · string · required

The type of this transaction.

status · string · required

The status of this transaction

Request

curl --location 'https://api.nomba.com/v2/bill/topup' \
--header 'accountId: <accountId>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 100,
    "phoneNumber": "08123456788",
    "network": "MTN",
    "merchantTxRef": "REF-29-07-2026-12",
    "senderName": "John Doe"
}'

Success response (200)

{
    "code": "200",
    "description": "SUCCESS",
    "message": "Transaction completed Successfully",
    "status": true,
    "data": {
        "id": "API-TOPUP-A6950-8c060b7c-4155-4e33-a846-101b49229c33",
        "status": "SUCCESS",
        "type": "topup",
        "amount": 100.0,
        "source": "api",
        "sourceUserId": null,
        "customerBillerId": "08123456788",
        "productId": "62130",
        "meta": {
            "api_rrn": "260926204701",
            "rrn": "260926204701",
            "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f",
            "api_client_id": "2167288-d989-460a-bbde-9842f2b4320f",
            "user_id": "0167288-d989-460a-bbde-9842f2b4320f",
            "merchantTxRef": "REF-29-07-2026-12",
            "allowDuplicate": true,
            "sender_name": "John Doe",
            "idempotentKey": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12",
            "pos_withdrawal_id": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12",
            "userName": "John Doe",
            "isCorporate": "true",
            "currency": "NGN",
            "hooksEligible": "true",
            "isSubscribedToSavingsService": false,
            "isSubscribedToLoanService": false,
            "txnAlertEligible": true,
            "banking_entity_id": 189585760,
            "banking_entity_user_id": 188595905,
            "banking_entity_type": "CORPORATE",
            "transactionCategory": "Bills & Utility",
            "network": "mtn",
            "subscriberNumber": "08123456788",
            "amount_charged": "100.0",
            "wallet_balance": "610.55",
            "wallet_currency": "NGN",
            "phoneNumber": "08123456788"
        },
        "userId": null,
        "timeCreated": "2026-09-26T19:47:01.514+00:00"
    }
}