Public
Cash payment
Deferred payment in cash at PrivatBank self-service terminals
Scheme of API cash payment
Forming a request to API for self-integration:
Required URLs for work depending on the model chosen:
- https://www.liqpay.ua/api/request — Server-Server;
- https://www.liqpay.ua/api/3/checkout — Client-Server;
To call the LiqPay API you need to pass the data and signature (Server - Server) parameters via the POST method or redirect the client (Client-Server) using the POST method, where:
data
- json string with APIs parameters encoded by the function base64, base64_encode( json_string ),
signature
- is the unique signature of each request base64_encode( sha1( private_key + data + private_key) ),
base64_encode
- returns a string encoded by the base64,
sha1
- the hash is returned as a binary string of 20 characters.
Forming data and signature, example:
To connect the receiving of payment via LiqPay, forming json string with parameters api call, wherein:
Parameter | Required | Type | Description | |
---|---|---|---|---|
version | Required | Number | Версія API. Наприклад: 3 | |
public_key | Required | String | Public_key - the identifier of the created company. For example: i00000000 | |
private_key | Required | String | Private key of the created company (not available to anyone except your developer). For example: a4825234f4bae72a0be04eafe9e8e2bada209255 | |
action | Required | String | Transaction type. Possible values: pay - payment, hold - amount of hold on sender's account, subscribe - payment payment, paydonate - donation | |
amount | Required | Number | Payment amount. For example: 5, 7.34 | |
currency | Required | String | Payment currency. Possible values: USD, EUR, UAH. Additional currencies can be added by company's request | |
description | Required | String | Payment description | |
order_id | Required | String | Unique purchase ID in your shop. Maximum length is 255 symbols |
More parameters in the documentation
Example of creating json_string:
json_string =
{"public_key":"i00000000","version":"3","action":"pay","amount":"3","currency":"UAH","description":"test","order_id":"000001"}
Example of coding json_string function base64_encode, the company receives data:
data = eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9
An example formation of signature, the company forms the string sign_string by concatenating private_key + data + private_key:
sign_string = a4825234f4bae72a0be04eafe9e8e2bada209255eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9a4825234f4bae72a0be04eafe9e8e2bada209255
After applying the functions base64_encode( sha1( sign_string) ) we get the string:
signature = wR+UZDC4jjeL/qUOvIsofIWpZh8=
Example of sending a request to LiqPay:
1.To redirect the client to the LiqPay payment page (Client - Server), you need to generate an HTML form
<form method="POST" action="https://www.liqpay.ua/api/3/checkout" accept-charset="utf-8">
<input type="hidden" name="data"
value="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9"/>
<input type="hidden" name="signature" value="wR+UZDC4jjeL/qUOvIsofIWpZh8="/><input
type="image" src="//static.liqpay.ua/buttons/payUk.png"/></form>
<input type="hidden" name="data"
value="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9"/>
<input type="hidden" name="signature" value="wR+UZDC4jjeL/qUOvIsofIWpZh8="/><input
type="image" src="//static.liqpay.ua/buttons/payUk.png"/></form>
2.For interaction (Server - Server), the received data and signature must be sent to the url https://www.liqpay.ua/api/request
curl --silent -XPOST https://www.liqpay.ua/api/request --data-
urlencodedata="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9"/>
--data-urlencode
signature="wR+UZDC4jjeL/qUOvIsofIWpZh8="
urlencodedata="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9"/>
--data-urlencode
signature="wR+UZDC4jjeL/qUOvIsofIWpZh8="
3.The status of the operation will be sent to server_url
4.Successful completion of payment
Example of using SDK:
#!/bin/bash
PUBLIC_KEY='your_public_key'
PRIVATE_KEY='your_private_key'
API_URL='https://www.liqpay.ua/api/request'
JSON="{
\"action\" : \"paycash\",
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\",
\"phone\" : \"380950000001\",
\"amount\" : 1,
\"currency\" : \"USD\",
\"description\" : \"description text\",
\"order_id\" : \"order_id_1\"
}"
# DATA is base64_encode result from JSON string
DATA=$(echo -n ${JSON} | base64)
# SIGNATURE is base64 encode result from sha1 binary hash from concatenate string ${PRIVATE_KEY}${DATA}${PRIVATE_KEY}
SIGNATURE=$(echo -n "${PRIVATE_KEY}${DATA}${PRIVATE_KEY}" | openssl dgst -binary -sha1 | base64)
# REQ is json response from liqpay
REQ=$(curl --silent -XPOST ${API_URL} --data-urlencode data="${DATA}" --data-urlencode signature="${SIGNATURE}")
echo "Result: ${REQ}"
Options for generating data:
Main
Parameter | Required | Type | Description | |
---|---|---|---|---|
version | Required | Number | Version API. Current value - 3 | |
public_key | Required | String | Public key - the store identifier. You can get the key in the store settings | |
action | Required | String | paycash | |
amount | Required | Number | Payment amount. For example: 5, 7.34 | |
currency | Required | String | Payment currency. Possible values: USD, EUR, UAH | |
description | Required | String | Payment description | |
ip | Required | String | Client IP | |
order_id | Required | String | Unique purchase ID in your shop. Maximum length is 255 symbols | |
phone | Required | String | Payer's phone number. The OTP-password will be sent to this telephone number to confirm your payment, and the linked payer's LiqPay cabinet. The telephone number should be indicated in the international format (Ukraine +380). For example: +380950000001 (with +) or 380950000001 (without +) | |
expired_date | Optional | String | Date and time until which customer is able to pay invoice by UTC. Should be sent in the following format 2016-04-24 00:00:00 | |
language | Optional | String | Customer's language uk, en | |
prepare | Optional | String | The preliminary preparation of the payment. This mode allows you to determine whether all data is complete, whether 3DS is required to check the card, whether the limit is exceeded. The funds are not debited from the payer's card. To activate the mode, you need to transfer the value of 1 | |
server_url | Optional | String | URL API in your store for notifications of payment status change (server -> server). Maximum length is 510 symbols. Learn more |
Parameters of splitting the payments:
Parameter | Required | Type | Description | |
---|---|---|---|---|
split_rules | Optional | String | Payment with a split amount for a few receivers. This parameter is a JSON array containing split rules. While using the split_rules parameter, the card is being charged and the amount is split and credited to a few receivers. If you need to convey your purpose for each amount use the parameter description. If you need to fiscalize payment, you should add the object rro_info into each part of the split rules. Acquiring fee is being charged from each receiver in the split_rules. Example JSON string: |
|
Other parameters:
Parameter | Required | Type | Description | |
---|---|---|---|---|
customer | Optional | String | Unique customer ID in your shop. Max length 100 symbols. | |
dae | Optional | String | Detail Addenda. Required for merchants with MCC 4511 Parameter dae is JSON string, to which function base64. JSON can contain the parameters shown in the example Example of parameter dae: ewogICJhaXJMaW5lIjogIkROSVBST0FWSUEiLAogICJ0aWNrZXROdW1iZXIiOiAiQUNTRkQxMjM1NFNBIiwKICAicGFzc2VuZ2VyTmFtZSI6ICJKb2huIERvZSIsCiAgImZsaWdodE51bWJlciI6ICI3NDIiLAogICJvcmlnaW5DaXR5IjogIkRQIiwKICAiZGVzdGluYXRpb25DaXR5IjogIk5ZIiwKICAiZGVwYXJ0dXJlRGF0ZSI6ICIxMDA1MTQiCn0= |
|
info | Optional | String | Information to add details to payment. For example: «External information for payments» | |
product_category | Optional | String | Product category in your shop. The maximum length is 25 symbols | |
product_description | Optional | String | Product description in your shop. The maximum length is 500 symbols | |
product_name | Optional | String | Product name in your shop. The maximum length is 100 symbols | |
product_url | Optional | String | Product page address. The maximum length is 2000 symbols |
Response parameters:
Parameter | Type | Description | |
---|---|---|---|
acq_id | Number | Acquirer ID | |
action | String | Transaction type. Possible values: pay - payment, hold - amount of hold on sender's account, paysplit - splitting payments, subscribe - creation of a regular payment, paydonate - donation, auth - card preauth, regular - regular payment | |
agent_commission | Number | Agent comission in payment currency | |
amount | Number | Payment amount | |
amount_bonus | Number | Payer bonus amount in payment currency debit | |
amount_credit | Number | Payment amount for credit in currency of currency_credit | |
amount_debit | Number | Payment amount for debit in currency of currency_debit | |
commission_credit | Number | Commission from the receiver in currency_credit | |
commission_debit | Number | Commission from the sender in currency_debit | |
confirm_phone | String | Payer's phone number. The OTP-password was sent to this telephone number to confirm your payment, and the linked payer's LiqPay cabinet. The telephone number should be indicated in the international format (Ukraine +380). For example: +380950000001 (with +) or 380950000001 (without +) | |
create_date | String | Date of payment creation | |
currency | String | Payment currency | |
currency_credit | String | Transaction currency of credit | |
currency_debit | String | Transaction currency of debit | |
description | String | Payment description | |
end_date | String | Date of payment edition/end | |
ip | String | Sender's IP address | |
is_3ds | Boolean | Possible values: true - transaction passed with 3DS, false - transaction passed without 3DS | |
liqpay_order_id | String | Payment order_id in LiqPay system | |
mpi_eci | Number | Possible values: 5 - the transaction passed with 3DS (issuer and acquirer support 3d Secure technology), 6 - the issuer of the payer card does not support 3d Secure technology, 7 - the operation passed without 3d Secure | |
order_id | String | Order_id payment | |
payment_id | Number | Payment id in LiqPay system | |
paytype | String | Methods of payment. Possible values card - card payment, privat24 - with privat24 account, moment_part - installments, cash - cash, invoice - to email, qr - qr code scanning | |
public_key | String | Shop public key | |
receiver_commission | Number | Receiver comission in payment currency | |
result | String | The result of the request ok, error | |
sender_bonus | Number | Sender's bonus in the payment currency | |
sender_commission | Number | Commission from the sender in the payment currency | |
sender_first_name | String | Sender's first name | |
sender_last_name | String | Sender's last name | |
sender_phone | String | Sender's phone number | |
status | String | Payment status. Available values: Final payment statuses error - Failed payment. Data is incorrect failure - Failed payment success - Successful payment Statuses that required payment confirmation cash_wait - Waiting for payment in self-service terminal | |
transaction_id | Number | Id transactions in the LiqPay system | |
type | String | Payment type | |
version | Number | Version API. Present value - 3 |
Example response:
{
"acq_id": "414963",
"action": "paycash",
"agent_commission": "0.0",
"amount_bonus": "0.35",
"amount_credit": "1.0",
"amount_debit": "1.0",
"amount": "1.0",
"commission_credit": "0.0",
"commission_debit": "0.0",
"confirm_phone": "380933454182",
"create_date": "1715335274831",
"currency_credit": "UAH",
"currency_debit": "UAH",
"currency": "UAH",
"description": "description text",
"end_date": "1501684842777", "is_3ds": "false",
"liqpay_order_id": "YP0L4E5S1715335274827674",
"mpi_eci": "7",
"order_id": "order_id_45_pay_by_cash1",
"payment_id": "13291496",
"paytype": "cash",
"public_key": "i16202663459",
"receiver_commission": "0.0",
"result": "ok",
"sender_bonus": "0.35",
"sender_commission": "0.0",
"sender_first_name": "Tetiana",
"sender_last_name": "Stanko",
"sender_phone": "380933454182",
"status": "cash_wait",
"transaction_id": "13291496",
"type": "cash",
"version": "3"
}