Payment API Gateway (test version for Sergei) (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'

Malawi

Tanzania

Zambia