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

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

Подробно расписано в разделе "Коллбеки":

Прием платежей (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"
}

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

Подробно расписано в разделе “Коллбеки”:

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

Метод передачи данных может быть 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	Нет	Ошибка не документирована