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' => 'KE',
  'order_id' => 'order_3444298767545',
  'amount' => 1000,
  'currency' => 'KES',
  '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

Only this parameter determines the status of the transaction

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
}

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

Client-Side Transaction Flow

After a transaction request is initiated, the following process occurs on the client side. Once the transaction is created, the customer receives an SMS notification requesting transaction approval.

Example notification: You received a request of approval at 10:00 10/10/2025 for cash-out 1,000 FBu from Bitlipa Burundi, code: 101010. Fee: 0 FBu. This request will expire in 4 minutes. Please dial *163# and choose option 2 to approve it. TransCode: 23145678945000 Thank you.

The user needs to perform actions from SMS

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

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

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.

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

For 191, 192: For C2B payments you should send a customer email in the payment requests. Parameters extra->customer_email. Please see the example in the API Methods section.

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

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.

The flow is standard, no need to pass extra parameters.

2250000000000 - 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.
Current methods have additional instructions for C2B payments for the Customers during the payment. To make it successful you should display these instructions to the Customers after the payment initiated. The flow is this:
1. You call the standard C2B request payment_c2b and get the response (example in the API Methods section).
2. After successful response of accepting the transaction into processing (status:1), you call the status method.
3. You can get the link in the parameter extra->customer_redirect in the response of the status method. After receiving the link, you should redirect the customer to this page to confirm the transaction using OTP code

For 194: 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.

233000000000 - 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.
You can get the link in the parameter extra->customer_redirect in the response of the status method. After receiving the link, you should redirect the customer to this page to confirm the transaction using OTP code.

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.

22400000000 - This is the format of the phone number you have to send in the payment requests (country code is not required).

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

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.

254000000000 - 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 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 B2C payments provider 199 you should send a customer document type and document number in the payment requests. Parameters extra->customer_doc_type and extra->customer_doc_number. The customer_doc_type parameter can have one of the following values: * intl_passport - for International Passport * driving_license - for Driving License * national_id - for National ID

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.

22300000000 - 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. Parameters extra->customer_name. Please see the example in the API Methods section.

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.

Bank Transfer / Pay Attitude / OPay / Palmpay payment C2B (deposit) scenario:

• Customer initiates the payment via Bank Transfer/Pay Attitude/OPay/Palmpay 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
• Merchant initialises the payment, redirecting the Customer to the Payment Page. Redirect url and other details are described on the Payment Page section.
• Customer is requested to specify required data for the payment: Name, Email, Amount.
• Customer receives the Merchant’s Bank Account details.
• 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.

C2B query url parameters:

Pay Attitude / OPay / Palmpay payment B2C (withdrawal) scenario:

• Customer initiates the payment on Merchant side and set extra data of his Pay Attitude / OPay / Palmpay bank account
  • customer_name
  • customer_email
• Merchant sends request to the platform (POST payment_b2c)
• Customer receives funds to his bank account in Pay Attitude / OPay / Palmpay
• Merchant gets a callback (or requests the status) with the final state of the operation

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.

B2C Bank Transfer request example:

{
  "merchant_id":"e0fecd91fcb24f348048193b3fb34875ba3722b4",
  "order_id":"0900000001",
  "customer_id":"16280954971628095497",
  "amount":"100",
  "currency":"NGN",
  "provider_id":5008,
  "extra":{
    "customer_name":"Name Lastname"
    "bank_code":"000001"
  },
  "signature":"d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

For 5008 provider_id, there is an alternative way to make a c2b transaction request - directly through the API

{
  "merchant_id":"e0fecd91fcb24f348048193b3fb34875ba3722b4",
  "order_id":"0900000001",
  "customer_id":"0000000000",
  "amount":"100.00",
  "currency":"NGN",
  "provider_id":5008,
  "extra": {
    "customer_email": "[email protected]"
  },
  "signature":"d7d6d76b0e22c6f9d369fa6c24f107053d12bdgjkdgrjrdig445579c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

In the synchronized response, you will get the bank payment details that need to be share to the user. This is listed in the "extra" part

{
  "order_id": "90900000001",
  "transaction_id": "",
  "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": "2024-04-20 01:08:42.797957",
  "extra": {
    "transfer_amount": 100,
    "account_number": "4000000000",
    "bank_name": "Premium Trust Bank"
  },
  "confirm_type": 0
}

For other provider_id in the case of bank transfers, a payment page implementation is required

250700000000 - 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.
Current methods have additional instructions for C2B payments for the Customers during the payment. To make it successful you should display these instructions to the Customers after the payment initiated. The flow is this:
1. You call the standard C2B request payment_c2b and get the response (example in the API Methods section).
2. After successful response of accepting the transaction into processing (status:1), you call the status method.
3. You can get the link in the parameter extra->customer_redirect in the response of the status method. After receiving the link, you should redirect the customer to this page to confirm the transaction using OTP code

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.

221700000000 - 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.
Current methods have additional instructions for C2B payments for the Customers during the payment. To make it successful you should display these instructions to the Customers after the payment initiated. The flow is this:
1. You call the standard C2B request payment_c2b and get the response (example in the API Methods section).
2. After successful response of accepting the transaction into processing (status:1), you call the status method.
3. You can get the link in the parameter extra->customer_redirect in the response of the status method. After receiving the link, you should redirect the customer to this page to confirm the transaction using OTP code

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.

Bank Transfer C2B (deposit) scenario:

• Customer initiates the payment on Merchant side and set extra data
  • customer_email
• Merchant sends request to the platform (POST payment_c2b)
• Merchant gets the status of the operation (POST status) and gets extra parameters from the response
  • customer_redirect
• Merchant redirects the customer to the page from the customer_redirect url
• Customer confirm the operation on the page
• Merchant gets a callback (or requests the status) with the final state of the operation

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. In the "customer_id" merchant specifies the bank account. In the "extra" merchant specifies:
  • bank_code
  • customer_name
  • customer_email
  • customer_phone
  • customer_address

B2C Bank Transfer C2B (deposit) request example:

{
  "merchant_id":"e0fecd91fcb24f348048193b3fb34875ba3722b4",
  "order_id":"0900000001",
  "customer_id":"0000000000",
  "amount":"100",
  "currency":"ZAR",
  "provider_id":5012,
  "extra":{
    "customer_email": "[email protected]"
  },
  "signature":"d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

B2C Bank Transfer B2C (withdrawal) request example:

{
  "merchant_id":"e0fecd91fcb24f348048193b3fb34875ba3722b4",
  "order_id":"0900000001",
  "customer_id":"16280954971628095497",
  "amount":"100",
  "currency":"ZAR",
  "provider_id":5012,
  "extra":{
    "bank_code":"FNB",
    "customer_name":"Name Lastname",
    "customer_email":"[email protected]",
    "customer_phone":"0123456789",
    "customer_address":"Customer Address"
  },
  "signature":"d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

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 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 B2C payments providers 206, 207, 208, 209 you should send a customer document type and document number in the payment requests. Parameters extra->customer_doc_type and extra->customer_doc_number. The customer_doc_type parameter can have one of the following values: * intl_passport - for International Passport * driving_license - for Driving License * national_id - for National ID

256709000000 - 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.
Current methods have additional instructions for C2B payments for the Customers during the payment. To make it successful you should display these instructions to the Customers after the payment initiated. The flow is this:
1. You call the standard C2B request payment_c2b and get the response (example in the API Methods section).
2. After successful response of accepting the transaction into processing (status:1), you call the status method.
3. You can get the link in the parameter extra->customer_redirect in the response of the status method. After receiving the link, you should redirect the customer to this page to confirm the transaction using OTP code

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.

260976000000 - 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, the flow is standard, no need to pass extra parameters

For payments, the flow is standard, no need to pass extra parameters

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

The flow is standard, no need to pass extra parameters.

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.bitlipa.net/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' => 5008,
  '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.bitlipa.net/?merchant_id=fffed61be9780b97c5e4c65e4e07bb6b&order_id=order_3444298767545&country=NGA&currency=NGN&provider_id=5008&operation=c2b&type=bank_transfer&callback_url=https://my.callback.url&signature=9826c5e89ff6386e7bbb5263a4fbd41ed35eb2fc7c58650be487db14f066b0a650b1980762575ad296b0cbac1745f6a5faeb64cacd2756ccff95b52ba08259d7

This payment page https://hpp.bitlipa.net/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