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

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
}

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

Client-Side Transaction Flow

Une demande d’approbation de transaction a été initiée. Pour la finaliser, composez *163# et sélectionnez l’option 2 dans les 4 prochaines minutes. La transaction sera effectuée avec succès uniquement après votre approbation.

Separate functionality. This section documents the Backoffice API (bo-api.avadapay.tech) — a different API from the merchant Payment API documented above. It is not part of the payment_c2b / payment_b2c / status integration and uses its own base URL and authentication (OAuth 2.0 Client Credentials, not request signatures).

1. Purpose

This feature gives Backoffice entities programmatic access to the BO API through the OAuth 2.0 Client Credentials Grant, decoupled from any interactive user session.

2. Process overview

The flow has three sequential stages:

1. Generate credentials — create a client_id / client_secret pair bound to a specific entity, through the Backoffice UI (see Getting credentials).
2. Get an access token — exchange the pair for a JSON Web Token (JWT) by calling /oauth/token (see Authentication).
3. Make an authorized request — use the token in the Authorization header to call protected BO API endpoints.

The access token's lifetime is 1800 seconds (30 minutes). Once it expires, request a new one using the same credentials.

3. Generating credentials

3.1 Steps

1. Open My Profile in the Backoffice UI.
2. In the Roles & Access block, select the card for the entity you need.
3. In the Backoffice API Access section, click Generate API credentials.
4. Save the Client ID and Client Secret shown in the dialog.

3.2 Important notes

• The Client Secret is shown once, in plaintext, immediately after generation. It cannot be retrieved again in plaintext afterwards.
• If a pair has already been generated for the entity, the control becomes Regenerate Secret (see section 4).

3.3 Assigning a role for API access

• For the issued credentials to grant access to protected BO API endpoints, the entity must have at least one role flagged for API access (is_api_user). The roles available to the entity for API access are listed in the access token under api_user_roles (see section 5.4).
• Role assignment is done by the partner's administrator. If no eligible role is assigned, requests to protected endpoints are rejected with 403 no_api_user_roles (see Errors).

4. Regenerating credentials

4.1 Steps

1. On the entity's card, click Regenerate Secret.
2. Confirm the action in the dialog.
3. Save the new Client Secret shown in the dialog.

4.2 Important notes

• The Client ID stays the same across regenerations.
• The previous Client Secret is invalidated immediately once the action is confirmed.
• Access tokens issued before the regeneration remain valid until they expire (expires_in) — regenerating does not immediately revoke tokens already issued.

Warning. Regenerating credentials for an entity used by a live integration will break that integration until the consumer updates its stored credentials.

5. Getting an access token

5.1 Request

POST /api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}

The same parameters can be sent as application/json.

5.2 Example

curl -X POST 'https://bo-api.avadapay.tech/api/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>'

5.3 Response

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 1800
}

This grant does not issue a refresh token. Once the token expires (expires_in), repeat the request above with the same client_id and client_secret to get a new one. Re-requesting a token needs no additional confirmation and can be done as often as needed, within rate limits (429 when exceeded).

5.4 Token structure

The access token carries an entities claim — an array with a single element, corresponding to the entity the credentials were issued for:

The token also carries an auth_method claim set to client_credentials, marking how the token was obtained.

6. Making authorized requests

6.1 Request

GET /api/v1/{endpoint}
Authorization: Bearer {ACCESS_TOKEN}

6.2 Example

curl -X GET 'https://bo-api.avadapay.tech/api/v1/merchant-accounts?clients[]=<CLIENT>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

6.3 Scope

The scope of the request is resolved automatically from the entity carried in the token. There's no need to pass X-ENTITY-TYPE / X-ENTITY-ID headers.

Requesting data belonging to an entity other than the one in the token is rejected (see Errors).

Send requests only to https://bo-api.avadapay.tech: a token used on another partner's domain is rejected with 403 entity_domain_mismatch.

7. Response code reference

Examples:

{ "error": "out_of_entity_scope" }

{
  "message": "The currency field must be an integer.",
  "errors": { "currency": ["The currency field must be an integer."] }
}

8. Additional notes

Access control is enforced at independent levels: the request domain must belong to the token's partner, a role check (api_user_roles) against the endpoint's requirements, and an entity-scope check. Passing one check doesn't guarantee passing the others.

9. Merchant balances

9.1 Purpose

Unified endpoint for retrieving merchant balances. Replaces the five separate balance endpoints previously used per entity type. Carries no query logic of its own on the BO API side — the request is proxied to the Balance Service as-is.

9.2 Request

GET /api/v1/merchant-accounts
Authorization: Bearer {ACCESS_TOKEN}

Query parameters

9.3 Scope resolution

The scope of the query is determined by the entity type carried in the access token:

9.4 Response

{
  "accounts": [
    {
      "country": "KEN",
      "country_name": "Kenya",
      "currency": 404,
      "public_id": "1011104044040000000000XXXXXXXXXXXXXXXXXX",
      "total_amount": "1500.00",
      "hold_amount": "200.00",
      "available_amount": "1300.00",
      "client": 3017,
      "merchant_name": "Demo Merchant",
      "branch": 223,
      "payment_method": 1,
      "payment_method_name": "M-Pesa",
      "provider_id": 9052,
      "provider_id_name": "9052-M-Pesa-KEN"
    }
  ]
}

The date field is present in the response root only when the corresponding query parameter was supplied. Field relationship: available_amount = total_amount − hold_amount.

Note. country carries the short country code; the full name is in the separate country_name field. provider_id carries the Provider ID (gate), with its name in provider_id_name; the naming format depends on the specific provider integration.

9.5 Example requests

No parameters (merchant_brand entity):

curl -X GET 'https://bo-api.avadapay.tech/api/v1/merchant-accounts' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

The query is automatically scoped to the entity's own client.

Explicit clients[] and date:

curl -X GET 'https://bo-api.avadapay.tech/api/v1/merchant-accounts?clients[]=1225&date=2026-09-10' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Requesting another merchant's data (merchant_brand entity):

curl -X GET 'https://bo-api.avadapay.tech/api/v1/merchant-accounts?clients[]=3024' \
  -H 'Authorization: Bearer <ACCESS_TOKEN_FOR_A_DIFFERENT_MERCHANT>'

Response: 400 {"message": "clients do not match current merchant brand."}.