Payment API Gateway (template version) (5.7.3)

This API is part of the our ecosystem. It allows you to make payments, find out the status of transactions and much more. Here you will find the latest documentation on setting up your solution.

Important: all Mobile Money C2B/B2C payments must be processed only with verified phone numbers.

Before proceeding with the request, please confirm that the phone number:

• has been previously verified by the customer;
• matches the number stored in your database.

This requirement is essential for minimizing fraud risk.

Use the test provider below during sandbox integration. Note that responses from the simulator do not include a callback — transactions remain in the "in progress" state.

Example response from test provider (ID: 14)

When using the simulator provider, a successful request returns the following structure. Note that status: 1 means "in progress" — use the /status method to poll for updates.

{
  "order_id": "54321",
  "transaction_id": "12345",
  "transaction_ref": "",
  "status": 1,
  "result": {
    "code": 0,
    "message": "OK"
  },
  "provider_result": {
    "code": -8888,
    "message": "Good"
  },
  "service_id": 1,
  "service_version": "1.03/1.14|1.0/1.26|1.0/1.0|1.01/1.01|1.01/1.01||1.01/1.27",
  "service_date_time": "2023-05-15 10:00:00.000000",
  "confirm_type": 0
}

To generate a correct signature, use your secretKey and apply recursive HMAC SHA-512 hashing on all request fields, excluding the signature field itself.

Example in PHP:

function calculateSignature(array $data, string $secretKey, string $prefix = '', int $depth = 16, int $level = 0): string {
    if ($level >= $depth) {
        throw new Exception('Too deep');
    }

    $result = '';
    foreach ($data as $key => $value) {
        if ($key === 'signature') continue;
        $fullKey = $prefix . $key;
        if (is_array($value)) {
            $result .= calculateSignature($value, $secretKey, $fullKey . '.', $depth, $level + 1);
        } else {
            $result .= $fullKey . $value;
        }
    }

    return $level === 0
        ? strtolower(hash_hmac('sha512', $result, $secretKey))
        : $result;
}

$postData = [
    'merchant_id' => 'fffed61b...',
    'provider_id' => 10,
    'client_id' => '254000000000',
    'country' => 'KE',
    'order_id' => 'order_3444298767545',
    'amount' => 1000,
    'currency' => 'KES',
    'callback_url' => 'https://my.callback.url'
];

$secretKey = 'cf11635572...';
$postData['signature'] = calculateSignature($postData, $secretKey);

Operation type codes visible in callbacks:

Transaction status is sent via callback because it requires asynchronous confirmation from the client system. Usually the callback should arrive within 2–3 minutes.

If no callback is received, use the status API method to check transaction result. Successful callback = HTTP 200 from merchant'

242000000000 - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids that do not require OTP or Redirect: 9525

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Congo-Brazzaville limits

254000000000 - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids that do not require OTP or Redirect: 9515, 9574

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Kenya limits

221000000000 - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids redirecting to Provider payment pages: 9259, 9322

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Merchant gets the status of the operation and extra data customer_redirect
   Example of a user redirect link:

"extra": 
{
"customer_redirect": "https://checkout.provider.com/202511131111MqKRft39377/pay"
}, 

4. Merchant redirect Customer to provider page
5. Customer confirms the payment on the provider page
6. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Senegal Limits

255000000000 - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids that do not require OTP or Redirect: 9369, 9370, 9376

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Tanzania Limits

The phone number must consist of exactly 8 numeric digits in the following format: 228XXXXXXXX (3-digit country code 228 + 8-digit local phone number). Example: 22890123456 No spaces, plus signs, separators, or other characters are permitted.

C2B for Provider_ids that do not require OTP or Redirect: 9526, 9527

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Note deposits and withdrawals are made in multiples of 5.

Togo limits

2250XXXXXXXXX - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids that do not require OTP or Redirect: 9260, 9261, 9516

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

C2B for Provider_ids that require a OTP: 9324

1. Customer create OTP code on ussd_code #144*82#
2. Customer initiates the payment on Merchant side
3. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

Example Request:

  {
  "merchant_id": "your merchant id",
  "customer_id": "2250705145655",
  "order_id": "test_161225_01_1",
  "amount": "1111",
  "currency": "XOF",
  "country": "BF",
  "callback_url": "your callback url",
  "provider_id": "9324",
  "signature": "1c594d338bc3f413bd61cb97d697e98ad5772071da533",
  "extra": {
    "otp": "7777"
  },
  }

4. Operator debits funds from customer mobile number
5. Merchant gets a callback (or requests the status) with the final state of the operation

C2B for Provider_ids redirecting to Provider payment pages: 9262, 9519

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Merchant gets the status of the operation and extra data customer_redirect
   Example of a user redirect link:

"extra": 
{
"customer_redirect": "https://checkout.provider.com/202511131111MqKRft39377/pay"
}, 

4. Merchant redirect Customer to provider page
5. Customer confirms the payment on the provider page
6. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Ivory Coast Limits

233000000000 - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids that do not require OTP or Redirect: 9343, 9344

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Ghana limits

260000000000 - This is the format of the phone number you have to send in the payment requests.

C2B for Provider_ids that do not require OTP or Redirect: 9341, 9342

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) and set extra data depending on the provider_id:

3. Customer gets push from operator and confirm the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C flow is the same for everyone, please specify the required extra parameters

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) and set extra data depending on the provider_id:

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Zambia limits