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 Anchor. If this is successful, you will receive a list of all airtime providers on Anchor:

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

curl --request GET \
     --url 'https://api.sandbox.getanchor.co/api/v1/bills/billers?category=airtime' \
     --header 'accept: application/json' \
     --header 'x-anchor-key: <API Key>'

{
  "data": [
    {
      "id": "168322497247222-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "NTEL",
        "category": "airtime",
        "slug": "ntel"
      }
    },
    {
      "id": "168322497215118-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Airtel",
        "category": "airtime",
        "slug": "airtel"
      }
    },
    {
      "id": "168322497203216-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "9Mobile",
        "category": "airtime",
        "slug": "9mobile"
      }
    },
    {
      "id": "16832249694843-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "MTN",
        "category": "airtime",
        "slug": "mtn"
      }
    }
  ]
}

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.

curl --request GET \
     --url https://api.sandbox.getanchor.co/api/v1/bills/billers/16832249694843-anc_blr/products \
     --header 'accept: application/json' \
     --header 'x-anchor-key: <API Key>'

{
  "data": [
    {
      "id": "16832249704130-anc_bll_itm",
      "type": "Airtime",
      "attributes": {
        "price": {
          "type": "Range",
          "minimumAmount": 500,
          "maximumAmount": 5000000,
          "currency": "NGN"
        },
        "name": "5-50000NGN Top Up",
        "slug": "mtn_5_50000ngn_top_up"
      },
      "relationships": {
        "provider": {
          "data": {
            "id": "16832249694843-anc_blr",
            "type": "Provider"
          }
        }
      }
    },
    {
      "id": "16832249706455-anc_bll_itm",
      "type": "Airtime",
      "attributes": {
        "price": {
          "type": "Fixed",
          "minimumAmount": 30000,
          "maximumAmount": 30000,
          "currency": "NGN"
        },
        "name": "Xtratalk 300",
        "slug": "mtn_xtratalk_300"
      },
      "relationships": {
        "provider": {
          "data": {
            "id": "16832249694843-anc_blr",
            "type": "Provider"
          }
        }
      }
    }
  ]
}

3. Initiate the airtime bill payment:

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

Attribute	Description
`type`	The type for airtime bill payment is `Airtime` .
`provider`	This is the airtime provider for the airtime purchase.
`phoneNumber`	This is the phone number that will receive the airtime.
`amount`	This is the amount of the airtime to be purchased (specified in the currencies lowest denomination).
`reference`	The unique identifier of the transaction on your system.

You would need to pass the account id and type (Deposit or Subaccount) where this transaction will be initiated or charged from.

Sample Request

curl --request POST \
     --url https://api.sandbox.getanchor.co/api/v1/bills \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-anchor-key: <API Key>' \
     --data '
{
  "data": {
    "type": "Airtime",
    "attributes": {
      "provider": "mtn",
      "phoneNumber": "2347012345678",
      "reference": "01231125aa6789",
      "amount": 1000
    },
    "relationships": {
      "account": {
        "data": {
          "type": "DepositAccount",
          "id": "16922123768364-anc_acc"
        }
      }
    }
  }
}
'

{
   "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"
      },
      "relationships":{
         "account":{
            "data":{
               "id":"16922609921350-anc_subacc",
               "type":"DepositAccount"
            }
         },
         "customer":{
            "data":{
               "id":"16922123736510-anc_bus_cst",
               "type":"BusinessCustomer"
            }
         }
      }
   }
}

Receive webhook events

You will receive bills.initiated events once the bill payment is initiated. If the bill payment is success full, you will receive bills.successful event. If this payment is not successful, you will receive bills.failed event.

{
  "data": {
    "id": "1701682033973765-anc_et",
    "type": "bills.initiated",
    "attributes": {
      "createdAt": "2023-12-04T10:27:14"
    },
    "relationships": {
      "bill": {
        "data": {
          "id": "17016820338191-anc_bll",
          "type": "BillPayment"
        }
      },
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }

{
  "data": {
    "id": "1701682034325824-anc_et",
    "type": "bills.successful",
    "attributes": {
      "createdAt": "2023-12-04T10:27:14"
    },
    "relationships": {
      "bill": {
        "data": {
          "id": "17016820338191-anc_bll",
          "type": "BillPayment"
        }
      },
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }

You can also use the support included functionality when listening to this bill payment event to retrieve other information such as the customer detail that is related to this event.