Приватний
Двостадійна оплата
Блокування коштів на картці клієнта для подальшого списання

Блокування

Схема роботи API двостадійної оплати
LiqPay UA_Two_step

Необхідні 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\" : \"hold\",
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\", 
\"phone\" : \"380950000001\", 
\"amount\" : \"1\", 
\"currency\" : \"USD\", 
\"description\" : \"description text\", 
\"order_id\" : \"order_id_1\", 
\"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}"
Параметри для формування data:
Основні
ParameterRequiredTypeDescription
versionRequiredNumberВерсія API. Поточне значення - 3
public_keyRequiredStringПублічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину
actionRequiredStringhold
amountRequiredNumberСума платежу. Наприклад: 5, 7.34
apay_token
Optional
StringJSON рядок з параметра token (отриманий від Apple), закодована функцією base64. Параметр не обов'язковий, якщо передається параметр card або gpay_token
card
Optional
StringНомер картки клієнта або незашифрований токен Apple, Google, міжнародних платіжних систем (MasterCard, Visa). Параметр не обов'язковий, якщо передається параметр gpay_token or apay_token
card_cvv
Optional
StringCVV/CVV2. Параметр обов’язковий, якщо передається номер картки
card_exp_month
Optional
StringМісяць терміну дії картки платника. Параметр обов'язковий, якщо передається номер картки або незашифрований токен. Наприклад: 08
card_exp_year
Optional
StringРік терміну дії картки платника. Параметр обов'язковий, якщо передається номер картки або незашифрований токен. Наприклад: 19
currencyRequiredStringВалюта платежу. Можливі значення: USD, EUR, UAH
descriptionRequiredStringПризначення платежу
gpay_token
Optional
StringJSON рядок з параметра token (отриманий від Google), закодована функцією base64. Параметр не обов'язковий, якщо передається параметр card або apay_token
ipRequiredStringIP клієнта
order_idRequiredStringУнікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів
phoneRequiredStringТелефон платника. На цей номер буде відправлений OTP пароль підтвердження платежу та підвязаний кабінет платника LiqPay. Телефон вказується в міжнародному форматі (Україна +380). Наприклад: +380950000001 (з +) або 380950000001 (без +)
paytype
Optional
StringТип оплати. Можливі значення: apay - оплата за допомогою зашифрованого токена Apple, gpay - оплата за допомогою зашифрованого токена Google, apay_tavv - оплата за допомогою незашифрованого токена Apple, gpay_tavv - оплата за допомогою незашифрованого токена Google, tavv - оплата за допомогою незашифрованого токена міжнародних платіжних систем (MasterCard, Visa). Параметр обов'язковий для оплат за допомогою зашифрованих і незашифрованих токенів
tid
Optional
StringІдентифікатор попередньої транзакції. Для рекурентних платежів за токенами міжнародної платіжної системи Visa
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
recurring
Optional
BooleanОзнака рекурентної оплати за токеном. Використовується для оплат за токеном міжнародних платіжних систем (MasterCard, Visa). Можливі значення true - операція виконується без участі клієнта, false - операція виконується клієнтом
server_url
Optional
StringURL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше
tavvRequiredStringРеференс токена, отриманого при декриптуванні даних пристрою Apple
Параметри відправника:
ParameterRequiredTypeDescription
sender_first_name
Optional
StringІм'я відправника
sender_last_name
Optional
StringПрізвище відправника
phoneRequiredStringТелефон платника
sender_email
Optional
StringЕлектронна адреса
sender_country_codeRequiredStringКод країни відправника. Цифровий ISO 3166-1 код
sender_cityRequiredStringМісто відправника
sender_addressRequiredStringАдреса відправника
sender_state
Optional
StringПлатіжна адреса. Код регіону відправника. Цифровий ISO 3166-2 код.
Для України ISO 3166-2:UA
sender_shipping_state
Optional
StringАдреса доставки. Код регіону відправника. Цифровий ISO 3166-2 код.
Для України ISO 3166-2:UA
sender_postal_codeRequiredStringПоштовий індекс відправника
Параметри розщеплення платежу:
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»
Параметри відповіді:
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
authcode_debitStringКод авторизації по транзакції debit
card_tokenStringToken картки відправника
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Коментар до платежу
ipStringIP адреса відправника
end_dateStringДата завершення/зміни платежу
is_3dsBooleanМожливі значення:
true - транзакція пройшла з 3DS перевіркою, false - транзакція пройшла без 3DS перевірки
languageStringМова клієнта uk, en
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
rrn_debitStringУнікальний номер транзакції в системі авторизації і розрахунків обслуговуючого банку Retrieval Reference number
sender_bonusNumberБонус відправника у валюті платежу
sender_card_bankStringБанк відправника
sender_card_countryStringКраїна картки відправника. Цифровий ISO 3166-1 код
sender_card_mask2StringКарта відправника
sender_card_typeStringТип картки відправника MC/Visa
sender_commissionNumberКомісія з відправника у валюті платежу
sender_first_nameStringІм'я відправника
sender_last_nameStringПрізвище відправника
sender_phoneStringТелефон відправника
statusStringСтатус платежу.
Можливі значення:
Кінцеві статуси платежу
error - Неуспішний платіж. Некоректно заповнені дані
failure - Неуспішний платіж
reversed - Платіж повернений
success - Успішний платіж
Статуси що потребують підтвердження платежу
3ds_verify - Потрібна 3DS верифікація.
Для завершення платежу, потрібно виконати 3ds_verify
cvv_verify - Потрібне введення CVV картки відправника. Для завершення платежу, потрібно виконати cvv_verify
otp_verify - Потрібне OTP підтвердження клієнта. OTP пароль відправлений на номер телефону Клієнта.
Для завершення платежу, потрібно виконати otp_verify
receiver_verify - Потрібне введення даних одержувача. Для завершення платежу, потрібно виконати receiver_verify
sender_verify - Потрібне введення даних відправника.
Для завершення платежу, потрібно виконати sender_verify
Інші статуси платежу
hold_wait - Сума успішно заблокована на рахунку відправника
wait_accept - Кошти з клієнта списані, але магазин ще не пройшов перевірку. Якщо магазин не пройде активацію протягом 60 днів, платежі будуть автоматично скасовані
wait_secure - Платіж на перевірці
transaction_idNumberId транзакції в системі LiqPay
typeStringТип платежу
versionNumberВерсія API. Поточне значення - 3
Приклад відповіді:
{
  "acq_id": "414963",
  "action": "hold",
  "agent_commission": "0.0",
  "amount_bonus": "0.02",
  "amount_credit": "0.1",
  "amount_debit": "0.1",
  "amount": "0.1",
  "authcode_debit": "805256",
  "card_token": "27AA8744A98339BB9E85D50AEB718A93B470395C",
  "commission_credit": "0.0",
  "commission_debit": "0.0",
  "confirm_phone": "380933454182",
  "create_date": "1715323287407",
  "currency_credit": "UAH",
  "currency_debit": "UAH",
  "currency": "UAH",
  "description": "testing pay by card",
  "ip": "8.8.0.0",
  "is_3ds": "false",
  "language": "uk",
  "liqpay_order_id": "YHVDEMXJ1715323369444359",
  "mpi_eci": "7",
  "order_id": "idByCard345D308",
  "payment_id": "13291299",
  "paytype": "card",
  "public_key": "i16202663459",
  "receiver_commission": "0.0",
  "result": "ok",
  "rrn_debit": "000000454153",
  "sender_bonus": "0.02",
  "sender_card_bank": "pb",
  "sender_card_country": "804",
  "sender_card_mask2": "545708*24",
  "sender_card_type": "mc",
  "sender_commission": "0.0",
  "sender_first_name": "Тетяна",
  "sender_last_name": "Станько",
  "sender_phone": "380933454182",
  "status": "hold_wait",
  "transaction_id": "13291299",
  "type": "hold",
  "version": "3"
}