Quick Start Documentation

Last updated: October 28th, 2019


The AirtimePay API is a REST based resource that offers you the flexibility to integrate your business with AirtimePay seamlessly. Our API has simple and easy to use URLS, accept JSON-encoded request bodies and return JSON-encoded responses. We also use standard HTTP response codes while transacting with our API.

We offer you the ability to test the API in sandbox mode, this does not affect your live transaction data, the API key you use will directly determine how AirtimePay treats the transaction, whether it's a test or live transaction.


Before you can integrate AirtimePay, you must set up your AirtimePay account and get your credentials for the test and live environments. You use these credentials to authorize your REST API calls. To test your web and mobile apps, use your test API keys.

AirtimePay API uses API keys to authenticate requests. You can view and manage your test and live API keys in the Dashboard's Settings section.

Test mode keys have the prefix test_ and live mode keys have the prefix live_. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, or client-side code.

Authentication to the API is performed via HTTP Basic Auth. Include your secret key in the Authorization header of every request you make.

Key Types

AirtimePay supports two types of keys - the secret key and public key, which both hold different levels of access to your AirtimePay account and can be accessed through the settings section of your merchant account. Both the secret and public keys can be used to initailize payment transactions for your business, however, we advice that you dont use your secret API keys on publicly/ client-side accessible integrations - this is the reaso we have disabled the use of secret keys in form based integration. Also do not keep your secret keys in your code repositories that are publicly visible like github etc.

Default code example:

"Authorization: Bearer test_4eC39HqLyjWDarjtT1zdp7dc"

Note: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

You must SET your callback URL in your merchant business settings section before integrating else, your calls will fail.


AirtimePay API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with AirtimePay's servers.


The following section, details the transactions currently available on this API, and will be updated from time to time, to reflect improvements and new features.

Standard Integration

Useful Tip:

Always include your API keys and use HTTPS when making API calls to avoid failed calls, also always declare content type as application/json. For initializing transactions, use PUBLIC/ SECRET API Keys and SET your callback URL in dashboard settings section to avoid failed calls

Step One: Prepare your parameters

Email and amount are compulsory parameters. Do send a unique email per customer. If your customers do not provide a unique email, please devise a strategy to set one for each of them.

Optional Fields Include: metaData (when passing metaData fullName and phoneNumber are required)

onSubmittedUrl: This is where the user is redirected after submitting the card PINs

description: This shows on the payment page and provides details of the payment.

Once your parameters are ready, initialize the payment using the following API call.

Step Two: Initialize the Transaction

Example Request - POST Transaction
curl --location --request POST "https://app.airtimepay.com/pay/transaction" \
		  --header "Content-Type: application/json" \
		  --header "key-type: public" \
		  --data "{
			\"amount\": 5000,
			\"email\": \"[email protected]\",
			\"metaData\": {
				\"fullName\": \"John Doe\",
				\"phoneNumber\": \"081xxxxxxxx\"
			\"onSubmittedUrl\": \"example.com/order\",
			\"description\": \"Game\"
Raw Request - POST

	"amount": 5000,
	"email": "[email protected]",
    "metaData": {
    	"fullName": "John Doe",
    	"phoneNumber": "081xxxxxxxx"
    "onSubmittedUrl": "example.com/order",
	"description": "Game"

Sample Response - Code 200 - OK
  "reference": "74a04e95dd4eceb0",
  "url": "https://app.airtimepay.com/pay/payment/74a04e95dd4eceb0"

Step Three: Redirect User to URL to complete payment

When the user enters the Card PINs for payment, AirtimePay will validate and start processing the card. Upon successful submission, AirtimePay will:

  1. Redirect back the user to a onSubmittedUrl set when initializing the transaction. If nothing is set, Customers see a "Payment Processing" message.

Upon succesful processing of the PIN(s) submitted by the user, AirtimePay Will:

  1. Send an event to your callback Url set in your dashboard with the sample request below,
  2. If receipts are not turned off, an HTML receipt will be sent to the customer's email and yours.

Example Callback Event
"email": "[email protected]",
"description": "Payment for Game download on Gamepad",
"metaData": {
    	"fullName": "John Doe",
    	"phoneNumber": "081xxxxxxxx"
"amount": 5000,
"reference": "bhsusbuhwhwjj22j32",
"status": "success"

Before you give value to the customer, please make a server-side call to our verification endpoint to confirm the status and properties of the transaction.

Step Four: Verify Transaction

We will post an event to the callback URL set on your dashboard. If it was a live transaction, we will post to your live callback url and vice-versa.

The transaction status can be one of the following:

  1. success
  2. pending
  3. failed

GET Transaction - https://app.airtimepay.com/pay/transaction/"reference"
curl --location --request GET "https://app.airtimepay.com/pay/transaction/74a04e95dd4eceb0"
Example Response - 200 - OK

"email": "[email protected]",
"description": "Payment for Game download on Gamepad",
"metaData": {
    	"fullName": "John Doe",
    	"phoneNumber": "081xxxxxxxx"
"amount": 5000,
"reference": "bhsusbuhwhwjj22j32",
"status": "failed"

Payment With Forms

Merchants who do not want to go through the standard integration can use forms to send their customers payment info to AirtimePay API. However, for us to understand and process your form request, you have to follow our "Payment Form Style"

The compulsory form fields are:

  1. type="number" name="amount"
  2. type="email" name="email"
  3. type="hidden" name="publicKey"

The other form fields are:

  1. type="text" name="description"
  2. type="text" name="onSubmittedUrl"

For meta data, name and phone are complulsory, The form fields must be prefixed with metaData:

  1. type="text" name="metaData_name"
  2. type="text" name="metaData_phoneNumber"
  3. type="text" name="metaData_age"
  4. type="text" name="metaData_address"

Note: The name attribute of your form field must correspond to our naming scheme, Valid Key Types are publicKey, testPublicKey, secretKey, testSecretKey. Forms Must be submitted using POST.
Example Form Code

<\form method="POST" action="https://app.airtimepay.com/pay/transaction"\>
    <\input type="number" name="amount" />
    <\input type="email" name="email" />
    <\input type="text" name="publicKey" />

    <\input type="text" name="description" />
    <\input type="text" name="onSubmittedUrl" />

    <\input type="text" name="metaData_name" />
    <\input type="text" name="metaData_phoneNumber" />
    <\input type="text" name="metaData_age" />
    <\input type="text" name="metaData_address" />

    <\input type="submit" name="submit" value="Pay Now" />

Once the user clicks Pay Now, they will be redirected to AirtimePay Payment Page to complete the payment. Then continue with step 3 above.