Public
Cash payment
Deferred payment in cash at PrivatBank self-service terminals
Scheme of API cash payment
LiqPay EN_Cash_payment

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:
ParameterRequiredTypeDescription
versionRequiredNumberВерсія API. Наприклад: 3
public_keyRequiredStringPublic_key - the identifier of the created company. For example: i00000000
private_keyRequiredStringPrivate key of the created company (not available to anyone except your developer). For example: a4825234f4bae72a0be04eafe9e8e2bada209255
actionRequiredStringTransaction type. Possible values: pay - payment, hold - amount of hold on sender's account, subscribe - payment payment, paydonate - donation
amountRequiredNumberPayment amount. For example: 5, 7.34
currencyRequiredStringPayment currency. Possible values: USD, EUR, UAH. Additional currencies can be added by company's request
descriptionRequiredStringPayment description
order_idRequiredStringUnique purchase ID in your shop. Maximum length is 255 symbols
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>
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="
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
ParameterRequiredTypeDescription
versionRequiredNumberVersion API. Current value - 3
public_keyRequiredStringPublic key - the store identifier. You can get the key in the store settings
actionRequiredStringpaycash
amountRequiredNumberPayment amount. For example: 5, 7.34
currencyRequiredStringPayment currency. Possible values: USD, EUR, UAH
descriptionRequiredStringPayment description
ipRequiredStringClient IP
order_idRequiredStringUnique purchase ID in your shop. Maximum length is 255 symbols
phoneRequiredStringPayer'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
StringDate 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
StringCustomer's language uk, en
prepare
Optional
StringThe 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
StringURL API in your store for notifications of payment status change (server -> server). Maximum length is 510 symbols. Learn more
Parameters of splitting the payments:
ParameterRequiredTypeDescription
split_rules
Optional
StringPayment 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:
[
  {
    "public_key": "i000000001",
    "amount": 404,
    "commission_payer": "sender",
    "server_url": "https://server1/callback",
    "rro_info": {
      "items": [
        {
          "amount": 2,
          "price": 202,
          "cost": 404,
          "id": 123456
        }
      ],
      "delivery_emails": [
        "email1@email.com",
        "email2@email.com"
      ]
    }
  },
  {
    "public_key": "i000000002",
    "amount": 200,
    "commission_payer": "receiver",
    "server_url": "https://server2/callback"
  }
]
Other parameters:
ParameterRequiredTypeDescription
customer
Optional
StringUnique customer ID in your shop. Max length 100 symbols.
dae
Optional
StringDetail 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=
{
  "airLine": "Avia", // airline abbreviation, max 4 symbols.
  "ticketNumber": "ACSFD12354SA", // ticket number, max 15 symbols. 
  "passengerName": "John Doe", // passenger name, max 29 symbols.
  "flightNumber": "742", // flight number, max 5 number.
  "originCity": "DP", // departure city/airport code, max 5 symbols.
  "destinationCity": "NY", // arrival city/airport code, max 5 symbols.
  "departureDate": "100514" // departure date in format YYMMDD, max 6 number.
}
info
Optional
StringInformation to add details to payment. For example: «External information for payments»
product_category
Optional
StringProduct category in your shop. The maximum length is 25 symbols
product_description
Optional
StringProduct description in your shop. The maximum length is 500 symbols
product_name
Optional
StringProduct name in your shop. The maximum length is 100 symbols
product_url
Optional
StringProduct page address. The maximum length is 2000 symbols
Response parameters:
ParameterTypeDescription
acq_idNumberAcquirer ID
actionStringTransaction 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_commissionNumberAgent comission in payment currency
amountNumberPayment amount
amount_bonusNumberPayer bonus amount in payment currency debit
amount_creditNumberPayment amount for credit in currency of currency_credit
amount_debitNumberPayment amount for debit in currency of currency_debit
commission_creditNumberCommission from the receiver in currency_credit
commission_debitNumberCommission from the sender in currency_debit
confirm_phoneStringPayer'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_dateStringDate of payment creation
currencyStringPayment currency
currency_creditStringTransaction currency of credit
currency_debitStringTransaction currency of debit
descriptionStringPayment description
end_dateStringDate of payment edition/end
ipStringSender's IP address
is_3dsBooleanPossible values:
true - transaction passed with 3DS, false - transaction passed without 3DS
liqpay_order_idStringPayment order_id in LiqPay system
mpi_eciNumberPossible 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_idStringOrder_id payment
payment_idNumberPayment id in LiqPay system
paytypeStringMethods of payment. Possible values card - card payment, privat24 - with privat24 account, moment_part - installments, cash - cash, invoice - to email, qr - qr code scanning
public_keyStringShop public key
receiver_commissionNumberReceiver comission in payment currency
resultStringThe result of the request ok, error
sender_bonusNumberSender's bonus in the payment currency
sender_commissionNumberCommission from the sender in the payment currency
sender_first_nameStringSender's first name
sender_last_nameStringSender's last name
sender_phoneStringSender's phone number
statusStringPayment 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_idNumberId transactions in the LiqPay system
typeStringPayment type
versionNumberVersion 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"
}