Публічний
Checkout
Персоналізована платіжна сторінка - 10 методів оплати
Схема роботи checkout
LiqPay 712_UA_checkout
Підключення
  1. Створіть компанію в LiqPay за посиланням:
    Після реєстрації для Вашої компанії автоматично будуть створені унікальні ключі доступу до API:
    public_key - унікальний ідентифікатор Вашої компанії в системі LiqPay
    private_key - секретний ключ доступу до API
  2. Відповідно до технічної документації сформуйте запит на 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 рядок з параметрами виклику апі, де:
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'
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:
Основні
ParameterRequiredTypeDescription
versionRequiredNumberВерсія API. Поточне значення - 3
public_keyRequiredStringПублічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину
actionRequiredStringТип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, subscribe - регулярний платіж, paydonate - пожертва
amountRequiredNumberСума платежу. Наприклад: 5, 7.34
currencyRequiredStringВалюта платежу. Можливі значення: USD, EUR, UAH
descriptionRequiredStringПризначення платежу
order_idRequiredStringУнікальний 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
StringURL у Вашому магазині на який покупця буде переадресовано після завершення покупки. Максимальна довжина 510 символів
server_url
Optional
StringURL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше
verifycode
Optional
StringМожливе значення Y. Динамічний код верифікації, генерується і повертається в Callback. Так само згенерований код буде переданий в транзакції верифікації для відображення у виписці по картці клієнта. Працює для action = auth
Дані для фіскалізації (об'єкт rro_info):
ParameterRequiredTypeDescription
items
Optional
ArrayДані про товари, за які здійснюється оплата
delivery_emails
Optional
ArrayПерелік e-mail, на які треба відправити квитанції після фіскалізації
Дані про товари, за які здійснюється оплата (масив items):
ParameterRequiredTypeDescription
amountRequiredNumberКількість/обʼєм
costRequiredNumberВартість всіх одиниць вказанного товару в чеку (кількість * вартість одиниці)
idRequiredNumberІдентифікатор товару. Отримати можна в кабінеті Liqpay - РРО - Каса - Товари
priceRequiredNumberВартість одиниці товару
Приклад даних про товари:
rro_info: {
  "items": [
     {
       "amount": 2,
       "price": 202,
       "cost": 404,
       "id": 123456
     }
  ],
  "delivery_emails": ["email1@email.com", "email2@email.com"]
}
Параметри розщеплення платежу:
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
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Поштовий індекс відправника
Параметри регулярного платежу:
ParameterRequiredTypeDescription
subscribe
Optional
StringРегулярний платіж. Можливі значення: 1
subscribe_date_startRequiredStringДата першого платежу. Час необхідно вказувати в такому форматі 2015-03-31 00:00:00 по UTC. Якщо вказана минула дата, то підписка буде активована з поточної дати отримання запиту
subscribe_periodicity
Optional
StringПеріодичність списання коштів. Можливі значення: day - щодня, week - щотижня, month - раз на місяць, year - раз на рік
Параметри для оплати в 1 клік:
ParameterRequiredTypeDescription
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 клік)
Інші параметри:
ParameterRequiredTypeDescription
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 символів
Буде корисно
Отримання статусу та інформації про платіж
Відомості та помилки, які повертаються у відповіді системою LiqPay