Приватний
Двостадійна оплата
Блокування коштів на картці клієнта для подальшого списання
Блокування
Схема роботи API двостадійної оплати
Формування запиту до 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( sha1( private_key + data + private_key) ),
base64_encode
- повертає рядок, закодований методом base64,
sha1
- повертає хеш у вигляді бінарного рядку з 20 символів.
Формування data і signature, приклад:
Для підключення прийому оплати через LiqPay, формуємо json рядок з параметрами виклику апі, де:
Parameter | Required | Type | Description | |
---|---|---|---|---|
version | Required | Number | Версія API. Наприклад: 3 | |
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":"3","action":"pay","amount":"3","currency":"UAH","description":"test","order_id":"000001"}
Приклад кодування json_string функцією base64_encode, компанія отримує data:
data = eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9
Приклад формування signature, компанія формує рядок sign_string шляхом конкатенації private_key + data + private_key:
sign_string = a4825234f4bae72a0be04eafe9e8e2bada209255eyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwIiwidmVyc2lvbiI6IjMiLCJhY3Rpb24iOiJwYXkiLCJhbW91bnQiOiIzIiwiY3VycmVuY3kiOiJVQUgiLCJkZXNjcmlwdGlvbiI6InRlc3QiLCJvcmRlcl9pZCI6IjAwMDAwMSJ9a4825234f4bae72a0be04eafe9e8e2bada209255
Після застосування функцій base64_encode( sha1( sign_string) ) отримуємо рядок:
signature = wR+UZDC4jjeL/qUOvIsofIWpZh8=
Приклад відправки запиту до 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="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.Для взаємодії (Server - Server) отримані data і signature необхідно відправити на 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.Статус операції буде відправлений на 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}"
Параметри для формування data:
Основні
Parameter | Required | Type | Description | |
---|---|---|---|---|
version | Required | Number | Версія API. Поточне значення - 3 | |
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 | |
recurring | Optional | Boolean | Ознака рекурентної оплати за токеном. Використовується для оплат за токеном міжнародних платіжних систем (MasterCard, Visa). Можливі значення true - операція виконується без участі клієнта, false - операція виконується клієнтом | |
server_url | Optional | String | URL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше | |
tavv | Required | String | Референс токена, отриманого при декриптуванні даних пристрою Apple |
Параметри відправника:
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 рядка: |
|
Інші параметри:
Parameter | Required | Type | Description | |
---|---|---|---|---|
customer | Optional | String | Унікальний ідентифікатор користувача на сайті мерчанта. Максимальна довжина 100 символів. | |
dae | Optional | String | Довгий запис Detail Addenda. Обов'язковий для мерчантів з МСС 4511 Параметр dae являє собою JSON рядок, до якого застосували функцію base64. JSON може містити параметри наведені у прикладі Приклад параметру dae: ewogICJhaXJMaW5lIjogIkROSVBST0FWSUEiLAogICJ0aWNrZXROdW1iZXIiOiAiQUNTRkQxMjM1NFNBIiwKICAicGFzc2VuZ2VyTmFtZSI6ICJKb2huIERvZSIsCiAgImZsaWdodE51bWJlciI6ICI3NDIiLAogICJvcmlnaW5DaXR5IjogIkRQIiwKICAiZGVzdGluYXRpb25DaXR5IjogIk5ZIiwKICAiZGVwYXJ0dXJlRGF0ZSI6ICIxMDA1MTQiCn0= |
|
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 receiver_verify - Потрібне введення даних одержувача. Для завершення платежу, потрібно виконати receiver_verify sender_verify - Потрібне введення даних відправника. Для завершення платежу, потрібно виконати sender_verify Інші статуси платежу hold_wait - Сума успішно заблокована на рахунку відправника wait_accept - Кошти з клієнта списані, але магазин ще не пройшов перевірку. Якщо магазин не пройде активацію протягом 60 днів, платежі будуть автоматично скасовані wait_secure - Платіж на перевірці | |
transaction_id | Number | Id транзакції в системі LiqPay | |
type | String | Тип платежу | |
version | Number | Версія API. Поточне значення - 3 |
Приклад відповіді:
{
"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": "380933454182",
"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": "545708*24",
"sender_card_type": "mc",
"sender_commission": "0.0",
"sender_first_name": "Тетяна",
"sender_last_name": "Станько",
"sender_phone": "380933454182",
"status": "hold_wait",
"transaction_id": "13291299",
"type": "hold",
"version": "3"
}