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.
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.
"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.
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
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.
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\"
}"
{
"amount": 5000,
"email": "[email protected]",
"metaData": {
"fullName": "John Doe",
"phoneNumber": "081xxxxxxxx"
},
"onSubmittedUrl": "example.com/order",
"description": "Game"
}
{
"reference": "74a04e95dd4eceb0",
"url": "https://app.airtimepay.com/pay/payment/74a04e95dd4eceb0"
}When the user enters the Card PINs for payment, AirtimePay will validate and start processing the card. Upon successful submission, AirtimePay will:
Upon succesful processing of the PIN(s) submitted by the user, AirtimePay Will:
{
"email": "[email protected]",
"description": "Payment for Game download on Gamepad",
"metaData": {
"fullName": "John Doe",
"phoneNumber": "081xxxxxxxx"
},
"amount": 5000,
"reference": "bhsusbuhwhwjj22j32",
"status": "success"
}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:
curl --location --request GET "https://app.airtimepay.com/pay/transaction/74a04e95dd4eceb0"
{
"email": "[email protected]",
"description": "Payment for Game download on Gamepad",
"metaData": {
"fullName": "John Doe",
"phoneNumber": "081xxxxxxxx"
},
"amount": 5000,
"reference": "bhsusbuhwhwjj22j32",
"status": "failed"
}
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:
The other form fields are:
For meta data, name and phone are complulsory, The form fields must be prefixed with metaData:
<\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" />