Skip to main content

​
Overview

The Airtime Purchase API allows you to buy airtime for different network providers through Novac Payment’s Bills API. Before making a purchase, you can retrieve available airtime providers, check your account balance, and confirm transaction details after completion.
Use the correct serviceId for each network provider when making a purchase request.

​
Get Balance

Use this endpoint to check your current Novac Payment wallet balance before initiating a transaction. Provide the currency code for example NGN as part of the URL path.
Request
curl --request GET \
  --url https://integrations.novacpayment.com/api/v1/External/balance/{currency code} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
Response
{
    "code": 200,
    "status": "success",
    "message": "Successful",
    "data": {
        "success": true,
        "message": "Balance Fetched Successfully",
        "data": {
            "currency": "NGN",
            "balance": 92840.98
        }
    }
}
This helps ensure you have sufficient funds before performing an airtime purchase.

​
Purchase Airtime

To purchase airtime, retrieve the service provider here. Once you’ve identified the desired provider and confirmed your balance, send a POST request to this endpoint api/v1/BillsPayment/initiateairtimepurchase to initiate an airtime purchase for the specified phone number.
Novac uses a reference to track transactions, so it’s important to include it; if you don’t, we will generate one.
Request
curl --request POST \
  --url https://integrations.novacpayment.com/api/v1/BillsPayment/initiateairtimepurchase \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
    {
        "serviceId": "A01E",
        "amount": 3500,
        "phoneNumber": "09011111222",
        "reference": ""
    }
  '
Response
{
    "code": 200,
    "status": "success",
    "message": "Your transaction is in progress.",
    "data": {
        "status": "pending",
        "message": "Your transaction is in progress.",
        "reference": "reference",
        "amount": 3500,
        "fee": 0.00.
        "Domain": “test”
    }
}
If successful, the response confirms the transaction status and generated reference for tracking purposes.

​
Transaction Details

Use this endpoint to check the status or details of a completed or pending airtime purchase using its reference. This is especially useful for confirming delivery or updating transaction status in your system.
Request
curl --request GET \
  --url https://integrations.novacpayment.com/api/v1/BillsPayment/details?reference=string \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
Response
{
    "code": 200,
    "status": "success",
    "message": "Successful",
    "data": {
        "reference": "string",
        "status": "successful | pending | failed",
        "amount": 3500.00,
        "fee": 0.00,
        "recipient": "09011111222",
        "ipAddress": "1.1.1.1",
        "domain": "test",
        "billsProviderCode": "A01E",
        "billsProviderType": "airtime",
        "processingResponseCode": "00",
        "processingResponseMessage": "Successful",
        "transactionMetaData": "{}",
        "date": "13/10/2025 21:01"
    }
}
A successful response shows the full transaction metadata including the reference, amount, recipient, and transaction status.