Airtel Money SDK

deadangroup/airtel — Airtel Money Kenya API

Namespace: DGL\Airtel Base URLs: openapiuat.airtelkenya.com (sandbox) / openapi.airtelkenya.com (production)

Configuration

// config/airtel.php
return [
    'is_sandbox' => true,
    'client_id' => '...',
    'client_secret' => '...',
    'country' => 'KE',
    'currency' => 'KES',
    'callback_url' => '...',
];

Auth: OAuth2 client_credentials grant. Tokens expire every 180 seconds.

Headers: All requests include X-Country and X-Currency headers.

Collection (Receive Money)

USSD Push

Request payment from a subscriber's Airtel Money wallet.

$client->ussdPush([
    'msisdn' => '712345678',
    'amount' => 1000,
    'reference' => 'Invoice payment',
    'transaction_id' => 'unique-id-123',
]);

Endpoint: POST /merchant/v1/payments/

Request body:

{
    "reference": "Invoice payment",
    "subscriber": {
        "country": "KE",
        "currency": "KES",
        "msisdn": "712345678"
    },
    "transaction": {
        "amount": 1000,
        "country": "KE",
        "currency": "KES",
        "id": "unique-id-123"
    }
}

Collection Enquiry

Check the status of a collection transaction.

$client->collectionEnquiry([
    'transaction_id' => 'unique-id-123',
]);

Endpoint: GET /standard/v1/payments/{id}

Response:

{
    "transaction": {
        "airtel_money_id": "C36XXXXX67",
        "id": "83XXXX88",
        "message": "success",
        "status": "TS"
    }
}

Status codes: TS = Success, TF = Failed, TIP = In Progress

Refund

Refund a completed collection.

$client->refund([
    'airtel_money_id' => 'CI123456789018',
]);

Endpoint: POST /standard/v1/payments/refund

Disbursement (Send Money)

Send money to an Airtel Money subscriber. Requires PIN encryption.

$client->disburse([
    'msisdn' => '712345678',
    'name' => 'Bob',
    'amount' => 500,
    'reference' => 'REF001',
    'pin' => '1234',  // SDK encrypts this with RSA
]);

Endpoint: POST /standard/v2/disbursements/

The SDK automatically:

1. Fetches the RSA public key from /v1/rsa/encryption-keys
2. Encrypts the PIN using RSA/ECB/PKCS1Padding
3. Sends the encrypted PIN in the request body

Account

Balance Enquiry

$client->accountBalance();

Endpoint: GET /standard/v2/users/balance

Response:

{
    "data": {
        "balance": "37,600.00",
        "currency": "KES",
        "account_status": "Active"
    }
}

KYC

User Enquiry

$client->userKyc(['msisdn' => '712345678']);

Endpoint: GET /standard/v1/users/{msisdn}

Callbacks

Airtel sends transaction results to your callback URL as POST with JSON body:

{
    "transaction": {
        "id": "BBZMiscxy",
        "message": "Paid KES 5,000 to TECHNOLOGIES LIMITED...",
        "status_code": "TS",
        "airtel_money_id": "MP210603.1234.L06941"
    }
}

With auth enabled, a hash field is included for verification.

Error Codes