Avadapay-Burundi 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.

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.

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, 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,
  'customer_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

Payment process

• The customer initiates the payment via Card method on the merchant side
• The merchant asks for the customer's name, email and amount. This step is optional as this data may be stored in the merchant's system
• The merchant initializes the payment by redirecting the customer to the payment page
• The customer is prompted to provide the necessary details for payment: Name, Email, Amount
• The customer enters the card details
• The merchant receives notification of successful processing of the initiated payment and shows the Customer the success message

Creating a payment page

Valid only for 5002 provider_id

Payment Page allows to avoid the user interface and payment forms developing on the merchant’s side for card payment method. The Merchant only needs to redirect the Customer to the payment page at the link, where they can enter their specific data for the selected payment method. The payment page can be opened in a pop-up window, an iframe or a separate browser tab.
Merchant needs to append some required parameters to the query url, and some optional ones. The optional parameters allow merchant to pre-fill some data in the url, or let the customer enter it on the payment page themselves.
URL example with the pre-filled customer’s data https://hpp.avadapay.tech/example.php
After the redirect merchant needs to request the status of the initiated payment and also wait the callback with the final status. Code with signature generating for the redirect URL example:

<?php
// calculate signature
function calculateSignature($data, $secret)
{
$signed = '';

foreach ($data as $key => $value)
{
  $signed .= $key.$value;
}

 return strtolower(hash_hmac('sha512', $signed, $secret));
}


// create link with parameters
$domain = 'https://hpp.avadapay.tech';
$secretKey = "cf11635572c1e8d77297207152dc0791ad91f22b32d23c758ce3ba2637202ad8f7290ba41f2243cccf32edde1dfb8bf0f5dea62525309e293b3adb2c76eed6a5";

$data = [
 'merchant_id' => 'fffed61be9780b97c5e4c65e4e07bb6b',
 'order_id' => 'order3444298767545', // ONLY a-zA-Z0-9
 'country' => 'DRC',
 'amount' => 5,
 'currency' => 'USD',
 'provider_id' => 5002,
 'operation' => 'c2b',
 'type' => 'card',
 'callback_url' => 'https://my.callback.url',
 'return_url' => 'https://my.return.url',
 'email' => '',
 'name' => ''
];

$data['signature'] = calculateSignature($data, $secretKey);

$redirect_url = $domain . '?' . http_build_query($data); // you can use this link as a REDIRECT link, or as a source for an IFRAME tag

?>

<html>
<head>
 <title></title>
</head>

<body>
<iframe width="100%" height="100%" src="<?php echo $redirect_url; ?>"></iframe>
</body>
</html>

<?php
// or you can redirect user with that code: header('location: '.$redirect_url);

This payment page https://hpp.avadapay.tech/example.php is only a test example, it should be implemented on the merchant side with only the data that the user must enter. For example, it can only be email, name and amount.

After entering all the data correctly, the request will be sent to the system, and the user will be redirected to the web-page, where it is necessary to specify card details

Valid only for 5002 provider_id

Payment Page allows to avoid the user interface and payment forms developing on the merchant’s side for each payment method. The Merchant only needs to redirect the Customer to the payment page at [this link], where they can enter their specific data for the selected payment method. The payment page can be opened in a pop-up window, an iframe or a separate browser tab.
Merchant needs to append some required parameters to the query url, and some optional ones. The optional parameters allow merchant to pre-fill some data in the url, or let the customer enter it on the payment page themselves.
URL example with the pre-filled customer’s data https://hpp.avadapay.tech/example.php
After the redirect merchant needs to request the status of the initiated payment and also wait the callback with the final status. Status request and callbacks formats are described on the API Methods page.
Signature generating for the redirect URL example:

function calculateSignature($data, $secret)
{
    $signed = '';

    foreach ($data as $key => $value)
    {
        $signed .= $key.$value;
    }

    return strtolower(hash_hmac('sha512', $signed, $secret));
}

$data = [
  'merchant_id' => 'fffed61be9780b97c5e4c65e4e07bb6b',
  'order_id' => 'order_3444298767545',
  'country' => 'NGA',
  'currency' => 'NGN',
  'provider_id' => 2055,
  'operation' => 'c2b',
  'type' => 'bank_transfer',
  'callback_url' => 'https://my.callback.url'
];

$secretKey = "cf11635572c1e8d77297207152dc0791ad91f22b32d23c758ce3ba2637202ad8f7290ba41f2243cccf32edde1dfb8bf0f5dea62525309e293b3adb2c76eed6a5";

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

echo $signature;

// signature: 9826c5e89ff6386e7bbb5263a4fbd41ed35eb2fc7c58650be487db14f066b0a650b1980762575ad296b0cbac1745f6a5faeb64cacd2756ccff95b52ba08259d7
// result query: https://hpp.avadapay.tech/?merchant_id=fffed61be9780b97c5e4c65e4e07bb6b&order_id=order_3444298767545&country=NGA&currency=NGN&provider_id=2055&operation=c2b&type=bank_transfer&callback_url=https://my.callback.url&signature=9826c5e89ff6386e7bbb5263a4fbd41ed35eb2fc7c58650be487db14f066b0a650b1980762575ad296b0cbac1745f6a5faeb64cacd2756ccff95b52ba08259d7

This payment page https://hpp.avadapay.tech/example.php is only a test example, it should be implemented on the merchant side with only the data that the user must enter. For example, it can only be email, name and amount.

If the data is entered incompletely or incorrectly, the user will see the form:

After entering all the data correctly, the request will be sent to the system, and the user will be redirected to the web-page, where it is necessary to get bank details for payment

The parameters below will be obtained by a status query

Please note that it is necessary to assign the final transaction status only based on this parameter, the final statuses are 2, 3, 4 for the payment system (mobile money, card and bank transfers)

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

You can see this parameter in the callback

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.

In the case of POS terminals usage Merchant tech system receives callbacks after every successful operation performed on POS. The merchant_id parameter contains a unique identifier of the POS on which the operation was performed. The operation_type parameter contains a type of performed operation. So operations are initiated on POS terminals and information about successful ones is sent to the Merchant tech system with callbacks to configured URL.

You can route requests via "method_id" as an alternative to "provider_id" for more flexible routing. This feature is configured separately in agreement with technical support. Please note, In case of using "method_id" the "country" parameter is mandatory

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
}

254000000000 - 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.