API - billline.net
API Документація доступна на екранах з роздільною здатністю вище 1024 px по ширині

На Головну сторінку

Реєстрація

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

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

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

Реєстрація - billline.net

Рис. 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

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

  • payment_url

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

  • 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

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

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",
"payment_url" : "http://test.com",
"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, BRL та AZN;

  • card_num

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

  • card_exp_month

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

  • card_exp_year

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

  • card_cvv

    cvv картки;

  • process_url

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

  • item_name

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

  • first_name

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

  • last_name

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

  • payment_url

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

  • 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

Приклад запиту 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",
"payment_url" => "http://test.com",
"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

Приклад:

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

/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

    9 - Mastercard EUR

    11 - Visa/Mastercard AZN

    12 - Visa/Mastercard KZT

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

  • payout_id

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

  • account

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

  • amount

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

  • currency

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

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

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

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

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

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

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

  • sign

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

POST

/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"
}

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

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

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

Запит виплати на банківські рахунки (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

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

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"
}

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

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

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

Запит виплати на банківські рахунки (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

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

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"
}

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

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

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

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

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

  • merchant

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

  • payout_id

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

  • sign

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

POST

/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

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

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

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

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

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

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