Download OpenAPI specification:Download
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.
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
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.
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
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
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.
To refill your account via direct payment to paybill, do the following steps on your Smartphone:
After that you will receive a message with information that your transaction was completed successfully and it is confirmed
The merchant should provide their callback URL to the Unipesa tech team to receive information about such transactions.
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 |
{
"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"
}
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"}
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) |
Depending on the type of request you may see the following code
Code | Operation |
---|---|
16 | payment_b2c |
17 | payment_c2b |
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 |
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.
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.
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.
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 | |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "customer_id": "0900000001",
- "order_id": "16280954971628095497",
- "amount": "100.00",
- "currency": "CDF",
- "country": "CD",
- "provider_id": 10,
- "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "order_id": "16280954971628095497",
- "transaction_id": "",
- "transaction_ref": "",
- "status": 1,
- "result": {
- "code": 0,
- "message": "OK"
}, - "provider_result": {
- "code": 0,
- "message": "OK"
}, - "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
}
{- "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": {
- "code": 0,
- "message": "OK"
}, - "provider_result": {
- "code": 0,
- "message": "OK"
}, - "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. 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.
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 | |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "customer_id": "0900000001",
- "order_id": "16280954971628095497",
- "amount": "100.00",
- "currency": "CDF",
- "country": "CD",
- "provider_id": 10,
- "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "order_id": "16280954971628095497",
- "transaction_id": "C1234567.555.999",
- "transaction_ref": "",
- "status": 2,
- "result": {
- "code": 0,
- "message": "OK"
}, - "provider result": {
- "code": 0,
- "message": "OK"
}, - "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
}
{- "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": {
- "code": 0,
- "message": "OK"
}, - "provider_result": {
- "code": 0,
- "message": "OK"
}, - "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"
}
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "order_id": "16280954971628095497",
- "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "order_id": "16280954971628095497",
- "transaction_id": "",
- "transaction_ref": "",
- "status": 1,
- "result": {
- "code": 0,
- "message": "OK"
}, - "provider_result": {
- "code": 0,
- "message": "OK"
}, - "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
}
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
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "bulk_id": "0000000001",
- "currency": "CDF",
- "items": [
- {
- "order_id": "16280954971628095497",
- "customer_id": "0900000001",
- "amount": "100.00",
- "country": "CD",
- "provider_id": 10
}
], - "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "bulk_id": "0000000001",
- "status": 0,
- "result": {
- "code": 0,
- "message": "OK"
}, - "service_id": 1,
- "service_version": "1.27|1.01",
- "service_date_time": "2020-11-25 10:08:32.832969"
}
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "bulk_id": "0000000001",
- "page": 1,
- "page_size": 100,
- "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "bulk_id": "0000000001",
- "status": 2,
- "total": 3,
- "total_initiated": 0,
- "total_in_progress": 0,
- "total_successed": 3,
- "total_failed": 0,
- "items": [
- {
- "order_id": "16280954971628095497",
- "customer_id": "0900000001",
- "amount": 100,
- "status": 2
}
], - "service_id": 1,
- "service_version": "1.27|1.01",
- "service_date_time": "2020-11-25 10:08:32.832969"
}
Note that already executed transactions from the array will not be cancelled on request
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "bulk_id": "0000000001",
- "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "bulk_id": "0000000001",
- "status": 4,
- "result": {
- "code": 0,
- "message": "OK"
}, - "service_id": 1,
- "service_version": "1.27|1.01",
- "service_date_time": "2020-11-25 10:08:32.832969"
}
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.
{- "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": {
- "code": 0,
- "message": "OK"
}, - "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"
}
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.
public_id required | string Example: f54ec96649be11ebb3780242ac130002 Merchant public ID |
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 | |
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 |
{- "merchant_id": "e0fecd91fcb24f348048193b3fb34875ba3722b4",
- "customer_id": "0900000001",
- "order_id": "16280954971628095497",
- "amount": "100.00",
- "currency": "CDF",
- "country": "CD",
- "provider_id": "1003",
- "signature": "d7d6d76b0e22c6f9d369fa6c24f107053d12bfd24d3b154f2deb6676bf179c123134e1f20879c803be455d81cfe792f00cd8892c26ce7cf5a05beebb9c80843e"
}
{- "order_id": "16280954971628095497",
- "transaction_id": "",
- "transaction_ref": "",
- "status": 7,
- "result": {
- "code": 0,
- "message": "OK"
}, - "provider result": {
- "code": 0,
- "message": "OK"
}, - "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
}
{- "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": {
- "code": 0,
- "message": "OK"
}, - "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"
}