bill_line

Реєстрація

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

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

Для створення мерчанта потрібно перейти на вкладку "Мерчанти" (на сайдбарі) і натиснути на "+" (рис. 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 та AZN;
item_name

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

ім'я клієнта. Максимальна довжина – 30 символів;
last_name

прізвище клієнта;
country

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

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

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

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

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

ru — російська

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

Якщо не передавати поле «lang» – стандартно відобразиться форма оплати російською мовою.

Поля "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",
    "country" : "UA",
    "ip" : "212.10.20.75",
    "custom" : "",
    "lang" : "en"
}

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

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

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

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

order_no

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

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

валюта транзакції (у якій було виставлено рахунок);
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 та AZN;
card_num

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

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

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

cvv картки;
process_url

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

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

ім'я власника картки;
last_name

прізвище власника картки;
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",
    "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”), використовується механізм коллбеків.

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

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

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

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

merchant

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

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

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

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

GET

/api/host2host

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

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

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

9 - Mastercard EUR

11 - Visa/Mastercard AZN

12 - Visa/Mastercard KZT
payout_id

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

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

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

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

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

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

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

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

«KZT» для методу 12
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"
 }

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

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

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

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

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 або 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 або 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, RUB, USD або EUR);
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 RUB",
    "rates":{
          "USD":0.0127,
          "UAH":0.3476,
          "EUR":0.0112
    }
}

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

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	Ні	Помилка не документована