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' => 10,
  'client_id' => '080000000',
  'country' => 'KE',
  'order_id' => 'order_3444298767545',
  'amount' => 1000,
  'currency' => 'CDF',
  '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

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
}

C2B for Provider_ids redirecting to Provider payment pages: 9985

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

Argentine limits

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

C2B for Provider_ids redirecting to Provider payment pages: 9954

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:

   Provider_id	No Extra Required	customer_email	customer_name	customer_ip	return_url
   9954			*

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

C2B for Provider_ids payment using QR code: 9954

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:

   Provider_id	No Extra Required	customer_email	customer_name	customer_ip	return_url
   9954			*

3. Merchant gets the status of the operation and extra data qr Example of a user redirect link:

"extra": 
{
"qr": "000201010211212.pix2561qrcode.avivpay.com.br/v1/1c1231232"
}, 

4. Merchant display Customer to QR-code
5. Customer confirms the payment using a QR code
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:

   Provider_id	No Extra Required	customer_email	customer_name	return_url	customer_doc_number
   9954			*		*

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

C2B for 9405

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request) where customer_id should be customer phone number and set extra data:

• customer_name

• customer_email

• customer_doc_type (Example: "customer_doc_type": "CPF")

• customer_doc_number (Should be customer CPF number)

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 redirects a 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 for 9405

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST B2C request) where customer_id should be customer CPF number and set extra data:

• customer_name
• customer_email
• customer_doc_type (Example: "customer_doc_type": "CPF")
• customer_doc_number (Should be customer CPF number)
• customer_phone

3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Brazil limits

C2B for Provider_ids redirecting to Provider payment pages: 9965, 9964, 9963, 9962

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:

   Provider_id	No Extra Required	customer_email	customer_name	customer_doc_type	return_url
   9965, 9964, 9963, 9962		*	*	*

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

    Provider_id	bank_code	customer_acc_number	customer_doc_number	customer_name	customer_email	customer_acc_type	customer_doc_type
    9961	*	*	*	*	*	*	*

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

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

Chile

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

C2B for Provider_ids redirecting to Provider payment pages: 9988

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:

   Provider_id	No Extra Required	customer_email	customer_name	customer_doc_type	return_url	customer_acc_number	customer_doc_number
   9988		*	*	*		*	*

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 Payments for universal bank transfer

1. Customer initiates the withdrawal on Merchant 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 their recipient’s bank account

4. 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:

   Provider_id	bank_code	customer_acc_number	customer_doc_number	customer_name	customer_email	customer_doc_type
   10282	*	*	*	*	*	*

5. Platform transfers funds to the Customer's bank account

6. Merchant gets a callback (or requests the status) from the platform with the final state of the operation

Columbia

00000000000 - this is the format of the phone number/account id you have to send in the payment requests.

C2B for Provider_ids redirecting to Provider payment pages: 10324, 10325, 10326, 10327

1. Customer initiates the payment on Merchant side
2. Merchant sends request to the platform (POST C2B request), no extra data required
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), no extra data required
3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

Egypt limits