Unipesa Payment API Gateway (v5.7.2)

Download OpenAPI specification:Download

Payment Gateway API Reference

This API is part of the Unipesa 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.

Available Payment Providers

Provider ID Provider Name Country Notes
9 Vodacom CD Client's phone number with country code. Example: “243000000000”
10 OrangeMoney CD Client's phone should start from 0: 0800000000
11 Ecocash BI
12, 29 Safaricom KE Check your ID with your support team. Client's phone number with country code. Example: “254000000000”
14 Unipesa Simulator Any (e.g. KE) For testing purposes
15 Unipesa Payment Gateway Any (e.g. KE) For operations with Unipesa like cash out, etc
16, 30 Airtel KE Check your ID with your support team. Client's phone shouldn't start from 0: 999000000
17 Airtel CD Client's phone shouldn't start from 0: 999000000
19 Africell CD Client's phone should start from 0: 0900000000
20 Equity CD Online bank cards acquiring
23 Ecobank CD Online bank cards acquiring
28 Lumicash BI Client's phone number with country code. Example: “257123456789”
5002 Equity VISA CD The parameters are described in a separate section

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
}

For all other providers, status codes and callback parameters are described below in the documentation

Generating signature

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

Card payments

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

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

Safaricom Paybill

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 specify his account/wallet number to the Account number field
  • Client keys are in client’s M-PESA PIN
  • Client confirms details are correct and presses OK
  • Safaricom sends a callback to our system about this transaction
  • Amways sends a callback to Merchant about this transaction
  • Transaction information displays on Safaricom Backoffice
  • Transaction information displays on our Backoffice

Direct paybill payment instruction for Customer

To refill your account via direct payment to paybill, do the following steps on your Smartphone:

  1. Enter the SIM Toolkit
  2. Select Safaricom
  3. Select M-PESA
  4. Select Lipa na M-PESA
  5. Select Pay Bill
  6. Select "Enter business no." and enter it in the field that appears and then press "OK",
  7. Select "Account no" and specify your account for the desired resource on which you plan to make the deposit
  8. Enter the amount
  9. Enter the M-PESA PIN

After that you will receive a message with information that your transaction was completed successfully and it is confirmed

Paybill callback URL

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

Paybill callback format

Name of field Type Description Example
extra object A list of values
billRefNumber integer This field contains the parameter from Account number field in the payment form on Lipa Na M-PESA, which is indicated by the Customer.The Merchant has to inform the Customer to indicate the identification number of their account with the Merchant system. 555555555
firstName string Client’s first name (received from Safaricom) ALEX
amount number Amount to pay 100
result object Operation result
code integer Result code of the operation (0 - success) 0
message string Short description of the result code OK
status integer Status of the performed operation 2
currency string Currency code in ISO 4217 format KES
order_id string For paybills transactions, this unique value is generated by Unipesa for each Operation. Max length is 128 symbols. Allowed symbols: [a-z], [A-Z], [0-9], “_” (underscore character), “-” (hyphen), “:” (colon), “.” (dot). For example, GUID or TIMESTAMP can be used as an order_id. This parameter provides API idempotency. It means that requests with identical nonce from the same transaction initiator will have identical responses, and the corresponding operation won’t be repeated. In the backoffice, it may be found in the Merchant Trnx ID field 2023-03-15-15-25-12-255432
signature string Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course
service_id integer Unique ID of the service in the Payment gateway 1
customer_id string Customer’s phone number of 12 symbols. Client's phone should start from the country code: 254ХХХХХХХХХ (part of the number is returned as asterisk) 2547 ***** 000
merchant_id string Unique Merchant ID received during the merchant registration 555222hhh555fff999rrr444qqq222
provider_id integer Provider ID: 12: Safaricom 12
destination_id integer Transaction destination ID (merchant’s shortcode) 7000000
operation_type integer For paybills - 32 32
transaction_id string Usually generated by Safaricom. Empty for paybills
provider_result object
code integer Result code of the operation from the provider 0
message string Result description from the provider OK
service_version string Payment gateway service version used for the operation
transaction_ref string Transaction number registered in Safaricom (RRN). This field could be empty RBQ0000000
service_date_time string Payment gateway timestamp of the operation 2023-03-03 13:33:33.333333

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": 12,
 "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"}

Status Codes

The parameters below will be obtained by a status query

Code Name Description
-1 undefined Operation status is undefined (for example in an error situation)
0 initiated Operation initiated
1 in progress Operation is in progress
2 success Operation is successful
3 failed Operation failed
4 cancelled Operation cancelled
5 cancelled partially Operation cancelled partially (this status is related to POS payments)
6 in_transit Operation is in transition (for example for withdrawal operation it means that cash was held but wasn’t received by the customer, this status also is related to POS payments)

Operation Types

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

You can see this parameter in the callback

Code Operation
16 payment_b2c
17 payment_c2b

Available currencies

Code Note
CDF DRC, betting and non-betting merchants
USD Non-betting merchants only
KES Kenya, betting and non-betting merchants
BIF Burundi, betting and non-betting merchants

Confirmation Types

Verify the use of this parameter in the response of the performed operation

Code Type Request Parameters confirm_data parameter format
0 No confirmation required no confirmation request needed
1 OTP confirmation required merchant_id, order_id, confirm_data “otp”:”OTP value”
2 3DS 1.0 confirmation required merchant_id, order_id, confirm_data “pa_res”:”value”,”md”:”value”
3 3DS 2.0 confirmation required merchant_id, order_id, confirm_data “c_res”:”value”

Responses for confirmation requests have the same format as original operation responses.

Callbacks

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.

POS terminals usage case

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.

Online Payments

Cashless payment from the customer to the merchant

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Parameters to initiate a customer to the merchant payment

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

customer_id
required
string (customerIdDef)

Customer ID (usually mobile phone number of the customer)

order_id
required
string (orderIdDef)

The unique value is generated by the transaction initiator for each Operation. Max length is 128 symbols. Allowed symbols: [a-z], [A-Z], [0-9], “_” (underscore character), “-” (hyphen), “:” (colon), “.” (dot). For example, GUID or TIMESTAMP can be used as an order_id. This parameter provides API idempotency. It means that requests with identical nonce from the same transaction initiator will have identical responses and The corresponding operation won’t be repeated.

amount
required
string

Amount to pay, should be in format with two digits after point

currency
required
string (currencyDef)

Currency code in ISO 4217 format from the list of availabe currencies

country
string (countryDef)

Country code in ISO 3166-1 alpha-2 format as defined in the payment providers

callback_url
string

URL to notify the merchant via callback (recomended)

provider_id
required
integer (providerDef)
Enum: 9 10 11 12 14 15 16 17 19

Provider ID. Can be one of the option from this list.

signature
required
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "customer_id": "0900000001",
  • "order_id": "16280954971628095497",
  • "amount": "100.00",
  • "currency": "CDF",
  • "country": "CD",
  • "callback_url": "https://example.com/callback",
  • "provider_id": 10,
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "order_id": "16280954971628095497",
  • "transaction_id": "",
  • "transaction_ref": "",
  • "status": 1,
  • "result": {
    },
  • "provider_result": {
    },
  • "service_id": 1,
  • "service_version": "1.03/1.14|1.0/1.26|1.0/1.0|1.01/1.0|1.01/1.0||1.01/1.27",
  • "service_date_time": "2020-11-25 10:08:32.832969",
  • "confirm_type": 0
}

Callback payload samples

Callback
POST: Asynchronous notification of the merchant about the last performed transaction
Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "operation_type": 17,
  • "customer_id": "0900000001",
  • "amount": 100,
  • "order_id": "16280954971628095497",
  • "transaction_id": "1234567",
  • "transaction_ref": "QR555RQ",
  • "status": 2,
  • "provider_id": 10,
  • "destination_id": "",
  • "result": {
    },
  • "provider_result": {
    },
  • "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": "2020-11-25 10:08:32.832969",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Cashless payment from the merchant to the customer.

Cashless payment from the merchant to the customer. If the confirm_type response parameter is a non-zero merchant, send the second payment_b2c request with confirmation data according to the section Confirmation Types.

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Parameters to initiate the merchant to the customer payment

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

customer_id
required
string (customerIdDef)

Customer ID (usually mobile phone number of the customer)

order_id
required
string (orderIdDef)

The unique value is generated by the transaction initiator for each Operation. Max length is 128 symbols. Allowed symbols: [a-z], [A-Z], [0-9], “_” (underscore character), “-” (hyphen), “:” (colon), “.” (dot). For example, GUID or TIMESTAMP can be used as an order_id. This parameter provides API idempotency. It means that requests with identical nonce from the same transaction initiator will have identical responses and The corresponding operation won’t be repeated.

amount
required
string

Amount to pay, with two digits after point

currency
required
string (currencyDef)

Currency code in ISO 4217 format from the list of availabe currencies

country
string (countryDef)

Country code in ISO 3166-1 alpha-2 format as defined in the payment providers

callback_url
string

URL to notify the merchant via callback

provider_id
required
integer (providerDef)
Enum: 9 10 11 12 14 15 16 17 19

Provider ID. Can be one of the option from this list.

signature
required
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "customer_id": "0900000001",
  • "order_id": "16280954971628095497",
  • "amount": "100.00",
  • "currency": "CDF",
  • "country": "CD",
  • "callback_url": "https://example.com/callback",
  • "provider_id": 10,
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "order_id": "16280954971628095497",
  • "transaction_id": "C1234567.555.999",
  • "transaction_ref": "",
  • "status": 2,
  • "result": {
    },
  • "provider result": {
    },
  • "service_id": 1,
  • "service_version": "1.03/1.14|1.0/1.26|1.0/1.0|1.01/1.0|1.01/1.0||1.01/1.27",
  • "service_date_time": "2020-11-25 10:08:32.832969",
  • "confirm_type": 0
}

Callback payload samples

Callback
POST: Asynchronous notification of the merchant about the last performed transaction
Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "operation_type": 16,
  • "customer_id": "0900000001",
  • "amount": 100,
  • "order_id": "16280954971628095497",
  • "transaction_id": "1234567",
  • "transaction_ref": "QR555RQ",
  • "status": 2,
  • "provider_id": 10,
  • "destination_id": "",
  • "result": {
    },
  • "provider_result": {
    },
  • "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": "2020-11-25 10:08:32.832969",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Request a status of the transaction performed earlier

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Get the status of the performed transaction.

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

order_id
required
string (orderIdDef)

The unique value is generated by the transaction initiator for each Operation. Max length is 128 symbols. Allowed symbols: [a-z], [A-Z], [0-9], “_” (underscore character), “-” (hyphen), “:” (colon), “.” (dot). For example, GUID or TIMESTAMP can be used as an order_id. This parameter provides API idempotency. It means that requests with identical nonce from the same transaction initiator will have identical responses and The corresponding operation won’t be repeated.

signature
required
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "order_id": "16280954971628095497",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "order_id": "16280954971628095497",
  • "transaction_id": "",
  • "transaction_ref": "",
  • "status": 1,
  • "result": {
    },
  • "provider_result": {
    },
  • "service_id": 1,
  • "service_version": "1.03/1.14|1.0/1.26|1.0/1.0|1.01/1.0|1.01/1.0||1.01/1.27",
  • "service_date_time": "2020-11-25 10:08:32.832969",
  • "confirm_type": 0
}

Bulk online Payments

Create bulk payments

Merchant sends a request to the API method to create a bulk payment. Also, it is possible to get detailed information about the existing bulk payment, cancel processing of the existing bulk payment. Once the mass payment is initiated, the system will start processing payments for each client from the array in the bulk payment request

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Parameters to initiate the merchant to the customer payment

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

bulk_id
required
string

Bulk id

currency
required
string (currencyDef)

Currency code in ISO 4217 format from the list of availabe currencies

required
Array of objects (bulkitemsDef)
signature
required
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "bulk_id": "0000000001",
  • "currency": "CDF",
  • "items": [],
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "bulk_id": "0000000001",
  • "status": 0,
  • "result": {
    },
  • "service_id": 1,
  • "service_version": "1.27|1.01",
  • "service_date_time": "2020-11-25 10:08:32.832969"
}

Get details of bulk payments

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Get details of bulk payments

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

bulk_id
required
string
page
required
integer
page_size
required
integer
signature
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "bulk_id": "0000000001",
  • "page": 1,
  • "page_size": 100,
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "bulk_id": "0000000001",
  • "status": 2,
  • "total": 3,
  • "total_initiated": 0,
  • "total_in_progress": 0,
  • "total_successed": 3,
  • "total_failed": 0,
  • "items": [
    ],
  • "service_id": 1,
  • "service_version": "1.27|1.01",
  • "service_date_time": "2020-11-25 10:08:32.832969"
}

Cancel processing bulk payments

Note that already executed transactions from the array will not be cancelled on request

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Cancel processing bulk payments

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

bulk_id
required
string
signature
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "bulk_id": "0000000001",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "bulk_id": "0000000001",
  • "status": 4,
  • "result": {
    },
  • "service_id": 1,
  • "service_version": "1.27|1.01",
  • "service_date_time": "2020-11-25 10:08:32.832969"
}

POS Payments

Deposit via POS

Method should be called from the POS terminal or any other Unipesa valid external system for the initiation of the cash top-up operation to the customer account in the merchant system. Merchant gets information about the operation via the message that is sent to a predefined call back URL.

Callbacks

Callback payload samples

Callback
POST: Asynchronous notification of the merchant about the last performed transaction
Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "operation_type": 20,
  • "customer_id": "0900000001",
  • "amount": 100,
  • "order_id": "16280954971628095497",
  • "transaction_id": "1234567",
  • "transaction_ref": "QR555RQ",
  • "status": 2,
  • "provider_id": 10,
  • "destination_id": "",
  • "result": {
    },
  • "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": "2020-11-25 10:08:32.832969",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Withdrawal from the POS

Method should be called from the POS terminal or any other Unipesa valid external system for the initiation of the cash pay-out operation from the customer account in the merchant system. Note, that such operation requires pre-authorization on the merchant system and it can be done in various ways. In some cases, it is just an OTP confirmation sent to a customer’s phone, but in other cases, pre-allocation of money is also required that shall be done by calling the payment_c2b operation from the customer’s space in the merchant system. In such case, the amount that the customer is willing to withdraw is moved to a temporary account that is hard-locked with this particular customer and will stay there until the method withdrawal is called.

If the confirm_type response parameter is a non-zero merchant, send the second withdrawal request with confirmation data according to the section Confirmation Types.

path Parameters
public_id
required
string
Example: f54ec96649be11ebb3780242ac130002

Merchant public ID

Request Body schema: application/json

Parameters to initiate the merchant to the customer payment

merchant_id
required
string (merchantIdDef)

Unique Merchant ID received during the merchant registration

customer_id
required
string (customerIdDef)

Customer ID (usually mobile phone number of the customer)

order_id
required
string (orderIdDef)

The unique value is generated by the transaction initiator for each Operation. Max length is 128 symbols. Allowed symbols: [a-z], [A-Z], [0-9], “_” (underscore character), “-” (hyphen), “:” (colon), “.” (dot). For example, GUID or TIMESTAMP can be used as an order_id. This parameter provides API idempotency. It means that requests with identical nonce from the same transaction initiator will have identical responses and The corresponding operation won’t be repeated.

amount
required
string

Amount to pay, with two digits after point

currency
required
string (currencyDef)

Currency code in ISO 4217 format from the list of availabe currencies

country
string (countryDef)

Country code in ISO 3166-1 alpha-2 format as defined in the payment providers

provider_id
string

Provider_id

callback_url
string

callback_url

signature
required
string (signatureDef)

Merchant’s request and callback have to be signed to verify sent data. To generate the signature all sent parameters are included in the order they were sent. The parameter signature should be excluded, of course. Example can be found here

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "customer_id": "0900000001",
  • "order_id": "16280954971628095497",
  • "amount": "100.00",
  • "currency": "CDF",
  • "country": "CD",
  • "provider_id": "1003",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}

Response samples

Content type
application/json
{
  • "order_id": "16280954971628095497",
  • "transaction_id": "",
  • "transaction_ref": "",
  • "status": 7,
  • "result": {
    },
  • "provider result": {
    },
  • "service_id": 1,
  • "service_version": "1.03/1.14|1.0/1.26|1.0/1.0|1.01/1.0|1.01/1.0||1.01/1.27",
  • "service_date_time": "2020-11-25 10:08:32.832969",
  • "confirm_type": 0
}

Callback payload samples

Callback
POST: Asynchronous notification of the merchant about the last performed transaction
Content type
application/json
{
  • "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
  • "operation_type": 21,
  • "customer_id": "0900000001",
  • "amount": 100,
  • "order_id": "16280954971628095497",
  • "transaction_id": "1234567",
  • "transaction_ref": "QR555RQ",
  • "status": 2,
  • "provider_id": 10,
  • "destination_id": "",
  • "result": {
    },
  • "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": "2020-11-25 10:08:32.832969",
  • "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}