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

What is Safaricom Paybill?

The Pay Bill service is a mobile payments service that allows your organization to collect money on a regular basis from your customers through M-PESA.

How does Safaricom Paybill work?

• Client goes to M-PESA on the client’s phone SIM Menu or uses M-PESA app.
• Client selects Payment Services.
• Client chooses PayBill and enters Safaricom PostPay Bill number / ShortCode (XXXXXX).
• Client enters the mobile number to make payment.
• Client inputs the amount client wishes to pay.
• In the app, Client may indicate his account/wallet number to the Account number field.
• Client keys in client’s M-PESA PIN.
• Client confirms details are correct and presses OK.
• Safaricom sends a callback to us about this transaction.
• We sends a callback to Merchant about this transaction.
• Transaction information displays on Safaricom Backoffice.
• Transaction information displays on our Backoffice.

Paybill callback URL

The merchant should provide their callback URL to the our tech team to receive information about such transactions.

Paybill callback format

Paybill callback example

{
 "merchant_id": "555222hhh555fff999rrr444qqq222",
 "operation_type": 32,
 "customer_id": "2547 ***** 000",
 "amount": 100,
 "currency": "KES",
 "order_id": "2023-03-15-15-25-12-255432",
 "transaction_id": "",
 "transaction_ref": "RBQ0000000",
 "status": 2,
 "provider_id": 40,
 "destination_id": "7000000",
 "result": {
     "code": 0,
     "message": "OK"
 },
 "provider_result": {
     "code": 0,
     "message": ""
 },
 "service_id": 1,
 "service_version": "1.03/1.0|1.0/1.26|1.0/1.0|1.01/1.0|1.01/1.0||1.01/1.27",
 "service_date_time": "2023-03-03 13:33:33.333333",
 "extra": {
     "BillRefNumber": "555555555",
     "FirstName": "ALEX",
     "MiddleName": "",
     "LastName": ""
 },
 "signature": "sdfkdfpogu9550603etgkdopftege34t0i5rggdftoe0tgskguo09w6t"
     }

Paybill Validation

The parameter that is directly involved in the validation is PayBillRefNumber

To be able to pre-verify payments via paybill, the Merchant needs to add another URL in his system to which requests will be sent (the same as on paybill callback. This URL must be reported to us. The Merchant will be able to verify the validity of this request (for example, the existence of the customer's account number in the Merchant's system) and send a response to it. A response with the code=0 means that the validation has been completed and the payment can be credited; any other response means that the transaction should not be completed, and a request to cancel the payment will be sent to Safaricom. In order for the response to be counted as confirmation, it has to contain a JSON with "code":0. Any other data will be ignored.

Example:

{"code":0,"status":"ok"}

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.

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.

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
}

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

For 2414, 2415:

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 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 extra->customer_name
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 2425:

• 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 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 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 their 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 their 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 and customer_email
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 2406, 2407, 2408, 2409:

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

Please note that on channels 2442, 2443, 2444, 2445, users have the opportunity to pay the wrong amount using their details, as well as make payments several times. To avoid discrepancies in amounts, lengthy processing of transactions on these channels and other difficulties, we recommend that you create an information board for users. Please warn in the text 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 if these rules are violated

Flow for 2441 works only through the payment page, a description of the payment process and integration implementation is described in the payment page section

Flow for bank transfer

There are two methods for performing bank transfers in the C2B format: either by obtaining the account details directly or by using a link to the provider’s payment page. In both cases, retrieving the payment information requires requesting the status following the synchronous API response. These methods are described in detail in the sections below

Provider_ids redirecting to Provider payment pages: 2446, 2453, 2452

C2B:

1. Customer initiates the payment on Merchant side
2. Merchant sends C2B request to the platform where customer_id should be phone number
   In the extra parameters are specified:
   • customer_email
   • customer_name
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 makes a payment from their bank using the payment details
6. Merchant gets a callback (or requests the status) with the final state of the operation

Provider_ids Returning Bank Details for C2B Payments: 2442, 2443, 2444, 2445, 2447, 2448, 2449, 2450, 2451

The key characteristic of this payment type is that for C2B payments, a status request after a synchronous response returns the bank details required by the end user to complete the payment via a banking app

C2B:

1. The customer initiates the payment on the merchant side and sets extra data depending on the provider_id

2. Merchant sends C2B request to the platform
3. Platform returns temporary bank account details in the API response in status request (extra parameters) * account_number * bank_name * account_name
   Please note that the exact parameter names may differ slightly depending on the bank, so it is correct to display the entire extra section from the status request result to the user, for example:

"extra": 
{
"account_name": "MONEY TECH – LTD",
"account_number": "9999793854",
"bank_name": "GLOBAL BANK",
"transfer_amount": "1550"
}, 

4. Merchant displays these bank details to the Customer.
5. Customer makes a bank transfer to the provided details from their wallet.
6. Merchant gets a callback with the final state of the operation once the funds are received.

B2C Opay, PalmPay, Pay Attitude:

1. Customer initiates the payment on Merchant side and set extra data of their OPay, PalmPay or Pay Attitude bank account where customer_id is bank account
   In the extra parameters are specified:

   Provider_id	bank_code	customer_email	customer_name	customer_phone
   2443,2444,2445,2451,2449,2450,2452,2453		*	*

2. Merchant sends B2C request to the platform
3. Customer receives funds to their bank account in OPay, PalmPay or Pay Attitude
4. 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_email	customer_name	customer_phone
   2448, 2442	*		*
   2447	*
   2446	*	*	*

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

6. Merchant gets a callback from the platform with the final state of the operation

A typical example of a request involving extra parameters, including those responsible for payment security:

  {
  "merchant_id":"e0fecd91fcb24f348048193b3fb34875ba3722b4",
  "order_id":"1234567890",
  "customer_id":"1628095497",
  "customer_user_id": "user-123456",
  "amount":"1000.00",
  "currency":"NGN",
  "provider_id":2447,
  "extra":{
    "customer_name":"Name Lastname",
    "customer_email": "[email protected]",
    "bank_code":"0007",
    "customer_ip": "203.0.113.45",
    "customer_phone": "254700000001",
    "customer_doc_type": "ID",
    "customer_doc_number": "A123456789"
  },
  "signature":"d7d6d76b0e22c6f9d369fa6t7cf5a05beebb9c80843e"
}

Limits

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

2411, 2412:

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 their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

2410:

C2B:

1. Customer initiates the payment on Merchant side and set extra data customer_name
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 their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

2413:

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 receives a redirect_url via a status request
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 and customer_email
2. Merchant sends request to the platform (POST payment_b2c)
3. Customer receives funds to their mobile number
4. Merchant gets a callback (or requests the status) with the final state of the operation

For 2410, 2411, 2412, 2413:

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, 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.vukapay.io/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',
  'customer_id' => '0000000000', //For card payments only
  'country' => 'NGA', // For bank transfer only
  'amount' => 101, //For card payments only
  'currency' => 'NGN',
  'provider_id' => 5000,
  '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.vukapay.io/?merchant_id=fffed61be9780b97c5e4c65e4e07bb6b&order_id=order_3444298767545&country=NGA&currency=NGN&provider_id=5000&operation=c2b&type=bank_transfer&callback_url=https://my.callback.url&signature=9826c5e89ff6386e7bbb5263a4fbd41ed35eb2fc7c58650be487db14f066b0a650b1980762575ad296b0cbac1745f6a5faeb64cacd2756ccff95b52ba08259d7

This payment page https://hpp.vukapay.io/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 correct filling out all the form fields, including your credentials, you can check the "Print link:" box to see the link the user will be redirected to to continue payment, or simply click the "send to payment page" button so that 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 or get bank details for payment

Please note that the payment page is currently mandatory only in Nigeria for bank cards channel 2441.

C2B query url parameters for Payment page section: