Authorization
Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

OAuth2
This API is used to get the bearer token. The output of this API contains access_token that will be used as bearer token for the API that we will be going to call.

POST /auth/oauth2/token

Note : This is a common API to fetch access token for all the APIs listed in the documentation section.
Parameters
Name	In	Type	Required	Description
Content-Type	header	string	true	specifies the media type of the request.
Accept	header	string	true	specifies the media type of the response.
Request Body
Attribute	Description
client_id
string
mandatory	The client_id is a public identifier for apps. It must also be unique across all clients that the authorization server handles. This is equivalent to consumer key displayed under keys section of application listing. Example: c02e9e46-db9d-4faf-b91a-94f88bbe688c
client_secret
string
mandatory	The client_secret is a secret known only to the application and the authorization server.This is equivalent to consumer secret displayed under keys section of application listing Example: ab672211-4197-4c11-ba79-b29ce2034ca2
grant_type
string
mandatory	The Client Credential grant type is used by confidential and public clients to fetch access token. Example: client_credentials
Response Body
Attribute	Description
access_token
string
Received token of the user.
expires_in
string
Expiry time of the access-token received.
token_type
string
Type of token.
This operation is required to fetch OAuth2 Access token.
ShellRubyPythonJavascriptJavaPHP
Code samples

                
<?php>
require 'vendor/autoload.php';
$headers = array(
   'Content-Type' => 'application/json', 
   'Accept' => '*/*', 
);

$client = new GuzzleHttpClient();

request_body = array();

try {
  $response = $client->request('POST', 'https://openapiuat.airtel.africa/auth/oauth2/token', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
  print_r($e->getMessage());
}
                
                

Encryption
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

As part of our security enhancements, we now support RSA encryption with 2048-bit keys and a new algorithm for PIN encryption. We highly recommend transitioning to this stronger security mechanism for improved protection. All other interactions will remain unchanged.

Encryption documentation details methods for encrypting sensitive data, including PINs and callbacks, ensuring secure handling and protection against unauthorized access.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Pin Encryption
An RSA user creates and publishes a public key based on two large prime numbers, along with an auxiliary value. The prime numbers are kept secret. Messages can be encrypted by anyone, via the published public key, but can only be decoded by private key.

RSA encryption strategy with mode ECB, padding OAEPWithSHA-256AndMGF1Padding and KeyLength 2048 is used to encrypt data at client side..

It can be done using the below given code snippet for RSA encryption.


Note : Public key is available in code snippet. Copy it from there.
ShellRubyPythonJavascriptJavaPHP
Public Key

                    
                        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArUj2SQKLCdTqJ3/ZL6nkh1N3rtjXBBM+0hBUrhJ/VNSMTBixpD+JjeNaHbONcrvJGSstC2tcVfD04s9xGIKr9TT6hCYaqGojLeuLimVdXzaP5DzDyrHY8mYgHL+/EGRDh+/7B56Gw8UZxOBPtF6Wjjq0TWGcw5YOW1lSPUeaD+kupmDFlMRk26fASELwkYo5NkHgL/w+XzXw8gDZtrNS6L8UX2mfqdQ9qKpdMP3ztfOUPjmTvIbTKrGLx0U2sUSQINtMxZQzsYaXIGoZ2thvbIhJMDFBNbznuv1n8b03Q3MAnEK/xCduQBUkUg1syy7jZMT4ETDeFuW2NMZhteaadwIDAQAB
                    
                
Code samples

                
                    <?php
$data = "{"transaction":{"id":"BBZMiscxy","message":"Paid UGX 5,000 to TECH LIMITED, Trans ID MP210603.1234.L06941.","status_code":"TS","airtel_money_id":"MP210603.1234.L06941"}}";

// Load public key
$publicKey = "-----BEGIN PUBLIC KEY-----\n" .
             "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA20O377QEiZvPsj*************JB5WDTVjeab\n" .
             "-----END PUBLIC KEY-----";

// Encrypt data
openssl_public_encrypt($data, $encrypted, $publicKey, OPENSSL_PKCS1_OAEP_PADDING);

// Encode encrypted data in base64
$encodedEncrypted = base64_encode($encrypted);

echo $encodedEncrypted;
?>


Encryption
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

As part of our security enhancements, we now support RSA encryption with 2048-bit keys and a new algorithm for PIN encryption. We highly recommend transitioning to this stronger security mechanism for improved protection. All other interactions will remain unchanged.

Encryption documentation details methods for encrypting sensitive data, including PINs and callbacks, ensuring secure handling and protection against unauthorized access.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Callback Encryption
Partner Can Authenticate the response sent to them regarding the status of the transaction on the callback url. It can be configured in Application settings. Along with the callback request body a , hash message will be sent to user. User can hash the the callback request with the private key shown in application setting using HmacSHA256 algorithm, with output text format in Base64 and can match with it hash message sent if Callback authentication is enabled.

SHA256 with RSA signature is an efficient asymmetric encryption method used in many secure APIs. This algorithm first calculates a unique hash of the input data using SHA256 algorithm. The hash is then encrypted with a private key using the RSA algorithm. Steps to enable callback authentication

Step1 : Go to application settings

Step 2: Enable callback authentication

Step 3: Copy Private key to encrypt using HMAC algortihm

Note : Private key is available in application settings of account . Copy it from there.

ShellRubyPythonJavascriptJavaPHP
Code samples

                
                    <?php
// Your code here!
$data = "{"transaction":{"id":"BBZMiscxy","message":"Paid UGX 5,000 to TECH LIMITED, Trans ID MP210603.1234.L06941.","status_code":"TS","airtel_money_id":"MP210603.1234.L06941"}}";
$s = hash_hmac('sha256', $data, 'a4f48f692d2b4df9acbad7dff60a32a6', true);
echo base64_encode($s);
?>
                

Encryption
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

As part of our security enhancements, we now support RSA encryption with 2048-bit keys and a new algorithm for PIN encryption. We highly recommend transitioning to this stronger security mechanism for improved protection. All other interactions will remain unchanged.

Encryption documentation details methods for encrypting sensitive data, including PINs and callbacks, ensuring secure handling and protection against unauthorized access.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Encryption Keys
This API gets the encyption key.

GET /v1/rsa/encryption-keys

Note: For consuming this API consumer needs to add any of the below products in his account : Collection, Disbursement, Cash-In, Cash-Out, ATM Withdrawl.
Parameters
Name	In	Type	Required	Description
Authorization	header	string	true	Authorization bearer token.
X-Country	header	string	true	Transaction country.
X-Currency	header	string	true	Transaction currency.
Authorization	header	string	true	Authorization bearer token.
Response Body
Attribute	Description
data
object
Encryption keys api response.
data.key_id
number
Id associated to key returned.
data.key
string
RSA public key for given customer.
data.valid_upto
string
Expiry date of the key.
status
object
Status response.
status.code
string
Status code, HTTP status code.
status.message
string
The descriptive message of the response/action.
status.response_code
string
Product specific code to identify the error and success response. This will be different for the type of error and success.
status.result_code
string
Application specific code to identify the error and success response. This will be different for the type of error and success.
status.success
boolean
true if no error else false.
This operation does require Oauth2 authentication.
ShellRubyPythonJavascriptJavaPHP
Code samples

                
                    <?php>

    require 'vendor/autoload.php';

    $headers = array(
      'Authorization' => 'Bearer UCc*****ki2w', 
      'X-Country' => 'UG', 
      'X-Currency' => 'UGX', 
      'Authorization' => 'Bearer UCc*****ki2w', 
);

$client = new GuzzleHttpClient();

request_body = array();

try {
  $response = $client->request('GET', 'https://openapiuat.airtel.africa/v1/rsa/encryption-keys', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
  print_r($e->getMessage());
}
                
                
200 responses

                        
                            {
  "data": {
    "key_id": 100,
    "key": "MIG********AB",
    "valid_upto": "12-08-2024 21:29:26"
  },
  "status": {
    "code": "200",
    "message": "Success",
    "response_code": "DP02010001001",
    "result_code": "ESB000010",
    "success": true
  }
}
                        

Message Signing
Message signing in requests is a security technique to ensure the authenticity and integrity of data sent between parties. It involves generating a key , creating a payload, calculating a hash of the payload, signing the hash with the generated key, and including the signature in the request. On the server side, the private key is used to verify the signature, ensuring the data hasn't been tampered with. This process safeguards against data manipulation and impersonation during transmission. We use a similar technique to sign our request. Partner needs to encrypt the payload using a randomly generated AES key iv pair . Encrypt the key iv using a RSA key and add both encrypted key and encrypted signature to the request as headers. At the server side we use private RSA key to decrypt the AES key iv and encrypt the payload with this key and iv. We match this generated encrypted payload to the signature received to ensure that there is no change in the payload sent by the partner and payload received.

STEPS :

1. Generate a random AES key of size 256 bits and iv of size 128 bits using AES/CBC/PKCS5Padding algorithm.

2. Generated AES key and iv should be base 64 encoded.
Example - Key(PSw37xtnShLl7zgWn4dLSnf1J5GRhRsOD4OfvJOuLIM=) and iv(gGIhDvCBnSBhBgYiXCyMnw==)

3. Fetch RSA key for the consumer from encryption keys dev portal api.
Example - RSA key will be MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCYtZNZnPdBFqUIXoSJlvjhYH5m3Yq8OcK6OzQXxcE8nh7kRCwTvTpnNBIY+Dn1TQa9sq/iGuTfXgJABOzTH0Z4vT6V6vB6VlF4W469iH5u+BRwpV3YXYKm4dr5633UO1XBLdAc2X4aXm51HNkZKg+D0/zGOUFxwCAlYKr92kPHwQIDAQAB

4. Encrypt payload using AES key and iv . This encrypted payload will be sent as header x-signature of the request.
For example payload
{"reference": "1234","subscriber": {"country": "UG","currency": "UGX","msisdn": "752604392"},"transaction": {"amount": "100","country": "UG","currency": "UGX","id": "test_id"}}
will be encrypted to bDOsVGZzbK0P5jO/M5QVMH/qxSmRJLEvIPZCdW6H81xvsZNI6jZej54oBQlHZ38yy63QNeyyYcfEkGJ8f3f15wHWs86V9BCIpHSesS3SrhozE/gGA1fLydeSS26mw0jhyt9XIpabk1RjDH59SfsrkHKU38I5mRlthG/t2qXJck0FhNR64bgOExm9CsuxUlfpsSoW1g81g1u5a4yMFIHhp77f+h3EXNHzcEsdSWhqTho= using key and iv generated in point 2

5. Now concatenate the key and iv separated by a colon(Key:Iv)
Example - PSw37xtnShLl7zgWn4dLSnf1J5GRhRsOD4OfvJOuLIM=:gGIhDvCBnSBhBgYiXCyMnw==

6. Encrypt this key:iv using RSA public key (point 3). This encrypted key:iv will be sent as header x-key of the request
Example - PSw37xtnShLl7zgWn4dLSnf1J5GRhRsOD4OfvJOuLIM=:gGIhDvCBnSBhBgYiXCyMnw== will be encrytped using RSA keyMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCYtZNZnPdBFqUIXoSJlvjhYH5m3Yq8OcK6OzQXxcE8nh7kRCwTvTpnNBIY+Dn1TQa9sq/iGuTfXgJABOzTH0Z4vT6V6vB6VlF4W469iH5u+BRwpV3YXYKm4dr5633UO1XBLdAc2X4aXm51HNkZKg+D0/zGOUFxwCAlYKr92kPHwQIDAQAB.
So now x-key will be P0nwxJPVzTHzSbxcVyIi5PlpTRfiScRd4WaeSIUlXWtQwlSb0cesrvsi0jpsIUuPwvU3Zmvc2BVMH5m1873I4qAvFE6zTgHXWUZwRh+poXCXLWwn8NLEYqv9rmSQNkO3yvAYWnP4kR+h7NXrwBBSAoRP5w5Ue6TFDWZQECxikP0=

7. Once we receive the x-key and x-signature, we will decrypt the key:iv pair and encrypt the payload with this key:iv. If the encrypted payload matches x-signature, request will be considered valid else forbidden.


Encryption
Version
2.0
Encryption documentation details methods for encrypting sensitive data, including PINs and callbacks, ensuring secure handling and protection against unauthorized access.

Error Codes
Learn about error codes and what they mean.This page contains codes and descriptions of all errors that may occur when you communicate with the Encryption API. If after reading this section you are still not sure how to interpret a specific error, contact the support team
Error Code	Expected Error Reason	Description
DP02010001000
Error while fetching encryption key	Could not fetch encryption key.
DP02010001001
Successfully fetched encryption key.	Encryption key has been fetched successfully.



Collection-APIs
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

1. Message signing feature has been introduced in this version for Collection Payment and Refund api. 2. Message signing feature can be enabled or disabled for collection from the security section of the setting tab in application where Collection API is subscribed and approved.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Payments - USSD Push
This API is used to request a payment from a consumer(Payer). The consumer(payer) will be asked to authorize the payment. After authorization, the transaction will be executed.

POST /merchant/v2/payments/

Note : Do not send country code in msisdn.
Parameters
Name	In	Type	Required	Description
Accept	header	string	true	Specifies the media type of the response.
Content-Type	header	string	true	specifies the media type of the request.
X-Country	header	string	true	Transaction country.
X-Currency	header	string	true	Transaction currency.
Authorization	header	string	true	Authorization bearer token.
x-signature	header	string	true	Encrypted payload.
x-key	header	string	true	Encrypted AES key and iv.
Request Body
Attribute	Description
reference
string
mandatory	Reference for service / goods purchased.
subscriber
object
mandatory	Subscriber.
subscriber.country
string
mandatory	The country of the subscriber.
subscriber.currency
string
optional	The currency of the subscriber.
subscriber.msisdn
string
mandatory	MSISDN without the country code of the subscriber from which the payment amount deducted.
transaction
object
mandatory	Transaction details.
transaction.amount
number
mandatory	Transaction amount which will be deducted from subscriber's wallet.
transaction.country
string
optional	The country in which the transaction is happening, basically used for cross border payments. For the same country, this field is not required.
transaction.currency
string
optional	The currency in which the transaction is happening, basically used for cross border payments.For the same country, this field is not required.
transaction.id
string
mandatory	Partner unique transaction id to identify the transaction.
Response Body
Attribute	Description
data
object
Ussd Payment Response.
data.transaction
object
Ussd Payment Transaction.
transaction.id
boolean
Partner transaction-id which the partner send in the request
transaction.status
string
Transaction status.
status
object
Status Response.
status.code
string
Status code, HTTP status code.
status.message
string
The descriptive message of the response/action.
status.result_code
string
Application specific code to identify the error and success response. This will be different for the type of error and success.
Deprecated. Please use status.response_code field for new error code.
status.response_code
string
Product specific code to identify the error and success response. This will be different for the type of error and success.
status.success
boolean
true if no error else false.
This operation does require Oauth2 authentication.

Code samples

                
                    <?php
require 'vendor/autoload.php';
$headers = array(
  'Accept' => '*/* ',
  'Content-Type' => 'application/json',
  'X-Country' => 'UG',
  'X-Currency' => 'UGX',
  'Authorization' => 'Bearer UC*******2w',
  ' x-signature' => 'MGsp*****************Ag==',
  ' x-key' => 'DVZC*******************NM='
);
$client = new GuzzleHttpClient();
// Define array of request body.
$request_body = array();
try {
  $response = $client->request('POST', 'https://openapiuat.airtel.africa/merchant/v2/payments/', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
// handle exception or api errors.
  print_r($e->getMessage());
}
                
                
Body parameter

                        
                            {
    "reference": "Testing transaction",
    "subscriber": {
        "country": "UG",
        "currency": "UGX",
        "msisdn": "12****89"
    },
    "transaction": {
        "amount": 1000,
        "country": "UG",
        "currency": "UGX",
        "id": "random-unique-id"
    }
}
                        
                    
200 responses

                        
                            {
    "data": {
        "transaction": {
            "id": false,
            "status": "SUCCESS"
        }
    },
    "status": {
        "code": "200",
        "message": "SUCCESS",
        "result_code": "ESB000010",
        "response_code": "DP00800001006",
        "success": true
    }
}

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Refund
This API is used to make full refunds to Partners.

POST /standard/v2/payments/refund

Parameters
Name	In	Type	Required	Description
Accept	header	string	true	Specifies the media type of the response.
Content-Type	header	string	true	specifies the media type of the request.
X-Country	header	string	true	Transaction country.
X-Currency	header	string	true	Transaction currency.
Authorization	header	string	true	Authorization bearer token.
x-signature	header	string	true	Encrypted payload.
x-key	header	string	true	Encrypted AES key and iv.
Request Body
Attribute	Description
transaction
object
mandatory	Transaction
transaction.airtel_money_id
string
mandatory	Airtel unique transaction id to identify the transaction.
Response Body
Attribute	Description
data
object
Payment refund response.
data.transaction
object
Refund transaction.
transaction.airtel_money_id
string
Transaction id generated by AM.
transaction.status
string
Possible status: SUCCESS.
status
object
Status response.
status.code
string
Status code, HTTP status code.
status.message
string
The descriptive message of the response/action.
status.result_code
string
Application-specific code to identify the error and success response. This will be different for the type of error and success.
status.success
boolean
true if no error else false.
This operation does require Oauth2 authentication.

               
                    <?php
require 'vendor/autoload.php';
$headers = array(
  'Accept' => '*/* ',
  'Content-Type' => 'application/json',
  'X-Country' => 'UG',
  'X-Currency' => 'UGX',
  'Authorization' => 'Bearer UC*******2w',
  'x-signature' => 'MGsp*****************Ag==',
  'x-key' => 'DVZC*******************NM='
);
$client = new GuzzleHttpClient();
// Define array of request body.
$request_body = array();
try {
  $response = $client->request('POST', 'https://openapiuat.airtel.africa/standard/v2/payments/refund', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
// handle exception or api errors.
  print_r($e->getMessage());
}
                
                
Body parameter

                        
                            {
   "transaction": {
      "airtel_money_id": "CI************18"
   }
}
                        
                    
200 responses

                        
                            {
    "data": {
        "transaction": {
            "airtel_money_id": "CI2****29",
            "status": "SUCCESS"
        }
    },
    "status": {
        "code": "200",
        "message": "SUCCESS",
        "result_code": "ESB000010",
        "success": false
    }
}



Collection-APIs
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

1. Message signing feature has been introduced in this version for Collection Payment and Refund api. 2. Message signing feature can be enabled or disabled for collection from the security section of the setting tab in application where Collection API is subscribed and approved.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Transaction Enquiry
GET /standard/v1/payments/{id}

Parameters
Name	In	Type	Required	Description
Accept	header	string	true	Specifies the media type of the response.
X-Country	header	string	true	Transaction Country
X-Currency	header	string	true	Transaction Currency
Authorization	header	string	true	Authorization Bearer Token
Response Body
Attribute	Description
data
object
Transaction enquiry response.
data.transaction
object
Transaction response.
transaction.airtel_money_id
string
Transaction Id generated by AM in case of successful transaction TS (Transaction Success).
transaction.id
string
Transaction Id generated by TPP / Aggregator / Merchant.
transaction.message
string
Description message for the transaction status.
transaction.status
string
Possible Status: TF (Transaction Failed) TS (Transaction Success) TA (Transaction Ambiguous) TIP (Transaction in Progress) TE (Transaction Expired)
status
object
Status response.
status.code
string
Status code, HTTP status code.
status.message
string
The descriptive message of the response/action.
status.result_code
string
Application specific code to identify the error and success response. This will be different for the type of error and success.
Deprecated. Please use status.response_code field for new error code.
status.response_code
string
Product specific code to identify the error and success response. This will be different for the type of error and success.
status.success
boolean
true if no error else false.
This operation does require Oauth2 authentication.

Code samples

                
<?php
require 'vendor/autoload.php';
$headers = array(
  'Accept' => '*/* ',
  'X-Country' => 'UG',
  'X-Currency' => 'UGX',
  'Authorization' => 'Bearer UC*******2w'
);
$client = new GuzzleHttpClient();
// Define array of request body.
$request_body = array();
try {
  $response = $client->request('GET', 'https://openapiuat.airtel.africa/standard/v1/payments/{id}', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
// handle exception or api errors.
  print_r($e->getMessage());
}
                
                
200 responses

                        
                            {
    "data": {
        "transaction": {
            "airtel_money_id": "C36*******67",
            "id": "83****88",
            "message": "success",
            "status": "TS"
        }
    },
    "status": {
        "code": "200",
        "message": "SUCCESS",
        "result_code": "ESB000010",
        "response_code": "DP00800001006",
        "success": false
    }
}
                    



Collection-APIs
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

1. Message signing feature has been introduced in this version for Collection Payment and Refund api. 2. Message signing feature can be enabled or disabled for collection from the security section of the setting tab in application where Collection API is subscribed and approved.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Callback Without Authentication
Airtel Africa sends the status of the transaction on the callback url. The status of the transaction in the callback URL can be intermediate or final status. The URL is in the format "https://partner_domain/callback_path" can be configured in Application settings.

POST /callback_path

Parameters
Name	In	Type	Required	Description
Content-Type	header	string	true	specifies the media type of the request.
Request Body
Attribute	Description
transaction
object
mandatory	Transaction detail.
transaction.id
string
mandatory	Partner unique transaction id to identify the transaction.
transaction.message
string
mandatory	Description message for the transaction status.
transaction.status_code
string
mandatory	Possible Status: TF (Transaction Failed) TS (Transaction Success).
transaction.airtel_money_id
string
mandatory	Transaction id generated by AM.
ShellRubyPythonJavascriptJavaPHP
Code samples

                
                    <?php
require 'vendor/autoload.php';
$headers = array(
  'Content-Type' => 'application/json'
);
$client = new GuzzleHttpClient();
// Define array of request body.
$request_body = array();
try {
  $response = $client->request('POST', 'https://openapiuat.airtel.africa/callback_path', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
// handle exception or api errors.
  print_r($e->getMessage());
}
                



Collection-APIs
Version
2.0
Always stay ahead with the latest version! Older versions may be deprecated at any time, so for the best experience and support, we recommend using the most up-to-date API. Keep your integration future-proof!

Version Highlights:

1. Message signing feature has been introduced in this version for Collection Payment and Refund api. 2. Message signing feature can be enabled or disabled for collection from the security section of the setting tab in application where Collection API is subscribed and approved.

Base URLs:

Staging -- https://openapiuat.airtel.africa/

Production -- https://openapi.airtel.africa/

Callback With Authentication
Airtel Africa sends the status of the transaction on the callback url. The status of the transaction in the callback URL can be intermediate or final status. Along with the callback request body a , hash message will be sent to user.User can hash the the callback request with the private key shown in application setting using HmacSHA256 algorithm, with output text format in Base64 and can match with it hash message sent if Callback authentication is enabled.

POST /callback_path

Note: The URL is in the format "https://partner_domain/callback_path" can be configured in Application settings.
Parameters
Name	In	Type	Required	Description
Content-Type	header	string	true	specifies the media type of the request.
Request Body
Attribute	Description
transaction
object
mandatory	Transaction detail.
transaction.id
string
mandatory	Partner unique transaction id to identify the transaction.
transaction.message
string
mandatory	Description message for the transaction status.
transaction.status_code
string
mandatory	Possible Status: TF (Transaction Failed) TS (Transaction Success).
transaction.airtel_money_id
string
mandatory	Transaction id generated by AM.
hash
string
mandatory	Hmac generated using private key. To check for encryption Please click here
ShellRubyPythonJavascriptJavaPHP
Code samples

                
                    <?php
require 'vendor/autoload.php';
$headers = array(
  'Content-Type' => 'application/json'
);
$client = new GuzzleHttpClient();
// Define array of request body.
$request_body = array();
try {
  $response = $client->request('POST', 'https://openapiuat.airtel.africa/callback_path', array(
    'headers' => $headers,
    'json' => $request_body
    )
  );
 print_r($response->getBody()->getContents());
}
catch (GuzzleHttpExceptionBadResponseException $e) {
// handle exception or api errors.
  print_r($e->getMessage());
}
                
                
Body parameter

                        
                            {
    "transaction": {
        "id": "BBZMiscxy",
        "message": "Paid UGX 5,000 to TECHNOLOGIES LIMITED Charge UGX 140, Trans ID MP210603.1234.L06941.",
        "status_code": "TS",
        "airtel_money_id": "MP210603.1234.L06941"
    },
    "hash": "zITVAAGYSlzl1WkUQJn81kbpT5drH3koffT8jCkcJJA="
}
                        


Collection-APIs
Version
2.0
Error Codes
Learn about error codes and what they mean. This page contains codes and descriptions of all errors that may occur when you communicate with the Collection API. If after reading this section you are still not sure how to interpret a specific error, contact the support team
Error Code	Expected Error Reason	Description
DP00800001000
Ambiguous	The transaction is still processing and is in ambiguous state. Please do the transaction enquiry to fetch the transaction status.
DP00800001001
Success	Transaction is successful.
DP00800001002
Incorrect Pin	Incorrect pin has been entered.
DP00800001003
Exceeds withdrawal amount limit(s) / Withdrawal amount limit exceeded	The User has exceeded their wallet allowed transaction limit.
DP00800001004
Invalid Amount	The amount User is trying to transfer is less than the minimum amount allowed.
DP00800001005
Transaction ID is invalid	User didn't enter the pin.
DP00800001006
In process	Transaction in pending state. Please check after sometime.
DP00800001007
Not enough balance	User wallet does not have enough money to cover the payable amount.
DP00800001008
Refused	The transaction was refused.
DP00800001010
Transaction not permitted to Payee	Payee is already initiated for churn or barred or not registered on Airtel Money platform.
DP00800001024
Transaction Timed Out	The transaction was timed out.
DP00800001025
Transaction Not Found	The transaction was not found.
DP00800001026
Forbidden	X-signature and payload did not match.
DP00800001029
Transaction Expired	Transaction has been expired.