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.

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
}

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

The result of the query processing by the system

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 a transaction ID or 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.