Публічний
Checkout
Персоналізована платіжна сторінка - 10 методів оплати
Схема роботи checkout
Підключення
- Створіть компанію в LiqPay за посиланням:
Після реєстрації для Вашої компанії автоматично будуть створені унікальні ключі доступу до API:
public_key - унікальний ідентифікатор Вашої компанії в системі LiqPay
private_key - секретний ключ доступу до API - Відповідно до технічної документації сформуйте запит на 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'
JSON="{
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\",
\"action\" : \"pay\",
\"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)
echo "data: ${DATA}"
echo "signature: ${SIGNATURE}"
# DATA in this example
# eyAidmVyc2lvbiIgOiAzLCAicHVibGljX2tleSIgOiAieW91cl9wdWJsaWNfa2V5IiwgImFjdGlv
# biIgOiAicGF5IiwgImFtb3VudCIgOiAxLCAiY3VycmVuY3kiIDogIlVTRCIsICJkZXNjcmlwdGlv
# biIgOiAiZGVzY3JpcHRpb24gdGV4dCIsICJvcmRlcl9pZCIgOiAib3JkZXJfaWRfMSIgfQ==
# SIGNATURE in this example
# QvJD5u9Fg55PCx/Hdz6lzWtYwcI=
Приклад HTML-форми:
<form method="POST" action="https://www.liqpay.ua/api/3/checkout"
accept-charset="utf-8">
<input type="hidden" name="data" value="eyAidmVyc2lvbiIgOiAzLCAicHVibGljX2tleSIgOiAieW91cl9wdWJsaWNfa2V5IiwgImFjdGlv
biIgOiAicGF5IiwgImFtb3VudCIgOiAxLCAiY3VycmVuY3kiIDogIlVTRCIsICJkZXNjcmlwdGlv
biIgOiAiZGVzY3JpcHRpb24gdGV4dCIsICJvcmRlcl9pZCIgOiAib3JkZXJfaWRfMSIgfQ=="/>
<input type="hidden" name="signature" value="QvJD5u9Fg55PCx/Hdz6lzWtYwcI="/>
<input type="image"
src="//static.liqpay.ua/buttons/payUk.png"/>
</form>
Параметри для формування data:
Основні
Parameter | Required | Type | Description | |
---|---|---|---|---|
version | Required | Number | Версія API. Поточне значення - 3 | |
public_key | Required | String | Публічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину | |
action | Required | String | Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, subscribe - регулярний платіж, paydonate - пожертва | |
amount | Required | Number | Сума платежу. Наприклад: 5, 7.34 | |
currency | Required | String | Валюта платежу. Можливі значення: USD, EUR, UAH | |
description | Required | String | Призначення платежу | |
order_id | Required | String | Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів | |
rro_info | Optional | Object | Дані для фіскалізації | |
expired_date | Optional | String | Час до якого клієнт може оплатити рахунок за UTC. Передається в форматі 2016-04-24 00:00:00 | |
language | Optional | String | Мова клієнта uk, en | |
paytypes | Optional | String | Параметр в якому передаються способи оплати, які будуть відображені на чекауті. Можливі значення apay - оплата за допомогою Apple Pay, gpay - оплата за допомогою Google Pay, card - оплата карткою, privat24 - через кабінет приват24, moment_part - розстрочка, paypart - оплата частинами, cash - готівкою, invoice - рахунок на e-mail, qr - сканування qr-коду. Якщо параметр не переданий, то застосовуються налаштування магазину, вкладка Checkout | |
result_url | Optional | String | URL у Вашому магазині на який покупця буде переадресовано після завершення покупки. Максимальна довжина 510 символів | |
server_url | Optional | String | URL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше | |
verifycode | Optional | String | Можливе значення Y. Динамічний код верифікації, генерується і повертається в Callback. Так само згенерований код буде переданий в транзакції верифікації для відображення у виписці по картці клієнта. Працює для action = auth |
Дані для фіскалізації (об'єкт 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_rules | Optional | String | Платіж з розщепленням суми на декількох одержувачів. У цьому параметрі вказується JSON масив з правилами розщеплення платежу. При використанні параметра split_rules відбувається одне списання з клієнта і кілька зарахувань одержувачам. Якщо необхідно передавати своє призначення по кожній сумі використовуйте параметр description. Якщо необхідно фіскалізувати платежі по кожному одержувачу слід додати об'єкт rro_info. Еквайрингова комісія стягується з кожного одержувача в масиві split_rules. Приклад JSON рядка: |
|
Параметри відправника:
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 | |
---|---|---|---|---|
subscribe | Optional | String | Регулярний платіж. Можливі значення: 1 | |
subscribe_date_start | Required | String | Дата першого платежу. Час необхідно вказувати в такому форматі 2015-03-31 00:00:00 по UTC. Якщо вказана минула дата, то підписка буде активована з поточної дати отримання запиту | |
subscribe_periodicity | Optional | String | Періодичність списання коштів. Можливі значення: day - щодня, week - щотижня, month - раз на місяць, year - раз на рік |
Параметри для оплати в 1 клік:
Parameter | Required | Type | Description | |
---|---|---|---|---|
customer | Optional | String | Унікальний ідентифікатор клієнта на сайті мерчанта. При передачі параметра LiqPay запам'ятовує платіжні реквізити клієнта і його ідентифікатор - подальша оплата може бути проведена в 1 клік. Максимальна довжина 100 символів. (При використанні параметра для Masterpass 1 клік, в даному полі передається валідний номер телефону платника) | |
recurringbytoken | Optional | String | Дозволяє генерувати card_token платника, який ви отримаєте в callback запиті на server_url. card_token дозволяє проводити платежі без введення реквізитів картки платника, використовуючи API оплати за токеном - тобто в 1 клік. Для отримання card_token необхідно передати в запиті значення: 1 | |
customer_user_id | Optional | String | Ідентифікатор користувача в системі мерчанта, передається при кожній оплаті користувача (не повинен збігатися з customer, використовується для оплати за допомогою гаманця Masterpass 1 клік) |
Інші параметри:
Parameter | Required | Type | Description | |
---|---|---|---|---|
dae | Optional | String | Довгий запис Detail Addenda. Обов'язковий для мерчантів з МСС 4511 Параметр dae являє собою JSON рядок, до якого застосували функцію base64. JSON може містити параметри наведені у прикладі Приклад параметру dae: ewogICJhaXJMaW5lIjogIkROSVBST0FWSUEiLAogICJ0aWNrZXROdW1iZXIiOiAiQUNTRkQxMjM1NFNBIiwKICAicGFzc2VuZ2VyTmFtZSI6ICJKb2huIERvZSIsCiAgImZsaWdodE51bWJlciI6ICI3NDIiLAogICJvcmlnaW5DaXR5IjogIkRQIiwKICAiZGVzdGluYXRpb25DaXR5IjogIk5ZIiwKICAiZGVwYXJ0dXJlRGF0ZSI6ICIxMDA1MTQiCn0= |
|
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 символів |