Публічний

Інвойс

Виставлення рахунку на e-mail клієнта в режимі server-server

Що таке інвойс?

Відправлення рахунку на e-mail клієнта. Ви встановлюєте дату, до якої клієнт зможе оплатити рахунок. Після закінчення терміну рахунок автоматично стає недоступним для оплати.

Можливості

Встановити термін дії - дата, до якої клієнту необхідно сплатити рахунок

Вказати по API список товарів або послуг

Скасування інвойсу по API в будь-який момент, після чого клієнт не зможе оплатити

Вибрати тип платежу при оплаті рахунку клієнтом:

pay - проста оплата карткою

hold - блокування коштів на картці до 30 днів

subscribe - підписка

paydonate - пожертвування, платіж з вільною сумою

Як працює API інвойс

Клієнт оформив замовлення на Вашому сайті, але не сплатив його.
Ви відправляєте по API рахунок на e-mail клієнта з переліком товарів або послуг, які клієнт вказав у замовленні.
Клієнт отримує на e-mail рахунок з переліком товарів або послуг і кнопкою «Оплатити».
Для оплати LiqPay перенаправляє клієнта з e-mail на платіжну сторінку LiqPay, де клієнт може оплатити рахунок будь-яким зручним способом.

Підключення

Server-Server

Для даного API сертифікат PCI DSS не потрібен. Інтеграція в рамках API інвойс

Client-Server

При оплаті через API Checkout або Платіжний віджет клієнт може самостійно виставити рахунок на свій email.

Також компанія можете виставити рахунок на e-mail клієнта в Бізнес кабінеті LiqPay

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

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

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\" : \"invoice_send\",
    \"version\" : 3,
    \"public_key\" : \"${PUBLIC_KEY}\", 
    \"email\" : \"client-email@gmail.com\", 
    \"amount\" : 200,
    \"currency\" : \"USD\",
    \"order_id\" : \"order_id_1\",
    \"goods\" : \"[{
        \\"amount\\" : 100,
        \\"count\\" : 2,
        \\"unit\\" : \\"шт.\\",
        \\"name\\" : \\"USB\\"
    }]\",
}"
# 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'    => 'invoice_send',
'version'   => '3',
'email'     => 'client-email@gmail.com',
'amount'    => '200',
'currency'  => 'USD',
'order_id'  => 'order_id_1',
'goods'     => array(array(
'amount' => 100,
'count'  => 2,
'unit'   => 'шт.',
'name'   => 'телефон'
))
));


HashMap<String, String> params = new HashMap<String, String>();
params.put("action", "invoice_send");
params.put("version", "3");
params.put("email", "client-email@gmail.com");
params.put("amount", "200");
params.put("currency", "USD");
params.put("order_id", "order_id_1");
params.put("goods", "[{"
+ "\"amount\":100,"
+ "\"count\":2,"
+ "\"unit\":\"шт.\","
+ "\"name\":\"телефон\""
+ "}]");

LiqPay liqpay = new LiqPay(PUBLIC_KEY, PRIVATE_KEY);
HashMap<String, Object> res = liqpay.api("request", params);		
System.out.println(res.get("result"));


liqpay = LiqPay(public_key, private_key)
res = liqpay.api("request", {
"action"    : "invoice_send",
"version"   : "3",
"email"     : "client-email@gmail.com",
"amount"    : "1",
"currency"  : "USD",
"order_id"  : "order_id_1",
"goods"     : [{
"amount" : 100,
"count"  : 2,
"unit"   : "шт.",
"name"   : "телефон"
}]
})


liqpay = Liqpay::Liqpay.new(
:public_key  => 'public_key',
:private_key => 'private_key'
)
res = liqpay.api("request", {
:action   => "invoice_send",
:version  => "3",
:email    => "client-email@gmail.com",
:amount   => "1",
:currency => "USD",
:order_id => "order_id_1",
:goods    => [{
:amount => 100,
:count  => 2,
:unit   => "шт.",
:name   => "телефон"
}]
})


LiqPay = liqpay:init(PublicKey, PrivateKey),
Res = liqpay:api("request", [
{<<"action">>, <<"invoice_send">>},
{<<"version">>, <<"3">>}, 
{<<"email">>, <<"client-email@gmail.com">>}, 
{<<"amount">>, <<"1">>}, 
{<<"currency">>, <<"USD">>}, 
{<<"order_id">>, <<"order_id_1">>}, 
{<<"goods">>, [[
{<<"amount">>, 100},
{<<"count">>, 2},
{<<"unit">>, <<"шт.">>},
{<<"name">>, <<"телефон">>},
]]}
], LiqPay)


var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
liqpay.api("request", {
"action"   : "invoice_send",
"version"  : "3",
"email"    : "client-email@gmail.com",
"amount"   : "1",
"currency" : "USD",
"order_id" : "order_id_1",
"goods"    : [{
"amount" : 100,
"count"  : 2,
"unit"   : "шт.",
"name"   : "телефон"
}]
}, function( json ){
console.log( json.result );
});


my $liqpay = Liqpay->new($public_key,$private_key);
my $res = $liqpay->api("request",
{
'action'   => 'invoice_send',
'version'  => '3',
'email'    => 'client-email@gmail.com',
'amount'   => '1',
'currency' => 'USD',
'order_id' => 'order_id_1',
'goods'    => [{
'amount' => 100,
'count'  => 2,
'unit'   => 'шт.',
'name'   => 'телефон'
}]
}
);


var c = liqpay.New("my_public_key", "my_private_key", nil)
// Creating the request map with all necessary parameters
request:=map[string]interface{}{
    "action": "invoice_send",
    "version": 3,
    "public_key": "my_public_key",
    "order_id": "order_id_1",
    "email": "client-email@gmail.com", 
    "amount": 200,
    "currency": "USD",
    // goods if needed
    "goods": []interface{}{
        map[string]interface{}{
            "count":  2,
            "amount": 1,
            "unit":   "шт.",
            "name":   "USB",
        }
    },
}

resp, err:=c.Send("request", request)
    if err != nil {
        fmt.Printf("error %v\n", err.Error())
        return
    }
 
fmt.Printf("response: %#v\n", resp)

Параметри для формування data:

Основні

Parameter	Required	Type	Description
version	Required	Number	Версія API. Поточне значення - 7
public_key	Required	String	Публічний ключ - ідентифікатор магазину. Отримати ключ можна в налаштуваннях магазину
action	Required	String	invoice_send
amount	Required	Number	Сума платежу. Наприклад: 5, 7.34
currency	Required	String	Валюта платежу. Можливі значення: USD, EUR, UAH
description	Required	String	Призначення платежу
email	Required	String	E-mail клієнта для відправки інвойсу (phone або email обов'язкові параметри для передачі). Для імейлу заборонені домени підсанкційних країн: by, .ir, .iq, .cu, .ni, .sy, .mm, .kr, .ru, .ve, .af, .cd, .so, .ss, .sd, .ye, .zw, .ly
order_id	Required	String	Унікальний ID покупки у Вашому магазині. Максимальна довжина 255 символів
phone	Required	String	Телефон, на який буде відправлено інвойс як push-повідомлення в мобільний додаток Приват24 (phone або email обов'язкові параметри для передачі)
rro_info	Optional	Object	Дані для фіскалізації
action_payment	Optional	String	Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, subscribe - регулярний платіж, paydonate - пожертва
expired_date	Optional	String	Час до якого клієнт може оплатити рахунок за UTC. Передається в форматі 2016-04-24 00:00:00
goods	Optional	String	Одиниці виміру можно передати двума способами: самостійно через параметр unit, або за допомогою довідника API invoice_units	[ { "amount": 1, "count": 2, "unit": "шт.", "name": "USB" }, { "amount": 10, "count": 1, "unit": "шт.", "name": "Телефон" } ]
language	Optional	String	Мова клієнта uk, en
result_url	Optional	String	URL у Вашому магазині на який покупця буде переадресовано після завершення покупки. Максимальна довжина 510 символів
server_url	Optional	String	URL API в Вашому магазині для повідомлень про зміну статусу платежу (сервер -> сервер). Максимальна довжина 510 символів. Детальніше

Дані для фіскалізації (об'єкт rro_info):

Parameter	Required	Type	Description
items	Optional	Array	Дані про товари, за які здійснюється оплата
delivery_emails	Optional	Array	Перелік e-mail, на які треба відправити квитанції після фіскалізації

Дані про товари, за які здійснюється оплата (масив items):

Parameter	Required	Type	Description
amount	Required	Number	Кількість/обʼєм
cost	Required	Number	Вартість всіх одиниць вказанного товару в чеку (кількість * вартість одиниці)
id	Required	Number	Ідентифікатор товару. Отримати можна в кабінеті Liqpay - РРО - Каса - Товари
price	Required	Number	Вартість одиниці товару

Приклад даних про товари:


rro_info: {
  "items": [
     {
       "amount": 2,
       "price": 202,
       "cost": 404,
       "id": 123456
     }
  ],
  "delivery_emails": ["email1@email.com", "email2@email.com"]
}

API invoice_units

Parameter	Required	Type	Description
version	Required	Number	Версія API. Поточне значення - 7
action	Required	String	invoice_units_get_list якщо language НЕ вказано повертаємо список в вигляді — id, full_name_en, short_name_en, full_name_uk, short_name_uk якщо language вказано то повертаємо тільки по вказаній мові якщо language вказано і додатково вказано hide_name_lang = true то повертаємо в вигляді — id, full_name, short_name
action	Required	String	invoice_units_get_list_by_lang повертаємо список units в вигляді (id, full_name, short_name)
hide_name_lang	Optional	Boolean	true, false -тільки якщо передано language
language	Optional	String	Мова клієнта uk, en

Довідник одиниць виміру можете переглянути тут, він містить такі значення:

id - унікальний номер

full_name_uk - повне найменування українською

full_name_en - повне найменування англійською

short_name_uk - коротка назва українською

short_name_en - коротка назва англійською

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

Parameter	Type	Description
action	String	Тип операції. Можливі значення: pay - платіж, hold - блокування коштів на рахунку відправника, paysplit - розщеплення платежу, subscribe - створення регулярного платежу, paydonate - пожертвування, auth - предавторизація картки, regular - регулярний платіж
result	String	Результат виконання запиту ok, error
amount	Number	Сума платежу
currency	String	Валюта платежу
description	String	Коментар до платежу
href	String	Посилання на інвойс
id	Number	Id платежу в системі LiqPay
order_id	String	Order_id платежу
receiver_type	String	Вид каналу отримання
receiver_value	String	Значення отримане в параметрі receiver_type
status	String	Статус платежу. Можливі значення: Кінцеві статуси платежу error - Неуспішний платіж. Некоректно заповнені дані failure - Неуспішний платіж success - Успішний платіж Інші статуси платежу invoice_wait - Інвойс створений успішно, очікується оплата
token	String	Token платежу

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


{
  "id": 6173,
  "status": "invoice_wait",
  "amount": 0.03,
  "currency": "UAH",
  "description": "Invoice",
  "order_id": "98R1U1OV1485849059893399",
  "token": "150112455893001_6480_GBe3Mxwnq2O7G0MLX4gkQLtZf2",
  "href": "https://liqpay.ua/apipay/invoice/150112455893001_6480_GBe3Mxwnq2O7G0MLX4gkQLtZf2",
  "receiver_type": "email",
  "receiver_value": "test@gmail.com",
  "action": "pay",
  "result":"ok"
}

Скасування