API - billline.net

Реєстрація

Для початку роботи пройдіть реєстрацію https://billline.net/uk/connect-uk/#form-connect

Після реєстрації ви отримаєте доступ до особистого кабінету користувача.

Для створення мерчанта потрібно перейти на вкладку "Мерчанти" (на сайдбарі) і натиснути на "+" (рис. 1).

Рис. 1

Під час реєстрації нового мерчанта заповніть поля:

1. Найменування мерчанта

Вказати ім'я мерчанта

2. Посилання на ресурс

Потрібно ввести URL-адресу свого ресурсу

3. Секретний ключ мерчанта

Натисніть кнопку “Згенерувати”, щоб автоматично генерувати ключ.

Заповнення наступних полів пов'язане з прийманням платежів (Deposit)

4. Передача URL-адрес у формі

Обираючи «YES» — ви підтверджуєте згоду на передачу URL-адрес у форму оплати (куди буде перенаправлено покупця після проведення платежу – success_url після успішного прийняття платежу в обробку, fail_url – у випадку відмови проведення платежу).

Якщо залишити значення "NO" - адреса буде взята зі стандартних налаштувань мерчанта (process_url)

5. URL-адреса обробника платежів на стороні магазину (process_url)

Введіть URL-адресу обробника платежів на стороні магазину, а також вкажіть тип запиту, який потрібно надсилати на вказану адресу

6. URL-адреса перенаправлення у разі успішного проведення операції (success_url)

Введіть URL-адресу перенаправлення платника у разі успішного проведення операції, а також вкажіть тип запиту, який необхідно надсилати на вказану адресу

7. URL-адреса перенаправлення у разі помилки під час проведення операції (fail_url)

Введіть URL-адресу перенаправлення платника у разі помилки під час операції, а також вкажіть тип запиту, який необхідно надсилати на вказану адресу.

Заповнення наступних полів пов'язане із проведенням виплат (Withdrawal)

8. Отримання callback-відповіді з результатами проведення виплати коштів

Обираючи YES — ви підтверджуєте отримання callback-запитів з результатами проведення виплати коштів. В іншому випадку, результат необхідно отримувати самостійно (надсилання запиту статусу платежу).

9. URL-адреса обробника callback-відповідей (withdrawal_url)

У цьому полі потрібно задати URL, на який буде надсилатись відповідь з результатом проведення виплати та метод, яким будуть передаватися дані (GET або POST). Якщо ці дії не виконати, повідомлення про зміну статусу транзакції не буде надіслане.

10. Повернення маски картки одержувача в callback-відповіді

Обираючи "YES" - ви погоджуєтесь на отримання маски картки одержувача в callback (у форматі 123412ХХХХХХ4321). За умови, що callback-відповіді включені

11. Доступ до API методів Payout Send і Payout Status

У цьому налаштуванні можна обмежити IP-адреси, з яких буде дозволено приймати запит на здійснення виплат.

Ми рекомендуємо обмежити доступ – це додатково убезпечить сас.

Для активації мерчанта зверніться до служби підтримки support@billline.net

Також після активації мерчанта служба підтримки повідомить базову URL для запитів до API.

Цифровий підпис

Цифровий підпис в запитах

1. У кожному з методів API вказується, які поля використовуються для формування підпису, а також метод хешування (MD5 або SHA256).

2. Відібравши потрібні поля, потрібно їх відсортувати за алфавітом (за зростанням).

3. Наприкінці додається секретний ключ мерчанта.

4. Конкатенація всіх полів йде через символ «:» без їх назви

5. Отриманий рядок хешується (методом MD5 або SHA256) і його байтове подання кодується в Base64: sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'), true)) або sign = Base64(SHA256 (Implode(Sort(Params) + SecretKey, ':'), true))

Приклад підпису для запиту Payout Send:

Copy

Expand all

Collapse all

$data = [
"merchant" => "M1VJDHSI6DYXS",
"method" => 1,
"payout_id" => "000002",
"account" => "5300111122223333",
"amount" => 1.19,
"currency" => 'UAH'
];
$dataSet = $data;
ksort($dataSet, SORT_STRING);
array_push($dataSet, "SecRetKey0123");
$signString = implode(":", $dataSet);
$calc_sign = base64_encode(md5($signString, true));
$data["sign"] = $calc_sign;

Цифровий підпис у Callback

1. Усі поля форми з префіксом «co_» відсортовані за абеткою.

2. Наприкінці додано секретний ключ мерчанта.

3. Конкатенація всіх полів зроблена через символ «:» без їхньої назви.

4. Приклад рядка для підпису даних для запиту Payout Send: 16:UAH:2019-02-19 19:12:04:2019-02-19 19:12:11:success:1:M1VJDHSI6DYXS:20:34:15.76:SecretKey

5. Отриманий рядок хешується методом MD5 і його байтове уявлення кодується в Base64: co_sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'), true))

Приклад підпису даних у відповіді на запит Payout Send:

Copy

Expand all

Collapse all

$data = [
"co_inv_id" => "1111111",
"co_inv_crt" => "2021-02-16 19:12:04",
"co_inv_prc" => "2021-02-16 19:12:11",
"co_inv_st" => "Success",
"co_payout_id" => "000002",
"co_merchant_uuid" => "M1VJDHSI6DYXS"
];
$dataSet = $data;
ksort($dataSet, SORT_STRING);
array_push($dataSet, "SecRetKey0123");
$signString = implode(":", $dataSet);
$calc_sign = base64_encode(md5($signString, true));
$data["sign"] = $calc_sign;

Перевірка цифрового підпису

Перевірка цифрового підпису проводиться під час отримання запиту. Рекомендуємо реалізувати додаткову перевірку на стороні мерчанта.

Перевірка цифрового підпису

Copy

Expand all

Collapse all

$secret_key = 'SecretKey'; // секретний ключ мерчанта
$dataSet = json_decode($response, TRUE);
$sign = $dataSet["sign"];
unset($dataSet["sign"]);
ksort($dataSet, SORT_STRING);
array_push($dataSet, $secret_key);
$signString = implode(":", $dataSet);
$calc_sign = base64_encode(md5($signString, true));

if ($sign != $calc_sign) {
// Sign error
echo ("Sign error");
} else {
echo "Sign Ok";
}

Колбеки

Для сповіщення мерчанта про те, що транзакція набула фінального статусу (наприклад, із “Pending” на “Success”), використовується механізм колбеків.

Коллбек надсилається:

у випадку фіналізації транзакції поповнення (Deposit) на URL-адресу обробника платежів на стороні магазину (process_url)
при фіналізації транзакції виплати (Withdrawal) на URL-адресу обробника callback-відповідей (withdrawal_url)

У відповідь на отриманий пакет сервер магазину має відповісти двома англійськими літерами "OK".

У випадку, якщо не вдалося надіслати запит на callback_url, або була отримана відповідь не "OK", будуть здійснюватися повторні спроби доставки колбека, доки не буде отримано відповідь "OK".

Усього робиться 20 спроб доставки колбека. Інтервал між відправками колбека становить:

з 1 по 10 - 5 хв;
з 11 по 20 - 60 хв.

Колбек у випадку успішного платежу (iframe та host-2-host)

У випадку успішного проведення платежу на сервер магазину process_url передаються дані про платеж методом POST:

Колбек містить поля:

co_inv_id

унікальний номер транзакції;
co_inv_crt

дата і час створення транзакції;
co_inv_prc

дата та час проведення транзакції;
co_inv_st

статус успішного проведення ("Success");
co_order_no

номер транзакції в системі мерчанта (переданий мерчантом при проведенні платежу);
co_amount

сума транзакції у валюті, роздільник точка ".";
co_to_wlt

сума зарахування на рахунок мерчанта (за вирахуванням комісії);
co_cur

валюта транзакції;
co_merchant_id

унікальний номер мерчанта;
co_merchant_uuid

унікальний ідентифікатор мерчанта;
co_sign

цифровий підпис ключем мерчанта (докладніше розписано в розділі “Цифровий підпис у Callback”).
co_card_number

передача маски картки. Це поле стандантно відсутнє у відповіді. Щоб отримувати його у відповіді, необхідно в налаштуваннях мерчанта встановити значення “YES” у полі “Cardmask in callback”

У випадку, якщо виконується внутрішня конвертація, у колбеку можуть бути додаткові поля:

co_base_amount

базова сума, отримана в запиті;
co_base_currency

базова валюта, отримання в запиті платежу;
co_rate

курс конвертації;

При конвертації в поле co_cur буде валюта процесингу, а в полях co_amount та co_to_wlt будуть суми у валюті процесингу.

У відповідь на прийнятий пакет сервер мерчанта повинен відповісти двома англійськими літерами «OK».

Приклад:

Content type

application/json

Copy

Expand all

Collapse all

{
"co_inv_id" : "1111111",
"co_inv_crt" : "2019-02-19 19:12:04",
"co_inv_prc" : "2019-02-19 19:12:11",
"co_inv_st" : "success",
"co_order_no" : "0001",
"co_amount" : "16",
"co_to_wlt" : "15.95",
"co_cur" : "UAH",
"co_merchant_id" : "1",
"co_merchant_uuid" : "M1VJDHSI6DYXS",
"co_sign" : "pQQgUBfjz+XxRSpwo5srmw=="
}

Колбек при відмові у проведенні платежу (iframe та host-2-host)

У разі відмови у проведенні платежу на сервер магазину «process_url» передаються дані про помилковий платіж методом POST:

co_inv_id

унікальний номер транзакції;
co_inv_crt

дата і час створення транзакції;
co_inv_prc

дата та час проведення транзакції;
co_inv_st

статус проведення платежу ("Fail");
co_order_no

номер транзакції у системі мерчанта (переданий мерчантом при проведенні платежу);
co_merchant_id

унікальний номер мерчанта;
co_merchant_uuid

унікальний ідентифікатор мерчанта;
co_sign

цифровий підпис ключем мерчанта (докладніше розписано в розділі “Цифровий підпис у Callback”).

У відповідь на прийнятий пакет сервер мерчанта повинен відповісти двома англійськими літерами «OK».

Приклад:

Content type

application/json

Copy

Expand all

Collapse all

{
"co_inv_id" : "1111111",
"co_inv_crt" : "2019-02-19 19:12:04",
"co_inv_prc" : "2019-02-19 19:12:11",
"co_inv_st" : " fail",
"co_order_no" : "0001",
"co_merchant_id" : "1",
"co_merchant_uuid" : "M1VJDHSI6DYXS",
"co_sign" : "pQQgUBfjz+XxRSpwo5srmw=="
}

Колбек при виплаті

Повідомлення буде надіслано у разі зміни статусу транзакції (наприклад, з «Pending» на «Success»).

Дані надсилаються на URL-адресу обробника callback-відповідей (вказано в налаштуваннях мерчанта) методом GET або POST.

Колбек при виплаті містить поля:

co_inv_id

унікальний номер транзакції;
co_inv_crt

дата і час створення платежу;
co_inv_prc

дата та час проведення платежу;
co_inv_st

статус проведення ("Success" або "Fail");
co_payout_id

номер платежу в системі мерчанта (номер виплати);
co_merchant_uuid

унікальний ідентифікатор мерчанта;
co_sign

цифровий підпис ключем мерчанта (докладніше розписано у розділі “Цифровий підпис у Callback”)).

Приклад Callback при виплаті:

Copy

Expand all

Collapse all

Array
(
[co_inv_id] => 1111111
[co_inv_crt] => 2021-02-16 19:12:04
[co_inv_prc] => 2021-02-16 19:12:11
[co_inv_st] => Success
[co_payout_id] => 000002
[co_merchant_uuid] => M1VJDHSI6DYXS
[co_sign] => XXXXXXXXXXXXXXXXXX
)

Методи API

Список методів API:

/payment/form

запит на прийом платежу (iframe)
/api/host2host

запит на прийом платежу (host-2-host)
/payment/status

запит статусу платежу (прийом)
/merchant/api/payout_send

запит на виплату
/merchant/api/payout_status

запит статусу платежу (виплата)
/payment/balance

запит балансу
/api/payment-list

запит списку платежів

Прийом платежів (iframe)

Первинний запит

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
order

номер транзакції у системі мерчанта;
amount

сума транзакції у валюті, роздільник крапка".";
currency

валюта транзакції, може приймати значення UAH, USD, EUR, KZT, BRL та AZN;
item_name

назва товару;
first_name

ім'я клієнта. Максимальна довжина – 30 символів (Припустимі тільки латинські літери);
last_name

прізвище клієнта (Припустимі тільки латинські літери);
user_id

ідентифікатор кліента в системі мерчанта (поле не є обов'язковим до передачі) ;
payment_url

url адреса сайту на користь якого проходить платіж;
country

країна клієнта в ISO 3166-1 alpha-2 форматі;
ip

IP-адреса клієнта;
custom

для додаткової інформації про клієнта.
email

e-mail платника
phone

номер телефону платника
address

адреса проживання платника
city

місто проживання платника
post_code

почтовий код платника
region

регіон проживання платника
lang

мова (додано 26.07.2021.), якою буде відображатися платіжна форма:

en — англійська

ua — українська
cpf

CPF клієнта (Поле є опціональним для метода оплати PIX)

Поля "process_url", "success_url", "fail_url" (куди буде перенаправлено клієнта після проведення платежу) передавати не потрібно. Ці дані беруться автоматично з налаштувань мерчанта в особистому кабінеті.

У деяких випадках у запиті використовується поле "last_4", в якому передаються останні 4 цифри номера картки.

Важливо! Рядки запиту повинні містити виключно латинські літери та цифри.

GET

/payment/form

https://<наданий url>/payment/form

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"order" : "0001",
"amount" : "16",
"currency" : "UAH",
"item_name" : "Samsung TV",
"first_name" : "IVAN",
"last_name" : "IVANOV",
"user_id" : "492235",
"payment_url" : "http://test.com",
"country" : "UA",
"ip" : "212.10.20.75",
"custom" : "",
"email": "test@gmail.com",
"phone": "+35988222763",
"address": "Avenue Marius Renard 21",
"city": "Anderlecht",
"post_code": "1070",
"region": "stuttgart",
"lang" : "en"
}

Перенаправлення покупця після проведення платежу

Увага! Спрямування покупця на ”success_url” або «fail_url» є лише інформаційним і НЕ МОЖЕ підтверджувати успіх чи відмову у прийомі платежу!

Після платежу клієнт перенаправляється на “success_url” або “fail_url”

Відповідь містить поля:

order_no

номер транзакції у системі мерчанта (теж саме й у запиті «order»);
amount

сума транзакції у валюті, роздільник точка ".";
currency_code

валюта транзакції (у якій було виставлено рахунок);
item_name

назва товару (якщо передавалося);
co_inv_id

унікальний номер транзакції;
co_inv_st

статус транзакції в платіжній системі (Success або Canceled).

Приклад відповіді при успішному прийнятті платежу до обробки:

Content type

application/json

Copy

Expand all

Collapse all

{
"order_no" : "0001",
"amount" : "16",
"currency_code" : "UAH",
"item_name" : "Samsung TV",
"co_inv_id" : "1111111",
"co_inv_st" : "success"
}

Приклад відповіді у разі відхилення платежу:

Content type

application/json

Copy

Expand all

Collapse all

{
"order_no" : "0001",
"amount" : "16",
"currency_code" : "UAH",
"item_name" : "Samsung TV",
"co_inv_id" : "1111111",
"co_inv_st" : "canceled"
}

Фінальний статус (колбек)

Для повідомлення мерчанта про те, що транзакція набула фінального статусу (наприклад, із “Pending” на “Success”), використовується механізм колбеків.

Детально розписано у розділі "Колбеки".

Приймання платежів (host-2-host)

Згідно з правилами платіжних систем Mastercard та Visa наявність сертифіката PCI DSS (відповідного рівня) є обов'язковою, оскільки клієнт вводить реквізити картки на сайті мерчанта.

Первинний запит

Запит містить поля:

type

тип транзакції (payment);
merchant

унікальний ідентифікатор мерчанта;
order

номер транзакції у системі мерчанта;
amount

сума транзакції у валюті, роздільник крапка ".";
currency

валюта транзакції, може приймати значення UAH, USD, EUR, KZT, BRL та AZN;
card_num

номер картки;
card_exp_month

місяць закінчення терміну дії картки;
card_exp_year

рік закінчення терміну дії картки;
card_cvv

cvv картки;
process_url

URL для надсилання підсумкового статусу транзакції
item_name

назва товару (поле не обов'язкове);
first_name

ім'я власника картки (Припустимі тільки латинські літери);
last_name

прізвище власника картки (Припустимі тільки латинські літери);
user_id

ідентифікатор клієнта в системі мерчанта (поле не є обов'язковим до передачі);
payment_url

url адреса сайту на користь якого проходить платіж;
country

країна клієнта в ISO 3166-1 alpha-2 форматі;
email

e-mail платника
phone

номер телефону платника
address

адреса проживання платника
city

місто проживання платника
post_code

почтовий код платника
region

регіон проживання платника
sign

цифровий підпис ключем мерчанта. Використовуються поля "type", "merchant", "order", "amount", "currency", "card_num", "card_exp_month", "card_exp_year", "card_cvv". Хешується шляхом SHA256. (Детальніше розписано в розділі “Цифровий підпис у запитах”)
browser

масив, в якому передаються дані про браузер клієнта, а саме:

accept_header

color_depth

ip

language

screen_height

screen_width

time_different

window_width

window_height

Важливо! Рядки запиту повинні містити виключно латинські літери та цифри.

POST

/api/host2host

https://<наданий url>/api/host2host

Приклад запиту PHP:

Copy

Expand all

Collapse all

$url = "https://<наданий url>/api/host2host";
$merchant = "M1VJDHSI6DYXS";
$signature = "XXXXXXXXXXXXXXXXXX";
$order_id = "0001";
$data = [
"type" => "payment",
"merchant" => $merchant,
"order" => $order_id,
"amount" => "10.99",
"currency" => "UAH",
"card_num" => "5300111122223333",
"card_exp_month" => "01",
"card_exp_year" => "25",
"card_cvv" => "111",
"process_url" => "https://test.com/api/callback_url",
"item_name" => "Samsung TV",
"first_name" => "IVAN",
"last_name" => "IVANOV",
"user_id" => "492235",
"payment_url" => "http://test.com",
"country" => "UA",
"email": "test@gmail.com",
"phone": "+35988222763",
"address": "Avenue Marius Renard 21",
"city": "Anderlecht",
"post_code": "1070",
"region": "stuttgart",
"browser" => [
    "accept_header" => "...",
    "color_depth" => "...",
    "ip" => "...",
    "languager" => "...",
    "screen_height" => "...",
    "screen_width" => "...",
    "time_different" => "...",
    "user_agent" => "...",
    "java_enabled" => "...",
    "window_width" => "...",
    "window_height" => "..."
],
];
$dataSign = array_filter(
$data,
fn ($key) => in_array($key, [ 'type', 'merchant', 'order', 'amount', 'currency', 'card_num', 'card_exp_month', 'card_exp_year', 'card_cvv' ]),
ARRAY_FILTER_USE_KEY
);

/*
спрощений варіант:
$dataSign = [ $data['type'], $data['merchant'], $data['order'], $data['amount'], $data['currency'], $data['card_num'], $data['card_exp_month'], $data['card_exp_year'], $data['card_cvv'] ];
*/

ksort($dataSign, SORT_STRING);
array_push($dataSign, $signature);
$signString = implode(':', $dataSign);
$sign = base64_encode(hash('sha256', $signString, true));
$data['sign'] = $sign;
$request = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($request))
);
$result = curl_exec($ch);

У разі успішного приймання даних (для подальшого проведення платежу) відповідь містить поля:

status

статус транзакції (3ds);
merchant

унікальний ідентифікатор мерчанта;
order

номер транзакції у системі мерчанта (той самий, що й у запиті);
uuid

унікальний ідентифікатор транзакції, використовуйте його для пошуку та за потреби зв'язатися з техпідтримкою;
co_inv_id

унікальний номер транзакції;
d3_acs_url

посилання на сторінку 3DS, куди необхідно перенаправити клієнта;
d3_pareq

дані для пересилання;
d3_md

дані для пересилання.

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

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "3ds",
"merchant": "M1VJDHSI6DYXS",
"order": "0001",
"uuid": "ABC123abc123",
"co_inv_id": 1111111,
"d3_acs_url": "https://3ds.bank.ua",
"d3_pareq": "eJxVUt...tuwjAM/RX==",
"d3_md": "1:809b...82316eb"
}

У разі відхилення платежу відповідь містить поля:

status

статус транзакції (error);
code

код помилки;
description

опис помилки.

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

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "error",
"code": "10",
"description": "The order is already in the system. Request a status."
}

Перенаправлення покупця на форму 3DS

За позитивної відповіді мерчанту необхідно переадресувати клієнта на форму 3DS. Для цього використовуйте параметри відповіді при первинному запиті

Copy

Expand all

Collapse all

<form name="MPIform" action="{{ d3_acs_url }}" method="POST" target="_blank">
<input type="text" name="PaReq" value="{{ d3_pareq }}" />
<input type="text" name="MD" value="{{ d3_md }}" />
<input type="text" name="TermUrl" value="{{ URL }}" />
<button type="submit">Send</button>
</form>

Підсумковий запит

*Зверніть увагу! Не плутайте d3_pares та d3_pareq:

d3_pareq ви отримуєте у відповідь при первинному запиті та пересилаєте у форму 3DS;
d3_pares ви отримуєте від форми 3DS і пересилаєте у підсумковому запиті.

Запит містить поля:

type

тип (3ds);
merchant

унікальний ідентифікатор мерчанта;
uuid

унікальний ідентифікатор транзакції (параметр, який отримуєте у відповіді при первинному запиті);
order

номер транзакції у системі мерчанта (так само як і у первинному запиті);
d3_pares

отримуєте у відповіді від форми 3DS;
d3_md

дані для пересилання (отримуєте відповіді при первинному запиті);
sign

цифровий підпис ключем мерчанта. Використовуються поля "type", "merchant", "order", "uuid", "d3_md". Хешується шляхом SHA256. (Детально розписано у розділі “Цифровий підпис у запитах”).

POST

/api/host2host

https://<наданий url>/api/host2host

Приклад:

Copy

Expand all

Collapse all

$data = [
"type" => "3ds",
"merchant" => $merchant ,
"uuid" => "BILLLINE ID",
"order" => "Ваш ID який Ви вказували раніше",
"d3_pares" => $d3_pares,
"d3_md" => $d3_md,
];
$dataSign = array_filter(
$data,
fn ($key) => in_array($key, [ "type", "merchant", "order", "uuid", "d3_md" ]),
ARRAY_FILTER_USE_KEY
);

/*
спрощений варіант:
$dataSign = [ $data["type"], $data["merchant"], $data["order"], $data[" uuid "], $data["d3_md"] ];
*/

$dataSign = [ $data["type"], $data["merchant"], $data["order"], $data[" uuid "], $data["d3_md"] ];
ksort($dataSign, SORT_STRING);
array_push($dataSign, $signature);
$signString = implode(":", $dataSign);
$sign = base64_encode(hash("sha256", $signString, true));
$data["sign"] = $sign;
$request = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Content-Length:" . strlen($request))
);
$result = curl_exec($ch);

У разі успішної обробки запиту відповідь містить поля:

status

статус платежу (success);
merchant

унікальний ідентифікатор мерчанта;
uuid

унікальний ідентифікатор транзакції, використовуйте його для пошуку та за потреби зв'язатися з техпідтримкою;
order

номер транзакції у системі мерчанта (теж саме що й у запиті);

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

Content type

application/json

Copy

Expand all

Collapse all

{
"type" : "3ds",
"merchant" : "M1VJDHSI6DYXS",
"uuid" : "ABC123abc123",
"order" : "0001",
"d3_pares" : "eJzVmNmS...ovrSsTczhh==",
"d3_md" : "1:809b...82316eb",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

У разі помилки платежу відповідь містить поля:

status

статус транзакції (error);
code

код помилки;
description

опис помилки.

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

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "error",
"code": "2",
"description": "Incorrect request details"
}

Фінальний статус (колбек)

Для cповіщення мерчанта про те, що транзакція набула фінального статусу (наприклад, із “Pending” на “Success”), використовується механізм коллбеків.

Детально розписано у розділі “Коллбеки”:

Приймання платежів PIX (host-2-host)

Первинний запит

Запит містить поля:

type

тип транзакції (PIX);
merchant

унікальний ідентифікатор мерчанта;
order

номер транзакції у системі мерчанта;
amount

сума транзакції у валюті, роздільник крапка ".";
currency

валюта транзакції, може приймати значення BRL;
item_name

назва товару;
country

країна клієнта в ISO 3166-1 alpha-2 форматі;
custom

для додаткової інформації про кліента;
ip

IP-адреса клієнта;
sign

цифровий підпис ключем мерчанта. Використовуються поля "type", "merchant", "order", "amount", "currency". Хешується шляхом SHA256. (Детальніше розписано в розділі “Цифровий підпис у запитах”)

POST

/api/h2hpix

https://<наданий url>/api/h2hpix

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
    "type": "pix",
    "merchant": "M1VJDHSI6DYXS",
    "order": "125327341124",
    "amount": "123.45",
    "currency": "BRL",
    "item_name": "test",
    "country": "BR",
    "custom": "test",
    "ip": "127.0.0.1",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

У разі успішного приймання даних (для подальшого проведення платежу) відповідь містить поля:

status

статус транзакції (pending);
merchant

унікальний ідентифікатор мерчанта;
order

номер транзакції у системі мерчанта (той самий, що й у запиті);
uuid

унікальний ідентифікатор транзакції, використовуйте його для пошуку та за потреби зв'язатися з техпідтримкою;
co_inv_id

унікальний номер транзакції;
qr_code

строка в якій вказана адреса оплати PIX;
img

текстове відображення QR-коду, закодоване base64;

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

Content type

application/json

Copy

Expand all

Collapse all

{
    "status": "pending",
    "merchant": "QZLF99CVT3WMF",
    "order": "125327341124",
    "uuid": "P1FMNCQDPGI0O",
    "co_inv_id": 15356471,
    "qr_code": "0002012682...A0D28263049620",
    "img": "iVBORw0KGg...UVORK5CYII="
}

У разі помилки платежу відповідь містить поля:

status

статус транзакції (error);
code

код помилки;
description

опис помилки;

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

Content type

application/json

Copy

Expand all

Collapse all

{
    "status": "error",
    "code": "10",
    "description": "The order is already in the system. Request a status."
}

Запит статусу платежу (прийом)

Метод передачі даних может бути POST або GET.

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
order

номер транзакції у системі мерчанта;
co_inv_id

унікальний номер транзакції (номер передається після обробки платежу на Process URL мерчанта);
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant", "order", "co_inv_id". Хешується шляхом MD5. (Детально розписано у розділі “Цифровий підпис у запитах”).

GET

/payment/status

https://<наданий url>/payment/status

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"order" : "0001",
"co_inv_id" : "1111111",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

У відповідь на запит повертаються дані у форматі JSON:

status

статус транзакції:

Success – платіж проведено успішно (статус фінальний)

Pending – платіж новий або знаходиться в черзі на обробку

Fail – платіж відхилений (статус фінальний)

Refund – за платежем було здійснено повернення (статус фінальний)

Error – помилка прийнятих даних (підпис у відповіді порожній «sign» = «»)
order

номер транзакції у системі мерчанта;
description

опис статусу;
card_number

маска картки (у форматі NNNNNN******NNNN, де N – цифра);
sign

цифровий підпис ключем мерчанта.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "success",
"order" : "0001",
"description" : "Merchant payment success",
"card_number" : "530011******3333",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "Error",
"order" : "0001",
"description" : "Merchant payment not found",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Виплати на картку

Для коректного налаштування проведення виплат зайдіть до “Особистого кабінету” – “Редагування мерчанта”.

Детальний опис цих налаштувань міститься в розділі “Реєстрація” (пункти 8-11)

Запит на виплату

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
method

метод виплати, ціле число:

1 - Visa/Mastercard UAH

8 - Mastercard USD - для цього методу необхідно передавати обов'язкові поля: "exp_date": "mm/yy", "full_name": "CARD HOLDER"

9 - Mastercard EUR

11 - Visa/Mastercard AZN

12 - Visa/Mastercard KZT

16 - Visa/Mastercard UAH (Інший канал)

17 - Visa/Mastercard AZN - для цього методу необхідно передавати обов'язкове поле: "exp_date": "mm/yy"

22 - Visa EUR (Інший канал) - для цього методу необхідно передавати обов'язкове поле: "full_name": "CARD HOLDER"

23 - MasterCard EUR (Інший канал) - для цього методу необхідно передавати обов'язкове поле: "full_name": "CARD HOLDER"

24 - Mobile KZT - для цього методу потрібно передавати поле: "account":"номер телефону без знаку +"
payout_id

номер вихідного платежу в системі мерчанта;
account

номер платіжної картки (Visa або Mastercard);
amount

сума транзакції у валюті, роздільник точка ".";
currency

валюта транзакції, має відповідати полю «method»:

«UAH» для методу 1

«USD» для методу 8

«EUR» для методу 9

«AZN» для методу 11

«KZT» для методу 12

«UAH» для методу 16 (Інший канал)

«AZN» для методу 17

«EUR» для методу 22 (Інший канал)

«EUR» для методу 23 (Інший канал)

«KZT» для методу 24 (Мобільна комерція)
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant", "method", "payout_id", "account", "amount", "currency". Хешується шляхом MD5. (Детально розписано у розділі “Цифровий підпис у запитах”).

POST

/merchant/api/payout_send

https://<наданий url>/merchant/api/payout_send

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"method" : 1,
"payout_id" : "000002",
"account" : "5300111122223333",
"amount" : "102.81",
"currency" : "UAH",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Відповідь містить поля:

status

статус транзакції:

Success – платіж проведено успішно (статус фінальний)

Pending – платіж новий або знаходиться у черзі на обробку. Статус Pending вимагає додаткового запиту (докладно розписано у розділі “Запит статусу платежу”).

Blocked – платіж відхилено (статус фінальний)

Error – помилка прийнятих даних. Відповідь містить підпис порожнім ключем (статус не фінальний і є підставою для з'ясування причин виникнення даного статусу)
code

код статусу транзакції;
payout_id

номер вихідного платежу у системі мерчанта;
description

опис статусу;
sign

цифровий підпис ключем мерчанта.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "Success",
"code" : "0",
"payout_id" : 000002,
"description" : "Payment successful. Status final",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Pending:

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Pending",
"code": "40",
"payout_id": 000002,
"description": "Payment in order",
"sign": "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Error",
"code": "99",
"payout_id": "",
"description": "Sign error",
"sign": "XXXXXXXXXXXXXXXXXX"
}

Фінальний статус (колбек)

Детально розписано у розділі "Коллбеки"

Запит виплати на банківські рахунки (SEPA)

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
method

метод виплати, ціле число:

15 — Payout Iban EUR;
payout_id

номер вихідного платежу у системі мерчанта;
account

номер банківського рахунку;
full_name

ім'я, прізвище клієнта. Максимальна довжина – 30 символів;
amount

сума транзакції у валюті, роздільник точка ".";
currency

валюта транзакції "EUR":
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant", "method", "payout_id", "account", "amount", "currency". Хешується шляхом MD5. (Детально розписано у розділі “Цифровий підпис у запитах”).

POST

/merchant/api/payout_send

https://<наданий url>/merchant/api/payout_send

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
 "merchant" : "M1VJDHSI6DYXS",
 "method" : 15,
 "payout_id" : "000002",
 "account" : "iban adress",
 "full_name" : IVANOV IVAN
 "amount" : "102.81",
 "currency" : "EUR",
 "sign" : "XXXXXXXXXXXXXXXXXX"
}

Відповідь містить поля:

status

статус транзакції:

Success – платіж проведено успішно (статус фінальний)

Pending – платіж новий або знаходиться у черзі на обробку. Статус Pending вимагає додаткового запиту (докладно розписано у розділі “Запит статусу платежу”).

Blocked – платіж відхилений (статус фінальний)

Error – помилка прийнятих даних. Відповідь містить підпис порожнім ключем (статус не фінальний і є підставою для з'ясування причин виникнення даного статусу)
code

код статусу транзакції;
payout_id

номер вихідного платежу у системі мерчанта;
description

опис статусу;
sign

цифровий підпис ключем мерчанта.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
 "status" : "Success",
 "code" : "0",
 "payout_id" : 000002,
 "description" : "Payment successful. Status final",
 "sign" : "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Pending:

Content type

application/json

Copy

Expand all

Collapse all

{
 "status": "Pending",
 "code": "40",
 "payout_id": 000002,
 "description": "Payment in order",
 "sign": "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
 "status": "Error",
 "code": "99",
 "payout_id": "",
 "description": "Sign error",
 "sign": "XXXXXXXXXXXXXXXXXX"
}

Фінальний статус (колбек)

Детально розписано у розділі "Колбеки"

Запит виплати на банківські рахунки (PIX)

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
method

метод виплати, ціле число:

21 — Payout PIX BRL;
payout_id

номер вихідного платежу у системі мерчанта;
account

ідентифікаційний номер платника податків;
pix_key

ключ PIX користувача;
amount

сума транзакції у валюті, роздільник точка ".";
currency

валюта транзакції "BRL":
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant", "method", "payout_id", "account", "amount", "currency". Хешується шляхом MD5. (Детально розписано у розділі “Цифровий підпис у запитах”).

POST

/merchant/api/payout_send

https://<наданий url>/merchant/api/payout_send

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"method" : 21,
"payout_id" : "000002",
"account" : "1111111122222",
"pix_key" : "test@test.com",
"amount" : "102.81",
"currency" : "BRL",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Відповідь містить поля:

status

статус транзакції:

Success – платіж проведено успішно (статус фінальний)

Pending – платіж новий або знаходиться у черзі на обробку. Статус Pending вимагає додаткового запиту (докладно розписано у розділі “Запит статусу платежу”).

Blocked – платіж відхилений (статус фінальний)

Error – помилка прийнятих даних. Відповідь містить підпис порожнім ключем (статус не фінальний і є підставою для з'ясування причин виникнення даного статусу)
code

код статусу транзакції;
payout_id

номер вихідного платежу у системі мерчанта;
description

опис статусу;
sign

цифровий підпис ключем мерчанта.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "Success",
"code" : "0",
"payout_id" : 000002,
"description" : "Payment successful. Status final",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Pending:

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Pending",
"code": "40",
"payout_id": 000002,
"description": "Payment in order",
"sign": "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
 "status": "Error",
 "code": "99",
 "payout_id": "",
 "description": "Sign error",
 "sign": "XXXXXXXXXXXXXXXXXX"
}

Фінальний статус (колбек)

Детально розписано у розділі "Колбеки"

Запит статусу платежу (виплата)

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
payout_id

номер вихідного платежу у системі мерчанта;
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant" та "payout_id". Хешується шляхом MD5. (Детально розписано у розділі “Цифровий підпис у запитах”).

POST

/merchant/api/payout_status

https://<наданий url>/merchant/api/payout_status

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"payout_id" : "000002",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

У відповідь на запит повертаються дані у форматі JSON:

status

статус транзакції:

Success – платіж проведено успішно (статус фінальний)

Pending – платіж новий або знаходиться в черзі на обробку

Blocked – платіж відхилений (статус фінальний)

Error – помилка прийнятих даних (підпис у відповіді порожній «sign» = «»)
payout_id

номер вихідного платежу у системі мерчанта;
code

код статусу платежу;
description

опис статусу;
sign

цифровий підпис ключем мерчанта.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "Success",
"payout_id" : 000002,
"code" : "0",
"description" : "Payment successful. Status final",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "Error",
"code" : "8",
"payout_id" : "",
"description" : "Transaction not found",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Blocked:

Content type

application/json

Copy

Expand all

Collapse all

{
"status" : "Blocked",
"payout_id" : 000002,
"code" : "80",
"description" : "Payment error. Status final",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Запит балансу

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
currency

запитувана валюта (UAH, USD, EUR, KZT, BRL або AZN);
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant", "currency". Хешується методом MD5 (детально розписано у розділі "Цифровий підпис у запитах")

POST

/payment/balance

https://<наданий url>/payment/balance

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"currency" : "UAH",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Відповідь містить поля:

status

статус запиту:

Success – запит успішний

Error – помилка прийнятих даних (якщо мерчанта не знайдено, підпис у відповіді не передається)
currency

запитувана валюта (UAH, USD, EUR, KZT, BRL або AZN);
balance

доступна сума у валюті з двома знаками після коми, роздільник крапка (наприклад - 212.07);
description

опис ("Wallet balance");
sign

цифровий підпис ключем мерчанта.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Success",
"currency": "UAH",
"balance": 212.07,
"description": "Wallet balance",
"sign": "XXXXXXXXXXXXXXXXXX"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Error",
"merchant": "M1VJDHSI6DYXS",
"description": "Merchant not found or not Approved"
}

Запит списку платежів

Методом передачі даних може бути POST або GET.

Запити списку платежів обробляються не більше одного хвилину.

Максимальна кількість транзакцій відповідає 10 000.

Запит містить поля:

merchant

унікальний ідентифікатор мерчанта;
currency

валюта, що запитується (UAH, USD, EUR, KZT, BRL або AZN);
order

номер транзакції у системі мерчанта, з якої починається вибірка у заданому періоді (якщо передається 0, то повертаються всі транзакції);
start_date

дата та час початку періоду у форматі YYYY-MM-DD HH:ii:ss;
finish_date

дата та час закінчення періоду у форматі YYYY-MM-DD HH:ii:ss;
status

статус платежів, які будуть обрані (all, success, pending, blocked, refund);
type

тип транзакції (withdrawal або deposit);
sign

цифровий підпис ключем мерчанта. Використовуються поля "merchant", "currency", "order", "start_date", "finish_date", "status", "type". Хешується методом MD5 (детально розписано розділ “Цифровий підпис у запитах”).

GET

/api/payment-list

https://<наданий url>/api/payment-list

Приклад запиту:

Content type

application/json

Copy

Expand all

Collapse all

{
"merchant" : "M1VJDHSI6DYXS",
"currency" : "UAH",
"order" : "0",
"start_date" : "2021-02-09 00:00:00",
"finish_date" : "2021-02-11 16:59:59",
"status" : "all",
"type" : "deposit",
"sign" : "XXXXXXXXXXXXXXXXXX"
}

Відповідь містить поля:

id

унікальний номер транзакції;
uid

унікальний ідентифікатор транзакції (той самий, що і "uuid");
order_id

номер транзакції у системі мерчанта;
subtotal

сума, зарахована:

при «Deposit» – на баланс мерчанту

при «Withdrawal» – на картку
fee_percentage

утримана комісія (якщо тип комісії відсоток):

при «Deposit» віднімається з «total»

при «Withdrawal» нараховується на «subtotal»
fee_fixed

утримана комісія (якщо тип комісії фіксований):

при «Deposit» віднімається з «total»

при «Withdrawal» нараховується на «subtotal»
total

загальна сума транзакції:

при «Deposit» – сума поповнення без стягнення комісії

при «Withdrawal» – сума виплати з нарахованою комісією
type

тип транзакції (withdrawal або deposit);
status

статус транзакції (Success, Pending, Blocked, Refund);
created_at

дата та час створення транзакції;
updated_ad

дата та час проведення транзакції.

Приклад відповіді – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

{
"id" : 11114,
"uid" : "ABA4OD7X73L4Q",
"order_id" : "0083",
"subtotal" : 0.9,
"fee_percentage" : 0,
"fee_fixed" : 0.1,
"total" : 1,
"currency" : "UAH",
"type" : "Deposit",
"status" : "Success",
"created_at" : "2021-02-10 09:34:57",
"updated_ad" : "2021-02-10 09:37:40"
}

Приклад відповіді – статус Blocked:

Content type

application/json

Copy

Expand all

Collapse all

{
"id" : 11115,
"uid" : "XTJTEZXMJAUMT",
"order_id" : "0084",
"subtotal" : 0.9,
"fee_percentage" : 0,
"fee_fixed" : 0.1,
"total" : 1,
"currency" : "UAH",
"type" : "Deposit",
"status" : "Blocked",
"created_at" : "2021-02-10 10:22:32",
"updated_ad" : "2021-02-10 10:24:17"
}

Приклад відповіді – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Error",
"description": "Please send one request per minute"
}

Запит курсів валют

Метод передачі може бути POST або GET

Поля для запиту

merchant

ідентифікатор мерчанта
currency_from

базова валюта

GET

/api/rates

https://<наданий url>/api/rates

Content type

application/json

Copy

Expand all

Collapse all

{
"status":"success",
"description":"Опис відповіді",
"rates": {
      "CURR1":VAL1,
      "CURR2":VAL2,
…}
}

Приклад:

Content type

application/json

Copy

Expand all

Collapse all

{
"status":"success",
"description":"Rates from UAH",
"rates":{
      "USD":0.0247,
      "EUR":0.0228
}
}

або у випадку помилки

Content type

application/json

Copy

Expand all

Collapse all

{
"status" => "Error",
"description" => "Опис помилки"
}

Запит на обмін валют

Поля для проведення рекурентного платежу

merchant

ідентифікатор мерчанта
order

номер платежу у системі мерчанта
amount

сума обміну
currency_from

валюта обміну
currency_to

валюта результату
currency sign

підпис запиту з використанням методу шифрування sha256

POST

/api/exchange

https://<наданий url>/api/exchange

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "success",
"description": "Currency exchange success",
"transInfo":{
    "order":"order",
    "uuid":"uuid",
    "amount": amount,
    "fee":0,
    "currency_from":"currency_from",
    "converted_amount": converted_amount,
    "currency_to":"currency_to",
    "rate":rate
}
}

або у випадку помилки

Content type

application/json

Copy

Expand all

Collapse all

{
"status": "Error",
"description" => "Опис помилки"
}

Коди статусу

Код статусу	Статус	Фінальний	Опис
0	Success	Так	Виплата успішна
2	Error	Ні	Помилка вхідних даних
3	Error	Ні	Платіжний метод заблоковано
4	Error	Ні	Марчанта заблоковано
5	Error	Ні	Помилка валюти виплати
6	Error	Ні	Рахунок мерчанта заблоковано
7	Error	Ні	Сума перевищує баланс
8	Error	Ні	ID транзакції не знайдено (Зверніться до технічної підтримки для уточнення деталей)
10	Error	Ні	Повторний запит виплати, потрібен запит на статус транзакції
40	Pending	Ні	Транзакція в обробці
80	Blocked	Так	Відмовлено у виплаті
99	Error	Ні	Помилка підпису у запиті
100	Error	Ні	Помилка не документована