Публічний
Оплата готівкою
Відкладена оплата готівкою в терміналах самообслуговування ПриватБанку
Схема роботи API оплата готівкою
LiqPay UA_Cash_payment

Необхідні 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 рядок з параметрами виклику апі, де:
ParameterRequiredTypeDescription
versionRequiredNumberВерсія API. Наприклад: 3
public_keyRequiredStringПублічний ключ - ідентифікатор створеної компанії. Наприклад: i00000000
private_keyRequiredStringПриватний ключ створеної компанії (не надається нікому крім Вашого розробника). Наприклад: a4825234f4bae72a0be04eafe9e8e2bada209255
actionRequiredStringТип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, subscribe - регулярний платіж, paydonate - пожертва, auth - предавторізація картки
amountRequiredNumberСума платежу. Наприклад: 5, 7.34
currencyRequiredStringВалюта платежу. Можливі значення:USD, EUR, UAH. Додаткові валюти можуть бути встановлені за запитом компанії
descriptionRequiredStringПризначення платежу
order_idRequiredStringУнікальний 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>
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="
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\" : \"paycash\",
    \"version\" : 3,
    \"public_key\" : \"${PUBLIC_KEY}\", 
    \"phone\" : \"380950000001\",
    \"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)
# REQ is json response from liqpay
REQ=$(curl --silent -XPOST ${API_URL} --data-urlencode data="${DATA}" --data-urlencode signature="${SIGNATURE}")
echo "Result: ${REQ}"
Параметри для формування data:
Основні
ParameterRequiredTypeDescription
versionRequiredNumberВерсія API. Поточне значення - 3
public_keyRequiredStringПублічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину
actionRequiredStringpaycash
amountRequiredNumberСума платежу. Наприклад: 5, 7.34
currencyRequiredStringВалюта платежу. Можливі значення: USD, EUR, UAH
descriptionRequiredStringПризначення платежу
ipRequiredStringIP клієнта
order_idRequiredStringУнікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів
phoneRequiredStringТелефон платника. На цей номер буде відправлений OTP пароль підтвердження платежу та підвязаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +)
expired_date
Optional
StringЧас до якого клієнт може оплатити рахунок за UTC. Передається в форматі 2016-04-24 00:00:00
language
Optional
StringМова клієнта uk, en
prepare
Optional
StringПопередня підготовка платежу. Цей режим дозволяє визначити чи заповнені всі дані , чи потрібна 3DS перевірка картки, чи не перевищено ліміт. Гроші з картки платника не списуються. Для включення режиму необхідно передати значення 1
server_url
Optional
StringURL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше
Параметри розщеплення платежу:
ParameterRequiredTypeDescription
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"
  }
]
Інші параметри:
ParameterRequiredTypeDescription
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", // номер рейсу, 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 символів
Параметри відповіді:
ParameterTypeDescription
acq_idNumberID еквайера
actionStringТип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, paysplit - розщеплення платежу, subscribe - створення регулярного платежу, paydonate - пожертвування, auth - предавторизація картки, regular - регулярний платіж
agent_commissionNumberКомісія агента в валюті платежу
amountNumberСума платежу
amount_bonusNumberБонус відправника у валюті платежу debit
amount_creditNumberСума транзакції credit в валюті currency_credit
amount_debitNumberСума транзакції debit у валюті currency_debit
commission_creditNumberКомісія з одержувача у валюті currency_credit
commission_debitNumberКомісія з відправника у валюті currency_debit
confirm_phoneStringТелефон платника. На цей номер було відправлено OTP пароль підтвердження платежу та підв‘язаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +)
create_dateStringДата створення платежу
currencyStringВалюта платежу
currency_creditStringВалюта транзакції credit
currency_debitStringВалюта транзакції debit
descriptionStringКоментар до платежу
end_dateStringДата завершення/зміни платежу
ipStringIP адреса відправника
is_3dsBooleanМожливі значення:
true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки
liqpay_order_idStringOrder_id платежу в системі LiqPay
mpi_eciNumberМожливі значення: 5 - транзакція пройшла з 3DS (емітент і еквайєр підтримують технологію 3D-Secure), 6 - емітент картки платника не підтримує технологію 3D-Secure, 7 - операція пройшла без 3D-Secure
order_idStringOrder_id платежу
payment_idNumberId платежу в системі LiqPay
paytypeStringСпосіб оплати. Можливі значення card - оплата картою, privat24 - через кабінет Приват24, moment_part - розстрочка, invoice - рахунок на e-mail, qr - сканування qr-коду
public_keyStringПублічний ключ магазину
receiver_commissionNumberКомісія з одержувача у валюті платежу
resultStringРезультат виконання запиту ok, error
sender_bonusNumberБонус відправника у валюті платежу
sender_commissionNumberКомісія з відправника у валюті платежу
sender_first_nameStringІм'я відправника
sender_last_nameStringПрізвище відправника
sender_phoneStringТелефон відправника
statusStringСтатус платежу.
Можливі значення:
Кінцеві статуси платежу
error - Неуспішний платіж. Некоректно заповнені дані
failure - Неуспішний платіж
success - Успішний платіж
Статуси що потребують підтвердження платежу
cash_wait - Очікується оплата готівкою в ТСО
transaction_idNumberId транзакції в системі LiqPay
typeStringТип платежу
versionNumberВерсія API. Поточне значення - 3
Приклад відповіді:
{
  "acq_id": "414963",
  "action": "paycash",
  "agent_commission": "0.0",
  "amount_bonus": "0.35",
  "amount_credit": "1.0",
  "amount_debit": "1.0",
  "amount": "1.0",
  "commission_credit": "0.0",
  "commission_debit": "0.0",
  "confirm_phone": "380933454182",
  "create_date": "1715335274831",
  "currency_credit": "UAH",
  "currency_debit": "UAH",
  "currency": "UAH",
  "description": "description text",
  "end_date": "1501684842777",   "is_3ds": "false",
  "liqpay_order_id": "YP0L4E5S1715335274827674",
  "mpi_eci": "7",
  "order_id": "order_id_45_pay_by_cash1",
  "payment_id": "13291496",
  "paytype": "cash",
  "public_key": "i16202663459",
  "receiver_commission": "0.0",
  "result": "ok",
  "sender_bonus": "0.35",
  "sender_commission": "0.0",
  "sender_first_name": "Tetiana",
  "sender_last_name": "Stanko",
  "sender_phone": "380933454182",
  "status": "cash_wait",
  "transaction_id": "13291496",
  "type": "cash",
  "version": "3"
}