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'

Senegal

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

For 9259:

C2B

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

• return_url

3. Merchant requests the transaction status (POST payment_status)
4. Merchant gets a customer_redirect in the status response
5. Merchant redirects a customer to provider payment page
6. Customer makes a payment on the page
7. Merchant gets a callback (or requests the status) with the final state of the operation

B2C

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 9322:

C2B

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b)
3. Merchant requests the transaction status (POST payment_status)
4. Merchant gets a customer_redirect in the status response
5. Merchant redirects a customer to provider payment page
6. Customer makes a payment on the page
7. Merchant gets a callback (or requests the status) with the final state of the operation

B2C

1. Customer initiates the payment on Merchant side and set extra data:
   • return_url
2. Merchant sends request to the platform (POST payment_b2c)
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

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

For 9260:

C2B

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b) and set extra data:
   • return_url
3. Customer gets push from operator and confirms the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile wallet
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 9261:

C2B

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b) and set extra data:
3. Customer gets push from operator and confirms the operation
4. Merchant gets a callback (or requests the status) with the final state of the operation

B2C

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile wallet
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 9262:

C2B

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b)
3. Merchant requests the transaction status (POST status)
4. Merchant gets a customer_redirect in the status response
5. Merchant redirects a customer to provider payment page
6. Customer makes a payment on the page
7. Merchant gets a callback (or requests the status) with the final state of the operation

B2C

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation