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'

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

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

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.

Benin limits

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

C2B:

• The customer initiates the payment on the merchant side and sets extra data depending on the provider_id

Regardless of the extra parameters used for these methods, we strongly recommend specifying at least: customer_email, customer_name and user phone number in the customer_id parameter of the main request body to unify the solution.

• Merchant sends C2B request to the platform
• Platform returns temporary bank account details in the API response in status request (extra parameters)
  • account_number
  • bank_name
  • account_name
    Please note that the exact parameter names may differ slightly depending on the bank, so it is correct to display the entire extra section from the status request result to the user, for example:

"extra": 
{
"account_name": "MONEY TECH – LTD",
"account_number": "9999793854",
"bank_name": "GLOBAL BANK",
"transfer_amount": "1550"
}, 

• Merchant displays these bank details to the Customer.
• Customer makes a bank transfer to the provided details from their wallet.
• Merchant gets a callback with the final state of the operation once the funds are received.

B2C Payments for universal bank transfer

• Customer initiates the withdrawal on Merchant side.
• Merchant receives the list of available banks and its codes via get banks API Method
• Customer selects on the Merchant’s side the Bank and specifies their recipient’s bank account
• Merchant sends B2C request to the platform where customer_id is customer bank account number and sets extra data
  • bank_code got from get banks API Method response
  • Extra parameters used:

Regardless of the extra parameters used for these methods, we strongly recommend specifying at least: customer_email, customer_name to unify the solution.

• Platform transfers funds to the Customer's bank account
• Merchant gets a callback from the platform with the final state of the operation

Provider_ids redirecting to Provider payment pages: 9612, 9613

C2B:

1. Customer initiates the payment on Merchant side
2. Merchant sends C2B request to the platform where customer_id should be phone number
   In the extra parameters are specified:

• customer_name

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 makes a payment from their bank using the payment details
6. Merchant gets a callback (or requests the status) with the final state of the operation

B2C Opay (9612) Palmpay (9613):

1. Customer initiates the payment on Merchant side and set extra data of their OPay, PalmPay or Pay Attitude bank account where customer_id is bank account
   In the extra parameters are specified:

• customer_name

2. Merchant sends B2C request to the platform
3. Customer receives funds to their bank account in OPay or Palmpay
4. Merchant gets a callback (or requests the status) with the final state of the operation

Nigeria limits

221000000000 - 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: 9522

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 redirecting to Provider payment pages: 9259, 9322, 9599, 9521

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, 9630

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, 9585

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