Payment API Gateway (v5.7.2)

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.

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters from the payload are included in the order they were sent. The parameter signature should be excluded, of course, and added to the payload after generating.

Note: to generate a correct signature you need a secretKey received with other credentials.

PHP example

function calculateSignature(array $data, string $secretKey, string $currentParamPrefix = '', int $depth = 16, int $currentRecursionLevel = 0 ): string
{
    if ($currentRecursionLevel >= $depth) {
        throw new Exception('Recursion level exceeded');
    }

    $stringForSignature = '';
    foreach ($data as $key => $value) {
        if (is_array($value)) {
                $stringForSignature .= calculateSignature(
                $value,
                $secretKey,
                "$currentParamPrefix$key.",
                    $depth,
                $currentRecursionLevel + 1
            );
      } else if ($key !== 'signature') {
                $stringForSignature .= "$currentParamPrefix$key" . $value;
      }
   }

    if ($currentRecursionLevel == 0) {
      return strtolower(hash_hmac('sha512', $stringForSignature, $secretKey));
    } else {
      return $StringForSignature;
    }
 }

$postData = [
  'merchant_id' => 'fffed61be9780b97c5e4c65e4e07bb6b',
  'provider_id' => 14,
  'client_id' => '080000000',
  'country' => 'ZM',
  'order_id' => 'order_3444298767545',
  'amount' => 1000,
  'currency' => 'ZMW',
  'callback_url' => 'https://my.callback.url'
];

$secretKey = "cf11635572c1e8d77297207152dc0791ad91f22b32d23c758ce3ba2637202ad8f7290ba41f2243cccf32edde1dfb8bf0f5dea62525309e293b3adb2c76eed6a5";

$signature = calculateSignature($postData, $secretKey);

$postData['signature'] = $signature;

Examples in other languages are available on request

The parameters below will be obtained by a status query

The result of the query processing by the system

The parameters below will be obtained by a status query

Depending on the type of request you may see the following code

You can see this parameter in the callback

Responses for confirmation requests have the same format as original operation responses.

C2b transaction status is sent via callback because it needs a confirmation by client done asynchronously. Usually the callback should be sent in 2-3 minutes maximum. In case of missing callback there is a way to get the transaction status using API method status. It needs the order ID as an parameter and returns a status of the performed transaction.

Response for callback

Payment gateway considers the Merchant system response as successful if HTTP 200 was received.

During tests runs, using 14 provider ID (simulator) the callback is not returned and the transaction remains in the "in progress" status and if successful you will see in the response

{
  "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
}

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

For C2B payments, you should send a customer full name in the payment requests. Parameter extra->customer_name. Please see the example in the API Methods section.

The flow is standard, no need to pass extra parameters

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

For 5064:

B2C:

1. Customer initiates the payment via Bank Transfer method on the Merchant’s side.
2. Merchant receives the list of available banks and its codes via get banks API Method.
3. Customer selects on the Merchant’s side the Bank and specifies his recipient’s bank account.
4. Merchant sends a B2C request to the system. In the "extra" merchant specifies the bank code (parameter bank_code) and customer name (parameter customer_name). In the "customer_id" merchant specifies the bank account.

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

For C2B and B2C payments you should send a customer full name and customer email in the payment requests. Parameters extra->customer_name and extra->customer_email. Please see the example in the API Methods section.

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

For C2B and B2C payments you should send a customer full name and customer email in the payment requests. Parameters extra->customer_name and extra->customer_email. Please see the example in the API Methods section.

For 2128 Provider ID Wave after successful response of accepting the transaction into processing (status:1), you call the status method. In the response you get the URL in the parameter extra->customer_redirect which you have to redirect the Customer.

For 2127 Provider ID Orange the Customer must create an OTP code on the Operator side. This OTP must be sent in payment requests. Parameter extra->otp. User should dial #144*82# (May change on the method side, information is updated periodically)

For 2406,2408:

C2B

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

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

For 2407:

C2B

1. Customer initiates the payment on Merchant side and set extra data customer_name and customer_email
2. Merchant sends request to the platform (POST payment_c2b)
3. Merchant gets the status of the operation (POST status) and gets extra parameters from the response customer_redirect
4. Merchant redirects the customer to the page from the customer_redirect url
5. Customer gets SMS\WhatApp message with OTP
6. Customer confirm the operation by OTP on the page
7. Customer gets push from operator and confirm the operation
8. 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 customer_name
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to his mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 2409:

C2B:

1. Customer initiates the payment on Merchant side and set extra data customer_name and customer_email
2. Merchant sends request to the platform (POST payment_c2b)
3. The merchant gets a redirect_url
4. Merchant redirect Customer to provider payment page
5. Customer makes a payment on the page
6. 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 customer_name
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to his mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 2406, 2407, 2408, 2409:

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

For 824:

The payment flow is standard.

For 5063:

B2C:

1. Customer initiates the payment via Bank Transfer method on the Merchant’s side.
2. Merchant receives the list of available banks and its codes via get banks API Method.
3. Customer selects on the Merchant’s side the Bank and specifies his recipient’s bank account.
4. Merchant sends a B2C request to the system. In the "extra" merchant specifies the bank code (parameter bank_code) and customer name (parameter customer_name). In the "customer_id" merchant specifies the bank account.

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

For C2B payments, you should send a customer full name and customer email in the payment requests. Parameters extra->customer_name and extra->customer_email. Please see the example in the API Methods section.

For 748, 749, 750: For C2B payments the flow is standard. For B2C payments, you should send a customer full name in the payment requests. Parameter extra->customer_name. Please see the example in the API Methods section.

For 5045 (only B2C): You should set account number as customer_id and send customer full name and bank BIC("Bank Identifier Code", ask your bank) in the payment request. Parameters extra->customer_name and extra->bic. Please see the example in the API Methods section.

For 748, 749, 750:

Bank Transfer / Pay Attitude / OPay / Palmpay / Card payment C2B (deposit) scenario: * Customer initiates the payment via Bank Transfer/Pay Attitude/OPay/Palmpay/Card method on the Merchant’s side. * Merchant requests Customer’s Name, Email and Amount. This step is optional, as this data may be stored in the merchant's system

```
{
  "provider_id": 2133,
  "merchant_id": "cd4645yh720cc83gh5443d2bd6424b",
  "customer_id": "2349061239999",
  "order_id": "1234567890",
  "country": "NG",
  "amount": "10000",
  "currency": "NGN",
  "callback_url": "https://example.com",
  "email": "test@gmail.com",
  "name": "John Christopher",
  "signature": "3bca46363467e8683d73dbd8e564fa93596f5d4fede1f252d2c875597bf6945730fbbc8da66a4100fe60d"
}

• After successful response of accepting the transaction into processing (status:1), you call the status method. In the response you get the instructions in the parameter extra which you have to show to the Customer.\

Customer_message example:

{
  "order_id": "1234567890",
  "transaction_id": "0987654321",
  "transaction_ref": "",
  "status": 1,
  "result": {
    "code": 0,
    "message": "OK"
  },
  "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": "2025-05-25 15:15:55.050505",
  "extra": {
    "account_name": "EXAMPLE TECH – LTD",
    "account_number": "1597534560",
    "bank_name": "GLOBUS BANK",
    "transfer_amount": "10000"
  },
  "confirm_type": 0
}

For 2137, 2138, 2139 provider_id instead of the bank details a link will be returned in the customer_redirect parameter to which the user should be redirected

• Customer opens his Bank Application and makes the transfer to the corresponding account
• Merchant receives the notification, that initiated payment is processed successfully and shows to the Customer a success message.

Please note that on channels 2133, 2134, 2135, 2136 users have the opportunity to pay the wrong amount using the details, as well as make payments several times. To avoid discrepancies in amounts, long processing of transactions on these channels and other difficulties, we recommend that you create an information board for users. In the text, please warn that the details are used only once and only for the stated amount. In other cases, the transaction processing time may take a very long time. For example, to be convincing, you can warn about the high probability of losing funds

Bank Transfer B2C (withdrawal) scenario:

• Customer initiates the payment via Bank Transfer method on the Merchant’s 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 his recipient’s bank account.
• Merchant sends a B2C request to the system. Format is described on the API Methods page. In the "extra" merchant specifies the bank code (parameter bank_code) and customer name (parameter customer_name). In the "customer_id" merchant specifies the bank account.

Passing bank_code in the request is relevant only for 2133 and 2137 provider_id

B2C Bank Transfer request example:

{
  "merchant_id":"cd4645yh720cc83gh5443d2bd6424b",
  "order_id":"1234567890",
  "customer_id":"16280954971628095497",
  "amount":"1000",
  "currency":"NGN",
  "provider_id":2133,
  "extra":{
    "customer_name":"John Christopher",
    "customer_email": "test@gmail.com",
    "bank_code":"000001"
  },
  "signature":"d7d6d76b0e22c6f9d36f107053d12bfd248t498ghoshgos93f9379c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

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

For 874, 875, 876:

C2B:

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST payment_c2b)
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 withdrawal on Merchant side
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to his mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 254, 9115:

C2B:

1. Customer initiates the payment on Merchant side and set extra data a. customer_name b. customer_email
2. Merchant sends request to the platform (POST payment_c2b)
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:

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

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

For C2B payments, the flow is standard, no need to pass extra parameters For B2C payments, you should send a customer full name in the payment requests. Parameter extra->customer_name. Please see the example in the API Methods section.