Приватний
Оплата по токену
Списання з картки клієнта по токену картки
Що таке оплата по токену?
Списання з картки клієнта коштів без повторного введення реквізитів картки. Ви отримуєте унікальний токен картки клієнта - списання відбувається без єдиного кліка. Клієнту не потрібно заходити на сайт або заповнювати реквізити картки. Токен картки клієнта може зберігатися на сервері компанії.
Можливості
Повторна оплата для клієнта в 1 клік - без необхідності кожного разу вводити реквізити картки
Розщеплення платежу на декількох одержувачів
Як працює оплата по токену
- Клієнт оплачує послугу на Вашому сайті перший раз - оплата проходить через платіжну сторінку Checkout або інші API:
- Після успішної оплати Ви отримуєте токен картки клієнта у відповіді від LiqPay.
- При наступних оплатах Вам достатньо передати в запиті токен картки, для проведення операції.
Підключення
Server-Server
Для отримання доступу до API необхідно
Відправити запит
Методи інтеграції
Самостійна інтеграція згідно з документацією
Є питання?
Звертайтесь до нашого технічного відділу на пошту:
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\" : \"paytoken\",
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\",
\"phone\" : \"380950000001\",
\"amount\" : 1,
\"currency\" : \"USD\",
\"description\" : \"description text\",
\"order_id\" : \"order_id_1\",
\"card_token\" : \"B5BВB0D00B88B00ED00A00D0D\"
}"
# 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' => 'paytoken',
'version' => '3',
'phone' => '380950000001',
'amount' => '1',
'currency' => 'USD',
'description' => 'description text',
'order_id' => 'order_id_1',
'card_token' => 'B5BВB0D00B88B00ED00A00D0D'
));
HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "paytoken");
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_token", "B5BВB0D00B88B00ED00A00D0D");
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" : "paytoken",
"version" : "3",
"phone" : "380950000001",
"amount" : "1",
"currency" : "USD",
"description" : "description text",
"order_id" : "order_id_1",
"card_token" : "B5BВB0D00B88B00ED00A00D0D"
})
liqpay = Liqpay::Liqpay.new(
:public_key => 'public_key',
:private_key => 'private_key'
)
res = liqpay.api("request", {
:action => "paytoken",
:version => "3",
:phone => "380950000001",
:amount => "1",
:currency => "USD",
:description => "description text",
:order_id => "order_id_1",
:card_token => "B5BВB0D00B88B00ED00A00D0D"
})
LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>, <<"paytoken">>},
{<<"version">>, <<"3">>},
{<<"phone">>, <<"380950000001">>},
{<<"amount">>, <<"1">>},
{<<"currency">>, <<"USD">>},
{<<"description">>, <<"description text">>},
{<<"order_id">>, <<"order_id_1">>},
{<<"card_token">>, <<"B5BВB0D00B88B00ED00A00D0D">>}
], LiqPay)
var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
liqpay.api("request", {
"action" : "paytoken",
"version" : "3",
"phone" : "380950000001",
"amount" : "1",
"currency" : "USD",
"description" : "description text",
"order_id" : "order_id_1",
"card_token" : "B5BВB0D00B88B00ED00A00D0D"
}, function( json ){
console.log( json.status );
});
my $liqpay = Liqpay->new($public_key,$private_key);
my $res = $liqpay->api("request",
{
'action' => 'paytoken',
'version' => '3',
'phone' => '380950000001',
'amount' => '1',
'currency' => 'USD',
'description' => 'description text',
'order_id' => 'order_id_1',
'card_token' => 'B5BВB0D00B88B00ED00A00D0D'
}
);
var c = liqpay.New("my_public_key", "my_private_key", nil)
// Creating the request map with all necessary parameters
request:=map[string]interface{}{
"action": "paytoken",
"version": 3,
"public_key": "my_public_key",
"phone": "380950000001",
"amount": 1,
"currency": "UAH",
"description": "Test payment",
"order_id": "order_id_1",
"card_token": "B5BВB0D00B88B00ED00A00D0D",
}
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 | paytoken | |
| amount | Required | Number | Сума платежу. Наприклад: 5, 7.34 | |
| card_token | Required | String | Токен картки платника. Наприклад: B5BВB0D00B88B00ED00A00D0D (При використанні токену дані картки передавати не потрібно) | |
| currency | Required | String | Валюта платежу. Можливі значення: USD, EUR, UAH | |
| description | Required | String | Призначення платежу | |
| ip | Required | String | IP клієнта | |
| order_id | Required | String | Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів | |
| phone | Optional | String | Телефон платника. На цей номер буде відправлений OTP пароль підтвердження платежу та підвязаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +) | |
| language | Optional | String | Мова клієнта uk, en | |
| prepare | Optional | String | Попередня підготовка платежу. Цей режим дозволяє визначити чи заповнені всі дані , чи потрібна 3DS перевірка картки, чи не перевищено ліміт. Гроші з картки платника не списуються. Для включення режиму необхідно передати значення 1 | |
| server_url | Optional | String | URL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше |
Параметри розщеплення платежу:
| 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"
}
]
|
| split_tickets_only | Optional | Boolean | Ознака не фактичного розщеплення. Якщо значення split_tickets_only: true та массив split_rules передаються, платіж пройде без фактичного розщеплення на декількох отримувачів |
Параметри відправника:
| Parameter | Required | Type | Description | |
|---|---|---|---|---|
| sender_address | Optional | String | Адреса відправника | |
| sender_city | Optional | String | Місто відправника | |
| sender_country_code | Optional | String | Код країни відправника. Цифровий ISO 3166-1 код | |
| sender_first_name | Optional | String | Ім'я відправника | |
| sender_last_name | Optional | String | Прізвище відправника | |
| sender_postal_code | Optional | String | Поштовий індекс відправника |
Інші параметри:
| 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» | |
| product_category | Optional | String | Категорія товару. Максимальна довжина 25 символів | |
| product_description | Optional | String | Опис товару. Максимальна довжина 500 символів | |
| product_name | Optional | String | Назва товару. Максимальна довжина 100 символів | |
| product_url | Optional | String | Адреса сторінки з товаром. Максимальна довжина 510 символів | |
| is_recurring | Optional | Boolean | Ознака рекурентної оплати за токеном. Можливі значення true - операція виконується без участі клієнта, false - операція виконується клієнтом |
Параметри відповіді:
| 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 | |
| bonus_procent | Number | Розмір знижки в процентах | |
| bonus_type | String | Тип бонусу, можливі значення bonusplus, discount_club, personal, promo | |
| 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 | Коментар до платежу | |
| end_date | String | Дата завершення/зміни платежу | |
| ip | String | IP адреса відправника | |
| 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 - Неуспішний платіж reversed - Платіж повернений success - Успішний платіж Інші статуси платежу wait_accept - Кошти з клієнта списані, але магазин ще не пройшов перевірку. Якщо магазин не пройде активацію протягом 60 днів, платежі будуть автоматично скасовані wait_secure - Платіж на перевірці | |
| transaction_id | Number | Id транзакції в системі LiqPay | |
| type | String | Тип платежу | |
| version | Number | Версія API. Поточне значення - 7 |
Приклад відповіді:
{
"acq_id": "414963",
"action": "pay",
"agent_commission": "0.0",
"amount_bonus": "0.01",
"amount_credit": "0.2",
"amount_debit": "0.2",
"amount": "0.2",
"authcode_credit": "628292",
"authcode_debit": "642291",
"bonus_procent": "5.0",
"bonus_type": "promo",
"card_token": "811D840858969FD9DB4DF7040161BD1C324C983C",
"commission_credit": "0.0",
"commission_debit": "0.0",
"confirm_phone": "380912345678",
"create_date": "1717058255167",
"currency_credit": "UAH",
"currency_debit": "UAH",
"currency": "UAH",
"description": "Pay by token",
"end_date": "1717058257356",
"ip": "0.0.0.0",
"is_3ds": "false",
"language": "uk",
"liqpay_order_id": "V7NCWJBH1717058255159399",
"mpi_eci": "7",
"order_id": "id446789m",
"payment_id": "13293344",
"paytype": "token",
"public_key": "i16202663459",
"receiver_commission": "0.0",
"result": "ok",
"rrn_credit": "000000468437",
"rrn_debit": "000000468436",
"sender_bonus": "0.01",
"sender_card_bank": "pb",
"sender_card_country": "804",
"sender_card_mask2": "432100*63",
"sender_card_type": "mc",
"sender_commission": "0.0",
"sender_first_name": "Maria",
"sender_last_name": "GHenm",
"sender_phone": "380912345678",
"status": "success",
"transaction_id": "13293344",
"type": "buy",
"version": "7"
}