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'

Malawi

Tanzania

Zambia

Quick start for working with multi-step payments

A simple way to start payments without worrying about required fields — the system will guide you if anything is missing.

Depending on the data you provide, the payment will either start immediately, request missing information, or require confirmation (e.g. OTP or email). You can use it in 2 ways:

1. API only (host-to-host) - mutli-step flow, however it maybe more complex to implement and requires more API calls.
2. Web payment page (redirect method) - the page will handle the flow for you. This is the recommended way to implement multi-step payments, as it requires minimal API calls and the page will handle all the steps for you.

Option 1: All data provided

INIT with data → status: 1 or 2 → Done

Option 2: Missing data (Universal Flow)

INIT without data → status: 8
    ↓
STATUS request → receive action.fields (list of required fields)
    ↓
STATUS with data → status: 1 → Payment initiated

Option 3: Confirmation required (Multi-Step)

INIT with data → status: 1 (OTP sent)
    ↓
STATUS with OTP → status: 2 (success)

Each status tells you exactly what is happening with the payment and what to do next.

Use INIT to start a payment and STATUS to check or continue it.

INIT:

POST /{merchant_hash}/payment_c2b
POST /{merchant_hash}/payment_b2c

STATUS:

POST /{merchant_hash}/status

These are the minimum fields needed to start and manage a payment.

INIT request:

{
  "merchant_id": "string",
  "order_id": "string",
  "amount": "string",
  "currency": "string",
  "customer_id": "string",
  "provider_id": "integer",
  "signature": "string"
}

STATUS request:

{
  "merchant_id": "string",
  "order_id": "string",
  "signature": "string"
}

Additional fields you can use to enhance or complete the payment flow.

Optional (INIT):

• extra — additional parameters
• callback_url — URL for notifications

Optional (STATUS):

• extra — missing data or OTP codes

Example of how the system requests and processes missing data.

1. INIT without email:

{"order_id": "ORDER-1", "amount": "100", "currency": "NGN", "provider_id": 170}

Response: status: 8

2. STATUS (get required fields):

{"order_id": "ORDER-1"}

Response: action.fields: {customer_email: {...}}, action.errors: {customer_email: ["..."]}

3. STATUS with data:

{"order_id": "ORDER-1", "extra": {"customer_email": "test@example.com"}}

Response: status: 1 (initiated)

Example of a payment that requires user confirmation.

1. INIT with data:

{"order_id": "ORDER-2", "amount": "500", "currency": "KES", "extra": {"phone": "254712345678"}}

Response: status: 1 + provider_result.message: "OTP sent"

2. STATUS with OTP:

{"order_id": "ORDER-2", "extra": {"otp": "123456"}}

Response: status: 2 (success)

Key behaviors to understand, to avoid confusion during integration:

✅ Data from INIT is stored — no need to resend it

✅ STATUS takes priority — can temporarily override saved data, but changes won't be persisted

✅ Validation errors don't fail the operation — it stays in status: 8; fix the data and resubmit

✅ action.errors are arrays — use errors[field][0] for the first message

✅ Mechanisms work together — Universal Flow + Multi-Step can be combined

Mistakes that can lead to incorrect handling of the flow:

❌ Treating result.code === 0 for status: 8 as a success indicator

❌ Expecting the action block in the INIT response

❌ Parsing action.errors[field] as a string (it's an array!)

❌ Trying to modify saved data via STATUS

Gate 8** (via payment page)

C2B

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b)
3. Merchant gets link for redirect in pp_url in the payment response
4. Merchant redirects Customer to payment page
5. Customer makes a payment on the page
6. Merchant gets a callback with the final state of the operation

Gate 5** (via payment page)

C2B

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b)
3. Merchant gets link for redirect in pp_url in the payment response
4. Merchant redirects Customer to the payment page
5. Customer makes a payment on the page
6. Merchant gets a callback 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. Merchant gets link for redirect in pp_url in the payment response
4. Merchant redirects Customer to the payment page
5. Customer chooses bank on the page
6. Merchant gets a callback with the final state of the operation

Response example

{
  "order_id": "example_order_id_***",
  "transaction_id": "",
  "transaction_ref": "",
  "status": 8,
  "result": {
    "code": 0,
    "message": "request error"
  },
  "provider_result": {
    "code": -8888,
    "message": ""
  },
  "service_id": 1,
  "service_version": "1.03/1.14|1.0/2.0|1.0/1.0|1.01/1.0|1.01/2.0||1.02/1.27",
  "service_date_time": "2026-04-09 14:08:48.535688",
  "pp_url": "https://pp.domain.example/cdeffe6210c7fdc7402c13b210dbd8ddec02da0c/****",
  "confirm_type": 0
}