Приватний
Двостадійна оплата
Блокування коштів на картці клієнта для подальшого списання
Що таке двостадійна оплата?
Двостадійна оплата дає змогу заблокувати кошти на картці клієнта та списати їх пізніше – до моменту відправлення товару або надання послуги.
Гарантований період блокування коштів на картці:
- 7 днів для Mastercard
- 10 днів для Visa
Після закінчення терміну банк платника автоматично розблокує кошти.
Технічно ви можете завершити оплату протягом 30 днів, але після закінчення періоду блокування коштів (7 або 10 днів) банк платника має право оскаржити операцію. Щоб уникнути ризиків, підтверджуйте оплату в межах гарантованого періоду блокування.
Можливості
Розщеплення платежу на декількох одержувачів
Отримання токена картки клієнта у відповіді від LiqPay
Завершення оплати протягом 30 днів
Розблокування в будь-який момент протягом 30 днів
Як працює API двостадійна оплата
- Компанія формує запит на API двостадійна оплата зі зазначенням обов'язкових параметрів..
- На картці клієнта блокуються кошти.
- Списання заблокованих коштів повністю або частково, на користь компанії. У разі часткового списання, блокування по частині коштів що залишилася автоматично скасовується.
- Скасувати блокування коштів можливо за допомогою API повернень.
Підключення
1
Server-Server
З сертифікатом PCI DSS відповідного рівня
Згідно з правилами платіжних систем Mastercard і Visa наявність сертифіката є обов'язковим, так як взаємодія з LiqPay проходить по методу server-server, клієнт вводить реквізити картки на сайті компанії.
Для отримання доступу до API необхідно:
- Мати сертифікат PCI DSS (Payment Card Industry Data Security Standard) відповідного рівня, в залежності від кількості операцій в рік
- Подати заявку на підключення
Відправити запит
2
Client-Server
Без сертифіката PCI DSS
Інтеграція в рамках публічних API Checkout або Платіжний віджет, використовуйте action hold - блокування коштів на рахунку відправника.
Методи інтеграції
Самостійна інтеграція згідно з документацією
Є питання?
Звертайтесь до нашого технічного відділу на пошту:
liqpay.support@privatbank.ua
Блокування
Схема роботи API двостадійної оплати

Необхідні URL для роботи в залежності від обраної моделі:
- https://www.liqpay.ua/api/request — Server-Server;
- https://www.liqpay.ua/api/3/checkout — Client-Server;
Для виклику API LiqPay необхідно передати параметри data і signature (Server - Server) POST методом або перенаправити клієнта (Client-Server) використовуючи POST метод, де:
data
- json рядок з параметрами APIs закодована функцією base64, base64_encode( json_string ),
signature
- унікальний підпис кожного запиту base64_encode( sha3-256( private_key + data + private_key) ),
base64_encode
- повертає рядок, закодований методом base64,
sha3-256
- повертає хеш у вигляді бінарного рядку з 32 байт (64 символи).
Формування data і signature, приклад:
Для підключення прийому оплати через LiqPay, формуємо json рядок з параметрами виклику апі, де:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| version | Required | Number | Версія API. Наприклад: 7 | |
| public_key | Required | String | Публічний ключ - ідентифікатор створеної компанії. Наприклад: i00000000 | |
| private_key | Required | String | Приватний ключ створеної компанії (не надається нікому крім Вашого розробника). Наприклад: a4825234f4bae72a0be04eafe9e8e2bada209255 | |
| action | Required | String | Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, subscribe - регулярний платіж, paydonate - пожертва, auth - предавторізація картки | |
| amount | Required | Number | Сума платежу. Наприклад: 5, 7.34 | |
| currency | Required | String | Валюта платежу. Можливі значення:USD, EUR, UAH. Додаткові валюти можуть бути встановлені за запитом компанії | |
| description | Required | String | Призначення платежу | |
| order_id | Required | String | Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів |
Більше параметрів в документації
Приклад створення json_string:
json_string =
{"public_key":"i00000000","version":7,"action":"pay","amount":"3","currency":"UAH","description":"test","order_id":"000001"}Приклад кодування json_string функцією base64_encode, компанія отримує data:
data = eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ==
Приклад формування signature, компанія формує рядок sign_string шляхом конкатенації private_key + data + private_key:
sign_string = a4825234f4bae72a0be04eafe9e8e2bada209255eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ==a4825234f4bae72a0be04eafe9e8e2bada209255
Після застосування функцій base64_encode( sha3-256( sign_string) ) отримуємо рядок:
signature = 0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s=
Приклад відправки запиту до LiqPay:
1.Для перенаправлення клієнта на сторінку оплати LiqPay (Client - Server) необхідно сформувати HTML-форму:
<form method="POST" action="https://www.liqpay.ua/api/3/checkout" accept-charset="utf-8">
<input type="hidden" name="data"
value="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
<input type="hidden" name="signature" value="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="/><input
type="image" src="//static.liqpay.ua/buttons/payUk.png"/></form>
<input type="hidden" name="data"
value="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
<input type="hidden" name="signature" value="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="/><input
type="image" src="//static.liqpay.ua/buttons/payUk.png"/></form>
2.Для взаємодії (Server - Server) отримані data і signature необхідно відправити на url https://www.liqpay.ua/api/request:
curl --silent -XPOST https://www.liqpay.ua/api/request --data-
urlencodedata="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
--data-urlencode
signature="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="
urlencodedata="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
--data-urlencode
signature="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="
3.Статус операції буде відправлений на server_url
4.Успішне завершення оплати
Приклад використання SDK:
#!/bin/bash
PUBLIC_KEY='your_public_key'
PRIVATE_KEY='your_private_key'
API_URL='https://www.liqpay.ua/api/request'
JSON="{
\"action\" : \"hold\",
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\",
\"phone\" : \"380950000001\",
\"amount\" : \"1\",
\"currency\" : \"USD\",
\"description\" : \"description text\",
\"order_id\" : \"order_id_1\",
\"card\" : \"4731195301524634\",
\"card_exp_month\" : \"03\",
\"card_exp_year\" : \"22\",
\"card_cvv\" : \"111\"
}"
# 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}"
$liqpay = new LiqPay($public_key, $private_key);
$res = $liqpay->api("request", array(
'action' => 'hold',
'version' => '3',
'phone' => '380950000001',
'amount' => '1',
'currency' => 'USD',
'description' => 'description text',
'order_id' => 'order_id_1',
'card' => '4731195301524634',
'card_exp_month' => '03',
'card_exp_year' => '22',
'card_cvv' => '111'
));
HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "hold");
params.put("version", "3");
params.put("phone", "380950000001");
params.put("amount", "1");
params.put("currency", "USD");
params.put("description", "description text");
params.put("order_id", "order_id_1");
params.put("card", "4731195301524634");
params.put("card_exp_month", "03");
params.put("card_exp_year", "22");
params.put("card_cvv", "111");
LiqPay liqpay = new LiqPay(PUBLIC_KEY, PRIVATE_KEY);
HashMap<String, Object> res = liqpay.api("request", params);
System.out.println(res.get("status"));
liqpay = LiqPay(public_key, private_key)
res = liqpay.api("request", {
"action" : "hold",
"version" : "3",
"phone" : "380950000001",
"amount" : "1",
"currency" : "USD",
"description" : "description text",
"order_id" : "order_id_1",
"card" : "4731195301524634",
"card_exp_month" : "03",
"card_exp_year" : "22",
"card_cvv" : "111"
})
liqpay = Liqpay::Liqpay.new(
:public_key => 'public_key',
:private_key => 'private_key'
)
res = liqpay.api("request", {
:action => "hold",
:version => "3",
:phone => "380950000001",
:amount => "1",
:currency => "USD",
:description => "description text",
:order_id => "order_id_1",
:card => "4731195301524634",
:card_exp_month => "03",
:card_exp_year => "22",
:card_cvv => "111"
})
LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>, <<"hold">>},
{<<"version">>, <<"3">>},
{<<"phone">>, <<"380950000001">>},
{<<"amount">>, <<"1">>},
{<<"currency">>, <<"USD">>},
{<<"description">>, <<"description text">>},
{<<"order_id">>, <<"order_id_1">>},
{<<"card">>, <<"4731195301524634">>},
{<<"card_exp_month">>, <<"03">>},
{<<"card_exp_year">>, <<"22">>},
{<<"card_cvv">>, <<"111">>}
], LiqPay)
var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
liqpay.api("request", {
"action" : "hold",
"version" : "3",
"phone" : "380950000001",
"amount" : "1",
"currency" : "USD",
"description" : "description text",
"order_id" : "order_id_1",
"card" : "4731195301524634",
"card_exp_month" : "03",
"card_exp_year" : "22",
"card_cvv" : "111"
}, function( json ){
console.log( json.status );
});
my $liqpay = Liqpay->new($public_key,$private_key);
my $res = $liqpay->api("request",
{
'action' => 'hold',
'version' => '3',
'phone' => '380950000001',
'amount' => '1',
'currency' => 'USD',
'description' => 'description text',
'order_id' => 'order_id_1',
'card' => '4731195301524634',
'card_exp_month' => '03',
'card_exp_year' => '22',
'card_cvv' => '111'
}
);
var c = liqpay.New("my_public_key", "my_private_key", nil)
// Creating the request map with all necessary parameters
request:=map[string]interface{}{
"action": "hold",
"version": 3,
"public_key": "my_public_key",
"phone": "380950000001",
"amount": 1,
"currency": "UAH",
"description": "Test payment",
"order_id": "order_id_1",
"card": "4731195301524634",
"card_exp_month": "03",
"card_exp_year": "22",
"card_cvv": "111",
}
resp, err := c.Send("request", request)
if err != nil {
fmt.Printf("error %v", err.Error())
return
}
fmt.Printf("response: %#v", resp)
Параметри для формування data:
Основні
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| version | Required | Number | Версія API. Поточне значення - 7 | |
| public_key | Required | String | Публічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину | |
| action | Required | String | hold | |
| amount | Required | Number | Сума платежу. Наприклад: 5, 7.34 | |
| apay_token | Optional | String | JSON рядок з параметра token (отриманий від Apple), закодована функцією base64. Параметр не обов'язковий, якщо передається параметр card або gpay_token | |
| card | Optional | String | Номер картки клієнта або незашифрований токен Apple, Google, міжнародних платіжних систем (MasterCard, Visa). Параметр не обов'язковий, якщо передається параметр gpay_token or apay_token | |
| card_cvv | Optional | String | CVV/CVV2. Параметр обов’язковий, якщо передається номер картки | |
| card_exp_month | Optional | String | Місяць терміну дії картки платника. Параметр обов'язковий, якщо передається номер картки або незашифрований токен. Наприклад: 08 | |
| card_exp_year | Optional | String | Рік терміну дії картки платника. Параметр обов'язковий, якщо передається номер картки або незашифрований токен. Наприклад: 19 | |
| currency | Required | String | Валюта платежу. Можливі значення: USD, EUR, UAH | |
| description | Required | String | Призначення платежу | |
| gpay_token | Optional | String | JSON рядок з параметра token (отриманий від Google), закодована функцією base64. Параметр не обов'язковий, якщо передається параметр card або apay_token | |
| ip | Required | String | IP клієнта | |
| order_id | Required | String | Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів | |
| phone | Required | String | Телефон платника. На цей номер буде відправлений OTP пароль підтвердження платежу та підвязаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +) | |
| paytype | Optional | String | Тип оплати. Можливі значення: apay - оплата за допомогою зашифрованого токена Apple, gpay - оплата за допомогою зашифрованого токена Google, apay_tavv - оплата за допомогою незашифрованого токена Apple, gpay_tavv - оплата за допомогою незашифрованого токена Google, tavv - оплата за допомогою незашифрованого токена міжнародних платіжних систем (MasterCard, Visa). Параметр обов'язковий для оплат за допомогою зашифрованих і незашифрованих токенів | |
| tid | Optional | String | Ідентифікатор попередньої транзакції. Для рекурентних платежів за токенами міжнародної платіжної системи Visa | |
| language | Optional | String | Мова клієнта uk, en | |
| prepare | Optional | String | Попередня підготовка платежу. Цей режим дозволяє визначити чи заповнені всі дані , чи потрібна 3DS перевірка картки, чи не перевищено ліміт. Гроші з картки платника не списуються. Для включення режиму необхідно передати значення 1 | |
| recurringbytoken | Optional | String | Цей параметр дозволяє генерувати card_token платника, який ви отримаєте в callback запиті на server_url. card_token дозволяє проводити платежі без введення реквізитів картки платника, використовуючи API paytoken. Для отримання card_token необхідно передати в запиті значення 1 | |
| is_recurring | Optional | Boolean | Ознака рекурентної оплати за токеном. Можливі значення true - операція виконується без участі клієнта, false - операція виконується клієнтом | |
| server_url | Optional | String | URL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше | |
| tavv | Required | String | Референс токена, отриманого при декриптуванні даних пристрою Apple | |
| eci | Optional | String | Electronic Commerce Indicator - код, який ідентифікує тип транзакції та факт проведення аутентифікації платника через 3D Secure або інший спосіб. Можливі значення: MasterCard: 02, 06 Visa: 05, 07 | |
| cavv | Optional | String | Cardholder Authentication Verification Value - використовується для перевірки автентичності власника картки під час транзакцій, що проходять через 3D Secure | |
| tdsv | Optional | String | Версія, за якою проходила перевірка 3ds | |
| dsTransID | Optional | String | Ідентифікатор сесії перевірки 3ds |
Параметри відправника:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| sender_first_name | Optional | String | Ім'я відправника | |
| sender_last_name | Optional | String | Прізвище відправника | |
| phone | Required | String | Телефон платника | |
| sender_email | Optional | String | Електронна адреса | |
| sender_country_code | Required | String | Код країни відправника. Цифровий ISO 3166-1 код | |
| sender_city | Required | String | Місто відправника | |
| sender_address | Required | String | Адреса відправника | |
| sender_state | Optional | String | Платіжна адреса. Код регіону відправника. Цифровий ISO 3166-2 код. Для України ISO 3166-2:UA | |
| sender_shipping_state | Optional | String | Адреса доставки. Код регіону відправника. Цифровий ISO 3166-2 код. Для України ISO 3166-2:UA | |
| sender_postal_code | Required | String | Поштовий індекс відправника |
Параметри розщеплення платежу:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| split_rules | Optional | String | Платіж з розщепленням суми на декількох одержувачів. У цьому параметрі вказується JSON масив з правилами розщеплення платежу. При використанні параметра split_rules відбувається одне списання з клієнта і кілька зарахувань одержувачам. Якщо необхідно передавати своє призначення по кожній сумі використовуйте параметр description. Якщо необхідно фіскалізувати платежі по кожному одержувачу слід додати об'єкт rro_info. Еквайрингова комісія стягується з кожного одержувача в масиві split_rules. Підключити можна за посиланням Приклад JSON рядка: |
[
{
"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"
}
]
|
Інші параметри:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| customer | Optional | String | Унікальний ідентифікатор користувача на сайті мерчанта. Максимальна довжина 100 символів. | |
| dae | Optional | String | Довгий запис Detail Addenda. Обов'язковий для мерчантів з МСС 4511 Параметр dae являє собою JSON рядок, до якого застосували функцію base64. JSON може містити параметри наведені у прикладі Приклад параметру dae: ewogICJhaXJMaW5lIjogIkROSVBST0FWSUEiLAogICJ0aWNrZXROdW1iZXIiOiAiQUNTRkQxMjM1NFNBIiwKICAicGFzc2VuZ2VyTmFtZSI6ICJKb2huIERvZSIsCiAgImZsaWdodE51bWJlciI6ICI3NDIiLAogICJvcmlnaW5DaXR5IjogIkRQIiwKICAiZGVzdGluYXRpb25DaXR5IjogIk5ZIiwKICAiZGVwYXJ0dXJlRGF0ZSI6ICIxMDA1MTQiCn0= |
{
"airLine": "Avia", // абревіатура авіакомпанії, max 4 символів.
"ticketNumber": "ACSFD12354SA", // номер бронювання (локатор), max 15 символів.
"passengerName": "John Doe", // ім'я пасажира, max 29 символів.
"flightNumber": "742", // dDae15, max 5 цифр.
"originCity": "DP", // код міста/аеропорту вильоту, max 5 символів.
"destinationCity": "NY", // код міста/аеропорту призначення, max 5 символів.
"departureDate": "100514" // дата вильоту в форматі YYMMDD, max 6 цифр.
}
|
| info | Optional | String | Інформація для додавання даних до платежу. Наприклад: «External information for payments» |
Параметри відповіді:
| Parameter | Type | Description | |
|---|---|---|---|
| acq_id | Number | ID еквайера | |
| action | String | Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, paysplit - розщеплення платежу, subscribe - створення регулярного платежу, paydonate - пожертвування, auth - предавторизація картки, regular - регулярний платіж | |
| agent_commission | Number | Комісія агента в валюті платежу | |
| amount | Number | Сума платежу | |
| amount_bonus | Number | Бонус відправника у валюті платежу debit | |
| amount_credit | Number | Сума транзакції credit в валюті currency_credit | |
| amount_debit | Number | Сума транзакції debit у валюті currency_debit | |
| authcode_debit | String | Код авторизації по транзакції debit | |
| card_token | String | Token картки відправника | |
| commission_credit | Number | Комісія з одержувача у валюті currency_credit | |
| commission_debit | Number | Комісія з відправника у валюті currency_debit | |
| confirm_phone | String | Телефон платника. На цей номер було відправлено OTP пароль підтвердження платежу та підв‘язаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +) | |
| create_date | String | Дата створення платежу | |
| currency | String | Валюта платежу | |
| currency_credit | String | Валюта транзакції credit | |
| currency_debit | String | Валюта транзакції debit | |
| description | String | Коментар до платежу | |
| ip | String | IP адреса відправника | |
| end_date | String | Дата завершення/зміни платежу | |
| is_3ds | Boolean | Можливі значення: true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки | |
| language | String | Мова клієнта uk, en | |
| liqpay_order_id | String | Order_id платежу в системі LiqPay | |
| mpi_eci | Number | Можливі значення: 5 - транзакція пройшла з 3DS (емітент і еквайєр підтримують технологію 3D-Secure), 6 - емітент картки платника не підтримує технологію 3D-Secure, 7 - операція пройшла без 3D-Secure | |
| order_id | String | Order_id платежу | |
| payment_id | Number | Id платежу в системі LiqPay | |
| paytype | String | Спосіб оплати. Можливі значення card - оплата картою, privat24 - через кабінет Приват24, moment_part - розстрочка, invoice - рахунок на e-mail, qr - сканування qr-коду | |
| public_key | String | Публічний ключ магазину | |
| receiver_commission | Number | Комісія з одержувача у валюті платежу | |
| result | String | Результат виконання запиту ok, error | |
| rrn_debit | String | Унікальний номер транзакції в системі авторизації і розрахунків обслуговуючого банку Retrieval Reference number | |
| sender_bonus | Number | Бонус відправника у валюті платежу | |
| sender_card_bank | String | Банк відправника | |
| sender_card_country | String | Країна картки відправника. Цифровий ISO 3166-1 код | |
| sender_card_mask2 | String | Карта відправника | |
| sender_card_type | String | Тип картки відправника MC/Visa | |
| sender_commission | Number | Комісія з відправника у валюті платежу | |
| sender_first_name | String | Ім'я відправника | |
| sender_last_name | String | Прізвище відправника | |
| sender_phone | String | Телефон відправника | |
| status | String | Статус платежу. Можливі значення: Кінцеві статуси платежу error - Неуспішний платіж. Некоректно заповнені дані failure - Неуспішний платіж reversed - Платіж повернений success - Успішний платіж Статуси що потребують підтвердження платежу cvv_verify - Потрібне введення CVV картки відправника. Для завершення платежу, потрібно виконати cvv_verify otp_verify - Потрібне OTP підтвердження клієнта. OTP пароль відправлений на номер телефону Клієнта. Для завершення платежу, потрібно виконати otp_verify Інші статуси платежу hold_wait - Сума успішно заблокована на рахунку відправника wait_accept - Кошти з клієнта списані, але магазин ще не пройшов перевірку. Якщо магазин не пройде активацію протягом 60 днів, платежі будуть автоматично скасовані wait_secure - Платіж на перевірці | |
| transaction_id | Number | Id транзакції в системі LiqPay | |
| type | String | Тип платежу | |
| version | Number | Версія API. Поточне значення - 7 |
Приклад відповіді:
{
"acq_id": "414963",
"action": "hold",
"agent_commission": "0.0",
"amount_bonus": "0.02",
"amount_credit": "0.1",
"amount_debit": "0.1",
"amount": "0.1",
"authcode_debit": "805256",
"card_token": "27AA8744A98339BB9E85D50AEB718A93B470395C",
"commission_credit": "0.0",
"commission_debit": "0.0",
"confirm_phone": "380912345678",
"create_date": "1715323287407",
"currency_credit": "UAH",
"currency_debit": "UAH",
"currency": "UAH",
"description": "testing pay by card",
"ip": "8.8.0.0",
"is_3ds": "false",
"language": "uk",
"liqpay_order_id": "YHVDEMXJ1715323369444359",
"mpi_eci": "7",
"order_id": "idByCard345D308",
"payment_id": "13291299",
"paytype": "card",
"public_key": "i16202663459",
"receiver_commission": "0.0",
"result": "ok",
"rrn_debit": "000000454153",
"sender_bonus": "0.02",
"sender_card_bank": "pb",
"sender_card_country": "804",
"sender_card_mask2": "432100*63",
"sender_card_type": "mc",
"sender_commission": "0.0",
"sender_first_name": "Тестувальник",
"sender_last_name": "Тестовий",
"sender_phone": "380912345678",
"status": "hold_wait",
"transaction_id": "13291299",
"type": "hold",
"version": "7"
}
Завершення
Необхідні URL для роботи в залежності від обраної моделі:
- https://www.liqpay.ua/api/request — Server-Server;
- https://www.liqpay.ua/api/3/checkout — Client-Server;
Для виклику API LiqPay необхідно передати параметри data і signature (Server - Server) POST методом або перенаправити клієнта (Client-Server) використовуючи POST метод, де:
data
- json рядок з параметрами APIs закодована функцією base64, base64_encode( json_string ),
signature
- унікальний підпис кожного запиту base64_encode( sha3-256( private_key + data + private_key) ),
base64_encode
- повертає рядок, закодований методом base64,
sha3-256
- повертає хеш у вигляді бінарного рядку з 32 байт (64 символи).
Формування data і signature, приклад:
Для підключення прийому оплати через LiqPay, формуємо json рядок з параметрами виклику апі, де:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| version | Required | Number | Версія API. Наприклад: 7 | |
| public_key | Required | String | Публічний ключ - ідентифікатор створеної компанії. Наприклад: i00000000 | |
| private_key | Required | String | Приватний ключ створеної компанії (не надається нікому крім Вашого розробника). Наприклад: a4825234f4bae72a0be04eafe9e8e2bada209255 | |
| action | Required | String | Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, subscribe - регулярний платіж, paydonate - пожертва, auth - предавторізація картки | |
| amount | Required | Number | Сума платежу. Наприклад: 5, 7.34 | |
| currency | Required | String | Валюта платежу. Можливі значення:USD, EUR, UAH. Додаткові валюти можуть бути встановлені за запитом компанії | |
| description | Required | String | Призначення платежу | |
| order_id | Required | String | Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів |
Більше параметрів в документації
Приклад створення json_string:
json_string =
{"public_key":"i00000000","version":7,"action":"pay","amount":"3","currency":"UAH","description":"test","order_id":"000001"}Приклад кодування json_string функцією base64_encode, компанія отримує data:
data = eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ==
Приклад формування signature, компанія формує рядок sign_string шляхом конкатенації private_key + data + private_key:
sign_string = a4825234f4bae72a0be04eafe9e8e2bada209255eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ==a4825234f4bae72a0be04eafe9e8e2bada209255
Після застосування функцій base64_encode( sha3-256( sign_string) ) отримуємо рядок:
signature = 0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s=
Приклад відправки запиту до LiqPay:
1.Для перенаправлення клієнта на сторінку оплати LiqPay (Client - Server) необхідно сформувати HTML-форму:
<form method="POST" action="https://www.liqpay.ua/api/3/checkout" accept-charset="utf-8">
<input type="hidden" name="data"
value="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
<input type="hidden" name="signature" value="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="/><input
type="image" src="//static.liqpay.ua/buttons/payUk.png"/></form>
<input type="hidden" name="data"
value="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
<input type="hidden" name="signature" value="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="/><input
type="image" src="//static.liqpay.ua/buttons/payUk.png"/></form>
2.Для взаємодії (Server - Server) отримані data і signature необхідно відправити на url https://www.liqpay.ua/api/request:
curl --silent -XPOST https://www.liqpay.ua/api/request --data-
urlencodedata="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
--data-urlencode
signature="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="
urlencodedata="eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6NywiYWN0aW9uIjoicGF5IiwiYW1vdW50IjoiMyIsImN1cnJlbmN5IjoiVUFIIiwiZGVzY3JpcHRpb24iOiJ0ZXN0Iiwib3JkZXJfaWQiOiIwMDAwMDEifQ=="/>
--data-urlencode
signature="0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s="
3.Статус операції буде відправлений на server_url
4.Успішне завершення оплати
Приклад використання SDK:
#!/bin/bash
PUBLIC_KEY='your_public_key'
PRIVATE_KEY='your_private_key'
API_URL='https://www.liqpay.ua/api/request'
JSON="{
\"action\" : \"hold_completion\",
\"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}"
$liqpay = new LiqPay($public_key, $private_key);
$res = $liqpay->api("request", array(
'action' => 'hold_completion',
'version' => '3',
'order_id' => 'order_id_1'
));
HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "hold_completion");
params.put("version", "3");
params.put("order_id", "order_id_1");
LiqPay liqpay = new LiqPay(PUBLIC_KEY, PRIVATE_KEY);
HashMap<String, Object> res = liqpay.api("request", params);
System.out.println(res.get("status"));
from liqpay import LiqPay
liqpay = LiqPay(public_key, private_key)
res = liqpay.api("request", {
"action" : "hold_completion",
"version" : "3",
"order_id" : "order_id_1"
})
liqpay = Liqpay::Liqpay.new(
:public_key => 'public_key',
:private_key => 'private_key'
)
res = liqpay.api("request", {
:action => "hold_completion",
:version => "3",
:order_id => "order_id_1"
})
LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>, <<"hold_completion">>},
{<<"version">>, <<"3">>},
{<<"order_id">>, <<"order_id_1">>}
], LiqPay)
var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
liqpay.api("request", {
"action" : "hold_completion",
"version" : "3",
"order_id" : "order_id_1"
}, function( json ){
console.log( json.status );
});
my $liqpay = Liqpay->new($public_key,$private_key);
my $res = $liqpay->api("request",
{
'action' => 'hold_completion',
'version' => '3',
'order_id' => 'order_id_1'
}
);
var c = liqpay.New("my_public_key", "my_private_key", nil)
// Creating the request map with all necessary parameters
request:=map[string]interface{}{
"action": "hold_completion",
"version": 3,
"public_key": "my_public_key",
"order_id": "order_id_1",
}
resp, err := c.Send("request", request)
if err != nil {
fmt.Printf("error %v", err.Error())
return
}
fmt.Printf("response: %#v", resp)
Параметри для формування data:
Основні
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| version | Required | Number | Версія API. Поточне значення - 7 | |
| public_key | Required | String | Публічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину | |
| action | Required | String | hold_completion | |
| amount | Required | Number | Сума платежу. Наприклад: 5, 7.34 | |
| order_id | Required | String | Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів | |
| rro_info | Optional | Object | Дані для фіскалізації |
Дані для фіскалізації (об'єкт rro_info):
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| items | Optional | Array | Дані про товари, за які здійснюється оплата | |
| delivery_emails | Optional | Array | Перелік e-mail, на які треба відправити квитанції після фіскалізації |
Дані про товари, за які здійснюється оплата (масив items):
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| amount | Required | Number | Кількість/обʼєм | |
| cost | Required | Number | Вартість всіх одиниць вказанного товару в чеку (кількість * вартість одиниці) | |
| id | Required | Number | Ідентифікатор товару. Отримати можна в кабінеті Liqpay - РРО - Каса - Товари | |
| price | Required | Number | Вартість одиниці товару |
Приклад даних про товари:
rro_info: {
"items": [
{
"amount": 2,
"price": 202,
"cost": 404,
"id": 123456
}
],
"delivery_emails": ["email1@email.com", "email2@email.com"]
}
Параметри розщеплення платежу:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| split_tickets_only | Optional | Boolean | Ознака не фактичного розщеплення. Якщо значення split_tickets_only: true та массив split_rules передаються, платіж пройде без фактичного розщеплення на декількох отримувачів |
Параметри відповіді:
| Parameter | Type | Description | |
|---|---|---|---|
| acq_id | Number | ID еквайера | |
| action | String | Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, paysplit - розщеплення платежу, subscribe - створення регулярного платежу, paydonate - пожертвування, auth - предавторизація картки, regular - регулярний платіж | |
| agent_commission | Number | Комісія агента в валюті платежу | |
| amount | Number | Сума платежу | |
| amount_bonus | Number | Бонус відправника у валюті платежу debit | |
| amount_credit | Number | Сума транзакції credit в валюті currency_credit | |
| amount_debit | Number | Сума транзакції debit у валюті currency_debit | |
| authcode_credit | String | Код авторизації по транзакції credit | |
| authcode_debit | String | Код авторизації по транзакції debit | |
| card_token | String | Token картки відправника | |
| commission_credit | Number | Комісія з одержувача у валюті currency_credit | |
| commission_debit | Number | Комісія з відправника у валюті currency_debit | |
| completion_date | String | Дата списання коштів | |
| confirm_phone | String | Телефон платника. На цей номер було відправлено OTP пароль підтвердження платежу та підв‘язаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +) | |
| create_date | String | Дата створення платежу | |
| currency | String | Валюта платежу | |
| currency_credit | String | Валюта транзакції credit | |
| currency_debit | String | Валюта транзакції debit | |
| description | String | Коментар до платежу | |
| ip | String | IP адреса відправника | |
| end_date | String | Дата завершення/зміни платежу | |
| is_3ds | Boolean | Можливі значення: true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки | |
| language | String | Мова клієнта uk, en | |
| liqpay_order_id | String | Order_id платежу в системі LiqPay | |
| mpi_eci | Number | Можливі значення: 5 - транзакція пройшла з 3DS (емітент і еквайєр підтримують технологію 3D-Secure), 6 - емітент картки платника не підтримує технологію 3D-Secure, 7 - операція пройшла без 3D-Secure | |
| order_id | String | Order_id платежу | |
| payment_id | Number | Id платежу в системі LiqPay | |
| paytype | String | Спосіб оплати. Можливі значення card - оплата картою, privat24 - через кабінет Приват24, moment_part - розстрочка, invoice - рахунок на e-mail, qr - сканування qr-коду | |
| public_key | String | Публічний ключ магазину | |
| receiver_commission | Number | Комісія з одержувача у валюті платежу | |
| result | String | Результат виконання запиту ok, error | |
| rrn_credit | String | Унікальний номер транзакції в системі авторизації і розрахунків обслуговуючого банку Retrieval Reference number | |
| rrn_debit | String | Унікальний номер транзакції в системі авторизації і розрахунків обслуговуючого банку Retrieval Reference number | |
| sender_bonus | Number | Бонус відправника у валюті платежу | |
| sender_card_bank | String | Банк відправника | |
| sender_card_country | String | Країна картки відправника. Цифровий ISO 3166-1 код | |
| sender_card_mask2 | String | Карта відправника | |
| sender_card_type | String | Тип картки відправника MC/Visa | |
| sender_commission | Number | Комісія з відправника у валюті платежу | |
| sender_first_name | String | Ім'я відправника | |
| sender_last_name | String | Прізвище відправника | |
| sender_phone | String | Телефон відправника | |
| status | String | Статус платежу. Можливі значення: Кінцеві статуси платежу error - Неуспішний платіж. Некоректно заповнені дані failure - Неуспішний платіж success - Успішний платіж | |
| transaction_id | Number | Id транзакції в системі LiqPay | |
| type | String | Тип платежу | |
| version | Number | Версія API. Поточне значення - 7 |
Приклад відповіді:
{
"acq_id": "414963",
"action": "hold",
"agent_commission": "0.0",
"amount_bonus": "0.02",
"amount_credit": "0.1",
"amount_debit": "0.1",
"amount": "0.1",
"authcode_credit": "124257",
"authcode_debit": "805256",
"card_token": "27AA8744A98339BB9E85D50AEB718A93B470395C",
"commission_credit": "0.0",
"commission_debit": "0.0",
"completion_date": "1715330216463",
"confirm_phone": "380912345678",
"create_date": "1715323287407",
"currency_credit": "UAH",
"currency_debit": "UAH",
"currency": "UAH",
"description": "testing pay by card",
"end_date": "1715330217449",
"ip": "8.8.0.0",
"is_3ds": "false",
"language": "uk",
"liqpay_order_id": "YHVDEMXJ1715323369444359",
"mpi_eci": "7",
"order_id": "idByCard345D308",
"payment_id": "13291299",
"paytype": "card",
"public_key": "i16202663459",
"receiver_commission": "0.0",
"result": "ok",
"rrn_credit": "000000454715",
"rrn_debit": "000000454153",
"sender_bonus": "0.02",
"sender_card_bank": "pb",
"sender_card_country": "804",
"sender_card_mask2": "432100*63",
"sender_card_type": "mc",
"sender_commission": "0.0",
"sender_first_name": "Тестувальник",
"sender_last_name": "Тестовий",
"sender_phone": "380912345678",
"status": "success",
"transaction_id": "13291299",
"type": "hold",
"version": "7"
}