Приватний

Підписка

Регулярний білінг Ваших клієнтів за методом server-server

Що таке підписка?

Регулярне списання з клієнта за методом server-server, із зазначеною датою першого списання та періодичністю.

Можливості

Автоматичний 3-х разовий повтор протягом 72 годин при невдалому списанні

Отримання токена карти клієнта у відповіді від LiqPay

Скасування підписки в будь-який момент

Зміна суми і картки для списання регулярних платежів

Як працює API підписка

Компанія формує запит на API підписки вказавши в параметрах дату першого регулярного списання з клієнта і періодичність списань.
Після успішного оформлення підписки - подальші регулярні списання з картки клієнта LiqPay проводить самостійно згідно з даними, переданими по API в запиті.
Регулярні списання проходять з картки клієнта, яка була вказана при оформленні підписки.
Компанія отримує статус платежів згідно API Callback.
При необхідності можна оновити суму, валюту, призначення підписки через API змінити підписку.
Скасувати підписку можна по API скасування підписки.

Підключення

Server-Server

З сертифікатом PCI DSS відповідного рівня

Згідно з правилами платіжних систем Mastercard і Visa наявність сертифіката є обов'язковим, так як взаємодія з LiqPay проходить по методу server-server, клієнт вводить реквізити карти на сайті компанії.

Для отримання доступу до API необхідно:

Мати сертифікат PCI DSS (Payment Card Industry Data Security Standard) відповідного рівня, в залежності від кількості операцій в рік
Подати заявку на підключення

Відправити запит

Client-Server

Без сертифіката PCI DSS

Інтеграція в рамках публічних API Checkout або Платіжний віджет використовуйте action subscribe - регулярний платіж.

Методи інтеграції

Самостійна інтеграція згідно з документацією

SDK мобільні бібліотеки:

SDK для мов програмування:

Є питання?

Звертайтесь до нашого технічного відділу на пошту:

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 символів

Більше параметрів в документації

Інструмент формування data і signature

Приклад створення 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-форму:

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="

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\" : \"subscribe\",
    \"version\" : 3,
    \"public_key\" : \"${PUBLIC_KEY}\", 
    \"phone\" : \"380950000001\",
    \"amount\" : 1,
    \"currency\" : \"USD\",
    \"description\" : \"description text\",
    \"order_id\" : \"order_id_1\",
    \"subscribe\" : \"1\",
    \"subscribe_date_start\" : \"2016-03-31 00:00:00\",
    \"subscribe_periodicity\" : \"month\",
    \"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'               => 'subscribe',
'version'              => '3',
'phone'                => '380950000001',
'amount'               => '1',
'currency'             => 'USD',
'description'          => 'description text',
'order_id'             => 'order_id_1',
'subscribe'            => '1',
'subscribe_date_start' => '2015-03-31 00:00:00',
'subscribe_periodicity'=> 'month',
'card'                 => '4731195301524634',
'card_exp_month'       => '03',
'card_exp_year'        => '22',
'card_cvv'             => '111'
));


HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "subscribe");
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("subscribe", "1"); 
params.put("subscribe_date_start", "2015-03-31 00:00:00");
params.put("subscribe_periodicity", "month");
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"));


from liqpay import LiqPay

liqpay = LiqPay(public_key, private_key)
res = liqpay.api("request", {
"action"                : "subscribe",
"version"               : "3",
"phone"                 : "380950000001",
"amount"                : "1",
"currency"              : "USD",
"description"           : "description text",
"order_id"              : "order_id_1",
"subscribe"             : "1",
"subscribe_date_start"  : "2015-03-31 00:00:00",
"subscribe_periodicity" : "month",
"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                => "subscribe",
:version               => "3",
:phone                 => "380950000001",
:amount                => "1",
:currency              => "USD",
:description           => "description text",
:order_id              => "order_id_1",
:subscribe             => "1",
:subscribe_date_start  => "2015-03-31 00:00:00",
:subscribe_periodicity => "month",
:card                  => "4731195301524634",
:card_exp_month        => "03",
:card_exp_year         => "22",
:card_cvv              => "111"
})


LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>, <<"subscribe">>},
{<<"version">>, <<"3">>}, 
{<<"phone">>, <<"380950000001">>}, 
{<<"amount">>, <<"1">>}, 
{<<"currency">>, <<"USD">>}, 
{<<"description">>, <<"description text">>}, 
{<<"order_id">>, <<"order_id_1">>}, 
{<<"subscribe">>, <<"1">>}, 
{<<"subscribe_date_start">>, <<"2015-03-31 00:00:00">>}, 
{<<"subscribe_periodicity">>, <<"month">>}, 
{<<"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"                : "subscribe",
"version"               : "3",
"phone"                 : "380950000001",
"amount"                : "1",
"currency"              : "USD",
"description"           : "description text",
"order_id"              : "order_id_1",
"subscribe"             : "1",
"subscribe_date_start"  : "2015-03-31 00:00:00",
"subscribe_periodicity" : "month",
"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'                => 'subscribe',
'version'               => '3',
'phone'                 => '380950000001',
'amount'                => '1',
'currency'              => 'USD',
'description'           => 'description text',
'order_id'              => 'order_id_1',
'subscribe'             => '1',
'subscribe_date_start'  => '2015-03-31 00:00:00',
'subscribe_periodicity' => 'month',
'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": "subscribe",
    "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",
    "subscribe": "1",
    "subscribe_date_start": "2016-03-31 00:00:00",
    "subscribe_periodicity": "month",
}

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	subscribe
amount	Required	Number	Сума платежу. Наприклад: 5, 7.34
card	Required	String	Номер картки платника
card_cvv	Required	String	CVV/CVV2
card_exp_month	Required	String	Місяць терміну дії картки платника. Наприклад: 08
card_exp_year	Required	String	Рік терміну дії картки платника. Наприклад: 19
currency	Required	String	Валюта платежу. Можливі значення: USD, EUR, UAH
description	Required	String	Призначення платежу
ip	Required	String	IP клієнта
order_id	Required	String	Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів
phone	Required	String	Телефон платника. На цей номер буде відправлений OTP пароль підтвердження платежу та підвязаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +)
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 символів. Детальніше

Параметри регулярного платежу:

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 - раз на рік

Параметри відправника:

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 символів

Параметри відповіді:

Parameter	Type	Description
acq_id	Number	ID еквайера
action	String	Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, paysplit - розщеплення платежу, subscribe - створення регулярного платежу, paydonate - пожертвування, auth - предавторизація картки, regular - регулярний платіж
agent_commission	Number	Комісія агента в валюті платежу
amount	Number	Сума платежу
authcode_debit	String	Код авторизації по транзакції debit
amount_bonus	Number	Бонус відправника у валюті платежу debit
amount_credit	Number	Сума транзакції credit в валюті currency_credit
amount_debit	Number	Сума транзакції debit у валюті currency_debit
card_token	String	Token картки відправника
commission_credit	Number	Комісія з одержувача у валюті currency_credit
commission_debit	Number	Комісія з відправника у валюті currency_debit
create_date	String	Дата створення платежу
currency	String	Валюта платежу
currency_credit	String	Валюта транзакції credit
currency_debit	String	Валюта транзакції debit
description	String	Коментар до платежу
end_date	String	Дата завершення/зміни платежу
is_3ds	Boolean	Можливі значення: true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки
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 - Платіж повернений subscribed - Підписка успішно оформлена success - Успішний платіж Статуси що потребують підтвердження платежу 3ds_verify - Потрібна 3DS верифікація. Для завершення платежу, потрібно виконати 3ds_verify cvv_verify - Потрібне введення CVV картки відправника. Для завершення платежу, потрібно виконати cvv_verify otp_verify - Потрібне OTP підтвердження клієнта. OTP пароль відправлений на номер телефону Клієнта. Для завершення платежу, потрібно виконати otp_verify Інші статуси платежу wait_accept - Кошти з клієнта списані, але магазин ще не пройшов перевірку. Якщо магазин не пройде активацію протягом 60 днів, платежі будуть автоматично скасовані wait_secure - Платіж на перевірці
transaction_id	Number	Id транзакції в системі LiqPay
type	String	Тип платежу
version	Number	Версія API. Поточне значення - 7

Приклад відповіді:


{
  "acq_id": 414963,
  "action": "subscribe",
  "agent_commission": 0.0,
  "amount_bonus": 0.0,
  "amount_credit": 0.1,
  "amount_debit": 0.1,
  "amount": 0.1,
  "authcode_debit": 944253,
  "card_token": "6E28D6039FD09FA3CE1DF27BCC2DE0E3254A3B27",
  "commission_credit": 0.0,
  "commission_debit": 0.0,
  "confirm_phone": "380912345678",
  "create_date": 1715266869912,
  "currency_credit": "UAH",
  "currency_debit": "UAH",
  "currency": "UAH",
  "description": "description text",
  "end_date": 1715266990142,
  "is_3ds": false,
  "liqpay_order_id": "1I9IGW951715266986946665",
  "mpi_eci": 7,
  "order_id": "order_id_263763yh737",
  "payment_id": 13291296,
  "paytype": "card",
  "public_key": "i16202663459",
  "receiver_commission": 0.0,
  "result": "ok",
  "rrn_debit": "000000454110",
  "sender_bonus": 0.0,
  "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": "subscribed",
  "transaction_id": 13291296,
  "type": "buy",
  "version": 7
}

Скасувати підписку

Необхідні URL для роботи в залежності від обраної моделі:

https://www.liqpay.ua/api/request — Server-Server;
https://www.liqpay.ua/api/3/checkout — Client-Server;

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 символів

Більше параметрів в документації

Інструмент формування data і signature

Приклад створення 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:

Після застосування функцій base64_encode( sha3-256( sign_string) ) отримуємо рядок:

signature = 0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s=

Приклад відправки запиту до LiqPay:

1.Для перенаправлення клієнта на сторінку оплати LiqPay (Client - Server) необхідно сформувати HTML-форму:

2.Для взаємодії (Server - Server) отримані data і signature необхідно відправити на url https://www.liqpay.ua/api/request:

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\" : \"unsubscribe\",
	\"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'        => 'unsubscribe',
'version'       => '3',
'order_id'      => 'order_id_1'
));


HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "unsubscribe");
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"        : "unsubscribe",
"version"       : "3",
"order_id"      : "order_id_1"
})


liqpay = Liqpay::Liqpay.new(
:public_key  => 'public_key',
:private_key => 'private_key'
)
res = liqpay.api("request", {
:action        => "unsubscribe",
:version       => "3",
:order_id      => "order_id_1"
})


LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>, <<"unsubscribe">>},
{<<"version">>, <<"3">>},
{<<"order_id">>, <<"order_id_1">>}
], LiqPay)


var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
liqpay.api("request", {
"action"   : "unsubscribe",
"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'        => 'unsubscribe',
'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": "unsubscribe",
    "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	unsubscribe
order_id	Required	String	Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів

Параметри відповіді:

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
card_token	String	Token картки відправника
commission_credit	Number	Комісія з одержувача у валюті currency_credit
commission_debit	Number	Комісія з відправника у валюті currency_debit
create_date	String	Дата створення платежу
currency	String	Валюта платежу
currency_credit	String	Валюта транзакції credit
currency_debit	String	Валюта транзакції debit
description	String	Коментар до платежу
end_date	String	Дата завершення/зміни платежу
is_3ds	Boolean	Можливі значення: true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки
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
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_phone	String	Телефон відправника
status	String	Статус платежу. Можливі значення: Кінцеві статуси платежу error - Неуспішний платіж. Некоректно заповнені дані failure - Неуспішний платіж success - Успішний платіж unsubscribed - Підписка успішно деактивована
transaction_id	Number	Id транзакції в системі LiqPay
type	String	Тип платежу
version	Number	Версія API. Поточне значення - 7

Приклад відповіді:


{
  "acq_id": "414963",
  "action": "subscribe",
  "agent_commission": "0.0",
  "amount_bonus": "0.0",
  "amount_credit": "38.31",
  "amount_debit": "38.31",
  "amount": "1.0",
  "commission_credit": "0.57",
  "commission_debit": "0.0",
  "create_date": "1705651874776",
  "currency_credit": "UAH",
  "currency_debit": "UAH",
  "currency": "USD",
  "description": "{{info.edittext_6686}}",
  "end_date": "1705651920384",
  "is_3ds": "false",
  "liqpay_order_id": "HGJI2AU61705651874774315",
  "mpi_eci": "7",
  "order_id": "order_id_76587576",
  "payment_id": "2416590001",
  "paytype": "card",
  "public_key": "sandbox_i63492854596",
  "receiver_commission": "0.02",
  "result": "ok",
  "sender_bonus": "0.0",
  "sender_card_bank": "Test",
  "sender_card_country": "804",
  "sender_card_mask2": "424242*42",
  "sender_card_type": "visa",
  "sender_commission": "0.0",
  "sender_phone": "380950000001",
  "status": "unsubscribed",
  "transaction_id": "2416590001",
  "type": "buy",
  "version": "7",
  "card_token": "6E28D6039FD09FA3CE1DF27BCC2DE0E3254A3B27"
}

Змінити підписку

Необхідні URL для роботи в залежності від обраної моделі:

https://www.liqpay.ua/api/request — Server-Server;
https://www.liqpay.ua/api/3/checkout — Client-Server;

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 символів

Більше параметрів в документації

Інструмент формування data і signature

Приклад створення 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:

Після застосування функцій base64_encode( sha3-256( sign_string) ) отримуємо рядок:

signature = 0adgJ8F2Ds5HCVkcz4AlmdLMRoIJf7IxsL3QmeFRz/s=

Приклад відправки запиту до LiqPay:

1.Для перенаправлення клієнта на сторінку оплати LiqPay (Client - Server) необхідно сформувати HTML-форму:

2.Для взаємодії (Server - Server) отримані data і signature необхідно відправити на url https://www.liqpay.ua/api/request:

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\" : \"subscribe_update\",
	\"version\" : 3,
	\"public_key\" : \"${PUBLIC_KEY}\", 
	\"order_id\" : \"order_id_1\",
	\"amount\" : 1,
	\"currency\" : \"USD\",
	\"description\" : \"description text\"
}"
# 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'        => 'subscribe_update',
'version'       => '3',
'order_id'      => 'order_id_1',
'amount'        => '1',
'currency'      => 'USD',
'description'   => 'description text'
));


HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "subscribe_update");
params.put("version", "3");
params.put("order_id", "order_id_1");
params.put("amount", "1");
params.put("currency", "USD");
params.put("description", "description text");

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"        : "subscribe_update",
"version"       : "3",
"order_id"      : "order_id_1",
"amount"        : "1",
"currency"      : "USD",
"description"   : "description text"
})


liqpay = Liqpay::Liqpay.new(
:public_key  => 'public_key',
:private_key => 'private_key'
)
res = liqpay.api("request", {
:action        => "subscribe_update",
:version       => "3",
:order_id      => "order_id_1",
:amount        => "1",
:currency      => "USD",
:description   => "description text"
})


LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>,      <<"subscribe_update">>},
{<<"version">>,     <<"3">>},
{<<"order_id">>,    <<"order_id_1">>},
{<<"amount">>,      <<"1">>},
{<<"currency">>,    <<"USD">>},
{<<"description">>, <<"description text">>}
], LiqPay)


var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
liqpay.api("request", {
"action"       : "subscribe_update",
"version"      : "3",
"order_id"     : "order_id_1",
"amount"       : "1",
"currency"     : "USD",
"description"  : "description text"
}, function( json ){
console.log( json.status );
});


my $liqpay = Liqpay->new($public_key,$private_key);
my $res = $liqpay->api("request",
{
'action'        => 'subscribe_update',
'version'       => '3',
'order_id'      => 'order_id_1',
'amount'        => '1',
'currency'      => 'USD',
'description'   => 'description text'
}
);


var c = liqpay.New("my_public_key", "my_private_key", nil)
// Creating the request map with all necessary parameters
request:=map[string]interface{}{
    "action": "subscribe_update",
    "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	subscribe_update
amount	Required	Number	Сума платежу. Наприклад: 5, 7.34
currency	Required	String	Валюта платежу. Можливі значення: USD, EUR, UAH
description	Required	String	Призначення платежу
order_id	Required	String	Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів

Параметри відповіді:

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
card_token	String	Token картки відправника
commission_credit	Number	Комісія з одержувача у валюті currency_credit
commission_debit	Number	Комісія з відправника у валюті currency_debit
create_date	String	Дата створення платежу
currency	String	Валюта платежу
currency_credit	String	Валюта транзакції credit
currency_debit	String	Валюта транзакції debit
description	String	Коментар до платежу
end_date	String	Дата завершення/зміни платежу
is_3ds	Boolean	Можливі значення: true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки
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	Комісія з одержувача у валюті платежу
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_phone	String	Телефон відправника
status	String	Статус платежу. Можливі значення: Кінцеві статуси платежу error - Неуспішний платіж. Некоректно заповнені дані failure - Неуспішний платіж reversed - Платіж повернений subscribed - Підписка успішно оформлена success - Успішний платіж
transaction_id	Number	Id транзакції в системі LiqPay
type	String	Тип платежу
version	Number	Версія API. Поточне значення - 7

Приклад відповіді:


{
  "acq_id": "414963",
  "action": "subscribe",
  "agent_commission": "0.0",
  "amount_bonus": "0.0",
  "amount_credit": "3.0",
  "amount_debit": "3.0",
  "amount": "3.0",
  "commission_credit": "0.57",
  "commission_debit": "0.0",
  "create_date": "1705655382848",
  "currency_credit": "UAH",
  "currency_debit": "UAH",
  "currency": "UAH",
  "description": "{{info.edittext_6686}}",
  "end_date": "1705655382943",
  "is_3ds": "false",
  "liqpay_order_id": "F9D77PKO1705655382844999",
  "mpi_eci": "7",
  "order_id": "order_id_263763737",
  "payment_id": "2416613735",
  "paytype": "card",
  "public_key": "sandbox_i63492854596",
  "receiver_commission": "0.02",
  "result": "ok",
  "sender_bonus": "0.0",
  "sender_card_bank": "Test",
  "sender_card_country": "804",
  "sender_card_mask2": "424242*42",
  "sender_card_type": "visa",
  "sender_commission": "0.0",
  "sender_phone": "380950000001",
  "status": "subscribed",
  "transaction_id": "2416613735",
  "type": "buy",
  "version": "7",
  "card_token": "6E28D6039FD09FA3CE1DF27BCC2DE0E3254A3B27"
}