> ## Documentation Index
> Fetch the complete documentation index at: https://developer.novacpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase Airtime

> Learn how to fetch airtime providers, check wallet balance, and purchase airtime.

## 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.

<Note>
  Use the correct `serviceId` for each network provider when making a purchase request.
</Note>

***

## 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.

```bash Request theme={null}
curl --request GET \
  --url https://integrations.novacpayment.com/api/v1/External/balance/{currency code} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
```

```json Response theme={null}
{
    "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](/docs/make-payment/bills/retrieve-bills-service-providers). 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.

<Note>
  Novac uses a reference to track transactions, so it's important to include it; if you don't, we will generate one.
</Note>

```bash expandable Request theme={null}
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": ""
    }
  '
```

```json expandable Response theme={null}
{
    "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.

```bash expandable Request theme={null}
curl --request GET \
  --url https://integrations.novacpayment.com/api/v1/BillsPayment/details?reference=string \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
```

```json expandable Response theme={null}
{
    "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.