Публічний
Платіжний віджет
Віджет для прийому платежів на web сторінці сайту
Що таке платіжний віджет?
Спосіб прийому платежів на Вашому сайті без перенаправлення клієнта на окрему платіжну сторінку.
Віджет інтегрується безпосередньо на сторінку сайту - клієнт обирає метод оплати, заповнює реквізити картки і підтверджує оплату в віджеті.
Основні можливості:
10 методів оплати
Автозаповнення адреси доставки
Оплата в 1 клік (3 варіанти)
Промо-коди та знижки
Підписка на регулярне списання
Конструктор дизайну
Адаптація під всі пристрої
Предавторизація картки
Платіж з довільною сумою
Блокування коштів
Розщеплення платежу на декількох одержувачів
Захищений платіж з гарантією оплати
Методи оплати:
Apple Pay
Прийом оплати від клієнта за допомогою пристроїв компанії Apple.
Google Pay
Зручний спосіб оплати від Google.
QR-код оплата в 1 клік
Для оплати по QR-коду клієнту необхідно встановити мобільний додаток Privat24 для платформ iOS або AOS.
Відсканувати QR-код на платіжній сторінці і натиснути кнопку «Підтвердити» в отриманій формі.
Картка
На платіжній сторінці приймаються дебетні, кредитні та корпоративні картки Mastercard і Visa.
PrivatPay
Оплата за допомогою інтернет-банку Приват24.
Розстрочка
Ваші клієнти зможуть оплатити товар в розстрочку від ПриватБанку - Ви отримуєте повну суму відшкодування на рахунок або картку. Детальніше про умови Миттєвої розстрочки.
Оплата готівкою
Ваші клієнти можуть оплатити готівкою у терміналах самообслуговування.
Рахунок на email
Зручний спосіб відкладеної оплати. Ваш клієнт отримає повідомлення (інвойс) на email з кнопкою «Оплатити» і може зробити оплату в будь-який момент.
Оплата в один клік (3 варіанти)
1
Оплата по QR-коду
У платіжному віджеті LiqPay клієнтам доступний QR-код, відсканувавши який за допомогою додатку Privat24, клієнт здійснює оплату лише в 1 клік - досить натиснути кнопку «Підтвердити» в отриманій формі оплати.
2
Оплата по токену
Вашим постійним клієнтам більше не потрібно кожного разу вводити реквізити картки для сплати рахунку. Наступні оплати Ви можете приймати за допомогою токена картки клієнта, який Ви отримаєте на server-url після оплати через API Checkout.
3
Запам'ятовування даних клієнта
LiqPay запам'ятовує дані клієнта за унікальним ідентифікатором у Вашій системі - наступні оплати клієнта пройдуть в 1 клік. Вам не потрібно зберігати токени клієнтів на Вашій стороні.
Оплата в 1 клік із запам'ятовуванням клієнтів може бути активована для Вас додатково менеджером LiqPay.
Які типи платежів підтримує платіжний віджет
pay - пряме списання з картки
hold - блокування коштів на картці клієнта в рамках двостадійної оплати
subscribe - оформлення підписки
paydonate - прийом пожертвувань з довільною сумою
split_rules - розщеплення платежу на декількох одержувачів
apay - оплата за допомогою Apple Pay
gpay - оплата за допомогою Google Pay
Як працює платіжний віджет LiqPay
- Сформуйте запит на API Платіжний віджет згідно з технічною документацією.
- Встановіть HTML-код віджету на сторінку Вашого сайту.
- Клієнт заповнює реквізити карти і підтверджує оплату на платіжному віджеті LiqPay.
- За результатом - Ви отримуєте відповідь від LiqPay про статус оплати.
Інтеграція
Для створення платіжного віджета на сторінці необхідно оголосити об'єкт LiqPayCheckout і передати на вхід функції init параметри - data, signature, embedTo, mode, language, де:
data і signature - обов'язкові параметри для роботи з LiqPay
embedTo - елемент на HTML-сторінці в якому буде відображений віджет
mode - режим відображення віджета на сайті
language - мова платіжного віджета
Для отримання результату платежу на вхід функції on потрібно передати liqpay.callback і функцію яка буде виконана при обробці цієї події.
Також можна обробити подію відкриття і закриття віджета передавши на функцію on події liqpay.ready і liqpay.close і відповідні функції, які виконуються при настанні цієї події.
Також можна обробити подію відкриття і закриття віджета передавши на функцію on події liqpay.ready і liqpay.close і відповідні функції, які виконуються при настанні цієї події.
Є питання?
Звертайтесь до нашого технічного відділу на пошту:
liqpay.support@privatbank.ua
Схема роботи платіжного віджету:

Підключення
- Створіть компанію в LiqPay за посиланням:
Після реєстрації для Вашої компанії автоматично будуть створені унікальні ключі доступу до API:
public_key - унікальний ідентифікатор Вашої компанії в системі LiqPay
private_key - секретний ключ доступу до 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.Успішне завершення оплати
Приклад JS віджета:
<div id="liqpay_checkout"></div>
<script>
globalThis.LiqPayCheckoutCallback = function() {
LiqPayCheckout.init({
data: "eyAidmVyc2lvbiIgOiAzLCAicHVibGljX2tleSIgOiAieW91cl9wdWJsaWNfa2V5IiwgImFjdGlv" +
"biIgOiAicGF5IiwgImFtb3VudCIgOiAxLCAiY3VycmVuY3kiIDogIlVTRCIsICJkZXNjcmlwdGlv" +
"biIgOiAiZGVzY3JpcHRpb24gdGV4dCIsICJvcmRlcl9pZCIgOiAib3JkZXJfaWRfMSIgfQ==",
signature: "QvJD5u9Fg55PCx/Hdz6lzWtYwcI=",
embedTo: "#liqpay_checkout",
language: "uk",
mode: "embed" // embed || popup
}).on("liqpay.callback", function(data){
console.log(data.status);
console.log(data);
}).on("liqpay.ready", function(data){
// ready
}).on("liqpay.close", function(data){
// close
});
};
</script>
<script src="//static.liqpay.ua/libjs/checkout.js" async></script>
Параметри платіжного віджета:
| data | Required | String | json рядок з параметрами APIs закодований функцією base64_encode( json_string ), де base64_encode - повертає рядок, закодований методом base64 | |
| signature | Required | String | Унікальний підпис кожного запиту base64_encode( sha3-256( private_key + data + private_key) ), де sha3-256 - повертає хеш у вигляді бінарного рядку з 20 символів | |
| embedTo | Optional | String | Елемент на HTML-сторінці в якому буде відображений віджет | |
| mode | Optional | String | Режим відображення віджета на сайті. Можливі значення: embed - вбудоване вікно, popup - спливаюче вікно на Вашому сайті | |
| language | Optional | String | Мова відображення віджету uk,en |
Приклад використання 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=
$liqpay = new LiqPay($public_key, $private_key); $html = $liqpay->cnb_form(array( 'action' => 'pay', 'amount' => '1', 'currency' => 'USD', 'description' => 'description text', 'order_id' => 'order_id_1', 'version' => '3' ));
HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "pay");
params.put("amount", "1");
params.put("currency", "USD");
params.put("description", "description text");
params.put("order_id", "order_id_1");
params.put("version", "3");
LiqPay liqpay = new LiqPay(PUBLIC_KEY, PRIVATE_KEY);
String html = liqpay.cnb_form(params);
System.out.println(html);
liqpay = LiqPay(public_key, private_key)
html = liqpay.cnb_form({
"action" : "pay",
"amount" : "1",
"currency" : "USD",
"description" : "description text",
"order_id" : "order_id_1",
"version" : "3"
})
liqpay = Liqpay::Liqpay.new(
:public_key => 'public_key',
:private_key => 'private_key'
)
html = liqpay.cnb_form({
:action => "pay",
:amount => "1",
:currency => "USD",
:description => "description text",
:order_id => "order_id_1",
:version => "3"
})
LiqPay = liqpay:init(PublicKey, PrivateKey),
Html = liqpay:cnb_form([
{<<"action">>, <<"pay">>},
{<<"amount">>, <<"1">>},
{<<"currency">>, <<"USD">>},
{<<"description">>, <<"description text">>},
{<<"order_id">>, <<"order_id_1">>},
{<<"version">>, <<"3">>}
], LiqPay)
var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
var html = liqpay.cnb_form({
'action' : 'pay',
'amount' : '1',
'currency' : 'USD',
'description' : 'description text',
'order_id' : 'order_id_1',
'version' : '3'
});
my $liqpay = Liqpay->new($public_key,$private_key);
my $html = $liqpay->cnb_form({
'action' => 'pay',
'amount' => '1',
'currency' => 'USD',
'description' => 'description text',
'order_id' => 'order_id_1',
'version' => '3'
}
);
func main() {
var c = liqpay.New("my_public_key", "my_private_key", nil)
request := map[string]interface{}{
"action": "pay",
"version": 3,
"public_key": "my_public_key",
"amount": 3,
"currency": "USD",
"description": "payment description",
"order_id": "67014f40-8d58-4dc8-b7e2-e8fe1afb48",
}
resp, err := c.RenderForm(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 | Тип операції. Можливі значення: 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 символів | |
| 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 | |
| sender_email | Optional | String | Email для відправки квитанції |
Параметри розщеплення платежу:
| 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 | |
|---|---|---|---|---|
| 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= |
{
"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 символів |