Airtime Purchase

1. Get the list of airtime providers

To initiate airtime bill payment, make an API call to the list billers endpoint to fetch all the airtime providers’ details on Smarthivesms. If this is successful, you will receive a list of all airtime providers on Smarthivesms:

Airtime Providers on Smarthivesms: MTN, Airtel, 9Mobile, NTEL, GLO

Verb	URL
GET	{{baseUrl}}/api/bills/airtime/get_airtime_providers

To initiate data bill payment, make an API call to the list billers endpoint to fetch all the data providers’ details on Anchor. If this is successful, you will receive a list of all data providers on Anchor.

Sample request payload and sample 200 OK response payload are given below:

List Data Providers

curl --request GET \
'http://localhost:6008/api/bills/airtime/get_airtime_providers' \
     --header 'accept: application/json' \
     --header 'x-api-key: <API KEY>'

200 OK Response

{
    "status": "ok",
    "description": "The request has succeeded",
    "data": [
        {
            "provider_id": "168322497247222-anc_blr",
            "type": "Provider",
            "attributes": {
                "name": "NTEL",
                "category": "airtime",
                "slug": "ntel"
            }
        },
        {
            "provider_id": "168322497215118-anc_blr",
            "type": "Provider",
            "attributes": {
                "name": "Airtel",
                "category": "airtime",
                "slug": "airtel"
            }
        },
        {
            "provider_id": "168322497203216-anc_blr",
            "type": "Provider",
            "attributes": {
                "name": "9Mobile",
                "category": "airtime",
                "slug": "9mobile"
            }
        },
        {
            "provider_id": "168322497175013-anc_blr",
            "type": "Provider",
            "attributes": {
                "name": "GLO",
                "category": "airtime",
                "slug": "glo"
            }
        },
        {
            "provider_id": "16832249694843-anc_blr",
            "type": "Provider",
            "attributes": {
                "name": "MTN",
                "category": "airtime",
                "slug": "mtn"
            }
        }
    ]
}

2. Get the provider’s details

Verb	URL
GET	{{baseUrl}}/api/bills/airtime/get_airtime_products?providerId={providerId}

2. Get the airtime provider’s details

Then call the list biller product endpoint and pass the billerId to fetch all the Products of that provider. When you list the biller product, note the slug and priceof the data product you want to purchase as you will use this in creating the data bill payment.

price - price of the of the airtime specified in the countries lowest currency unit. Price is a fixed for data

billerId is the unique Id of the bill provider on Anchor.

slug is the human readable identifier of the airtime product/plan. When you list a biller product you will see the product slug on each biller product.

List Provider Details

curl --request GET \
'http://localhost:6008/api/bills/airtime/get_airtime_products?providerId=168322497247222-anc_blr' \
--header 'accept: application/json' \
--header 'x-api-key: <API KEY>'

200 OK Response

{
    "status": "ok",
    "description": "The request has succeeded",
    "data": [
        {
            "product_id": "168322497253861-anc_bll_itm",
            "provider_id": "168322497247222-anc_blr",
            "type": "Airtime",
            "attributes": {
                "price": {
                    "type": "Range",
                    "minimumAmount": 500,
                    "maximumAmount": 5000000,
                    "currency": "NGN"
                },
                "name": "5-50000NGN Top Up",
                "slug": "ntel_5_50000ngn_top_up"
            }
        }
    ]
}

3. Initiate the data bill payment:

Verb	URL
POST	{{baseUlr}}/api/bills/airtime/get_airtime

When you have identified the data bundle you want to purchase, you can proceed to purchase the identified data plan.

Attribute	Description
phoneNumber	This is the phone number that will receive the data bundle.
amount	This is the fixed amount of the data bundle (specified in the currencies lowest denomination).
provider	The slug of the product for which the payment is being made.
reference	The unique identifier of the transaction on your system.

Initiate Data Purchase

curl --location 'http://localhost:6008/api/bills/data/get_data' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <API KEY>' \
--data '{
    "phoneNumber": "23490XXXXXXX",
    "amount": 10000,
    "provider": "mtn",
    "reference": 3456789
}'

200 OK Response

{
    "status": "ok",
    "description": "The request has succeeded",
    "data": {
        "id": "16974519234112-anc_bll",
        "type": "BillPayment",
        "attributes": {
            "reference": "01231125aa6789",
            "createdAt": "2023-10-16T10:25:23.412472",
            "amount": 1000,
            "phoneNumber": "2347012345678",
            "detail": {
                "provider": "MTN",
                "product": "5-50000NGN Top Up",
                "units": 0
            },
            "category": "airtime",
            "commissionAmount": 0,
            "status": "COMPLETED",
            "updatedAt": "2023-10-16T10:25:24.085709"
        }
    }
}