Private
Subscription
Regular billing of your clients by server-server method
Unsubscribe
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\" : \"unsubscribe\",
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\",
\"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 | unsubscribe | |
order_id | Required | String | Unique purchase ID in your shop. Maximum length is 255 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 | |
card_token | String | Sender's card token | |
commission_credit | Number | Commission from the receiver in currency_credit | |
commission_debit | Number | Commission from the sender in currency_debit | |
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 | |
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_card_bank | String | Sender's card bank | |
sender_card_country | String | Sender's card country. Digital ISO 3166-1 code | |
sender_card_mask2 | String | Sender's card | |
sender_card_type | String | Sender's card type MC/Visa | |
sender_commission | Number | Commission from the sender in the payment currency | |
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 unsubscribed - Subscribed successfully deactivated | |
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": "subscribe",
"agent_commission": "0.0",
"amount_bonus": "0.0",
"amount_credit": "38.31",
"amount_debit": "38.31",
"amount": "1.0",
"commission_credit": "0.57",
"commission_debit": "0.0",
"create_date": "1705651874776",
"currency_credit": "UAH",
"currency_debit": "UAH",
"currency": "USD",
"description": "{{info.edittext_6686}}",
"end_date": "1705651920384",
"is_3ds": "false",
"liqpay_order_id": "HGJI2AU61705651874774315",
"mpi_eci": "7",
"order_id": "order_id_76587576",
"payment_id": "2416590001",
"paytype": "card",
"public_key": "sandbox_i63492854596",
"receiver_commission": "0.02",
"result": "ok",
"sender_bonus": "0.0",
"sender_card_bank": "Test",
"sender_card_country": "804",
"sender_card_mask2": "424242*42",
"sender_card_type": "visa",
"sender_commission": "0.0",
"sender_phone": "380950000001",
"status": "unsubscribed",
"transaction_id": "2416590001",
"type": "buy",
"version": "3",
"card_token": "6E28D6039FD09FA3CE1DF27BCC2DE0E3254A3B27"
}