Purchase Airtime

Use this endpoint to purchase airtime for a mobile phone number.

Before making an airtime purchase, the user's billing wallet must be mapped for utility transactions.

Endpoint

POST {{base_url}}/api/v1/utility/transactions/airtime

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer authentication token.
`x-merchant-ref`	string	Yes	Your unique merchant reference.
`Content-Type`	string	Yes	Must be `application/json`.

Authorization

Include your access token using the Bearer authentication scheme:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body

{
  "user_ref": "{{vault:Merchant-user-ref}}",
  "operator_id": "1",
  "product_id": "1",
  "recipient": "2349023172491",
  "amount": 10,
  "currency": "NGN",
  "reference": "buy000001"
}

Request Fields

Field	Type	Required	Description
`user_ref`	string	Yes	Reference of the user making the airtime purchase.
`operator_id`	string	Yes	Identifier of the mobile network operator.
`product_id`	string	Yes	Identifier of the airtime product.
`recipient`	string	Yes	Phone number that will receive the airtime. Use the appropriate international format.
`amount`	number	Yes	Amount of airtime to purchase.
`currency`	string	Yes	Currency of the transaction.
`reference`	string	Yes	Merchant-generated reference used to identify the transaction.

Example Request


   {
    "user_ref": "{{vault:Merchant-user-ref}}",
    "operator_id": "1",
    "product_id": "1",
    "recipient": "2349023172491",
    "amount": 10,
    "currency": "NGN",
    "reference": "buy000001"
  }

Response

A successful request returns the payment reference, transaction reference, wallet information, debit details, and the response received from the utility provider.

{
  "status": "success",
  "message": "Airtime purchase successful",
  "data": {
    "payment_ref": "a214d6da-126c-4c2d-9853-ba5006d0d0d9",
    "txn_ref": "buy000001",
    "wallet_id": "LBWNGN81C4801EE29D43F8A0B2231E367B74550063J",
    "debit_currency": "NGN",
    "debit_amount": 10,
    "utility_response": {
      "data": {
        "amountOperator": "10.00",
        "amountUser": "10",
        "artxId": 206954114999217600,
        "artxStatus": 0,
        "artxStatusDescription": "Successful",
        "balanceAfter": "12.84",
        "createdAt": "2026-08-30T17:04:16.401612Z",
        "currency": "NGN",
        "id": "b7aa68a0-f396-486f-9ef3-88bd4a8119fe",
        "kind": "airtime",
        "operatorId": "1",
        "productId": "1",
        "recipient": "2349023172491",
        "reference": "buy000001",
        "status": "success",
        "updatedAt": "2026-08-30T17:04:16.401612Z"
      }
    }
  }
}

Response Fields

Transaction Details

Field	Type	Description
`payment_ref`	string	Unique reference generated for the payment.
`txn_ref`	string	Transaction reference associated with the purchase.
`wallet_id`	string	Wallet used to fund the transaction.
`debit_currency`	string	Currency debited from the wallet.
`debit_amount`	number	Amount debited from the wallet.

Utility Response

The utility_response.data object contains the response returned by the underlying utility provider.

Field	Type	Description
`amountOperator`	string	Amount processed by the utility operator.
`amountUser`	string	Amount charged to the user.
`artxId`	number	Utility provider transaction identifier.
`artxStatus`	number	Status code returned by the utility provider.
`artxStatusDescription`	string	Description of the utility provider status.
`balanceAfter`	string	Remaining balance reported after the transaction.
`createdAt`	string	Timestamp when the utility transaction was created.
`currency`	string	Currency of the utility transaction.
`id`	string	Unique utility transaction identifier.
`kind`	string	Type of utility transaction. For this endpoint, the value is `airtime`.
`operatorId`	string	Mobile network operator identifier.
`productId`	string	Airtime product identifier.
`recipient`	string	Phone number that received the airtime.
`reference`	string	Transaction reference supplied in the request.
`status`	string	Utility transaction status.
`updatedAt`	string	Timestamp when the utility transaction was last updated.

Transaction Flow

User
  ↓
Billing Wallet Mapped
  ↓
Identify Operator
  ↓
Select Airtime Product
  ↓
Purchase Airtime
  ↓
LedgerBlock Processes Transaction
  ↓
Transaction Result / Webhook

Important: The user must have a billing wallet mapped for utility transactions before purchasing airtime.