API - billline.net

Регистрация

Для начала работы пройдите регистрацию https://billline.net/ru/connect-ru/#form-connect

После регистрации вы получите доступ к личному кабинету пользователя.

Для создания мерчанта нужно перейти на вкладку “Мерчанты” (на сайдбаре), и нажать на “ + ” (рис. 1).

рис. 1

При регистрации нового мерчанта заполните поля:

1. Наименование мерчанта

Указать имя мерчанта

2. Ссылка на ресурс

Нужно ввести URL своего ресурса

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

Нажмите кнопку “Сгенерировать” для автоматической генерации ключа.

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

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

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

Если оставить значение «NO» — адрес будет взят из настроек мерчанта по умолчанию (process_url)

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

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

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

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

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

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

Заполнение следующих полей связано с проведением выплат (Withdrawal)

8. Получение callback-ответа с результатами проведения выплаты средств

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

9. URL-адрес обработчика callback-ответов (withdrawal_url)

В этом поле нужно задать URL, на который будет отправляться ответ с результатом проведения выплаты и метод, которым будут передаваться данные (GET или POST). Если эти действия не выполнить, то уведомление об изменении статуса транзакции отправлено не будет.

10. Возврат маски карты получателя в callback-ответе

Выбирая «YES» — вы соглашаетесь на получение маски карты получателя в callback (в формате 123412ХХХХХХ4321). При условии, что callback-ответы включены

11. Доступ к API методам Payout Send и Payout Status

В этой настройке можно ограничить IP-адреса, с которых будет разрешено принимать запрос на проведение выплат.

Мы рекомендуем ограничить доступ — это дополнительно обезопасит сас.

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

Также, после активации мерчанта, служба поддержки сообщит базовый URL для запросов к API.

Цифровая подпись

Цифровая подпись в запросах

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

2. Отобрав нужные поля нужно их отсортировать по алфавиту (по возрастанию).

3. В конец добавляется секретный ключ мерчанта.

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

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

Пример подписи для запроса Payout Send:

Copy

Expand all

Collapse all

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

Цифровая подпись в Callback

1. Все поля формы с префиксом «co_» отсортированы по алфавиту.

2. В конец добавлен секретный ключ мерчанта.

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

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

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

Пример подписи данных в ответе для запроса Payout Send:

Copy

Expand all

Collapse all

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

Проверка цифровой подписи

Проверка цифровой подписи проводится при получении запроса. Также, настоятельно рекомендуем, реализовать проверку на стороне мерчанта.

Проверка цифровой подписи

Copy

Expand all

Collapse all

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

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

Коллбеки

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

Коллбек отправляется:

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

В ответ на принятый пакет сервер магазина должен ответить двумя английскими буквами «OK».

В случае, если не удалось отправить запрос на callback_url, или был получен ответ не «OK», будут осуществляться повторные попытки доставки коллбека, пока не будет получен ответ «OK».

Всего производится 20 попыток доставки коллбека. Интервал между отправками коллбека составляет:

с 1 по 10 — 5 мин;
с 11 по 20 — 60 мин.

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

При успешном проведении платежа на сервер магазина «process_url» передаются данные о платеже методом POST:

Коллбек содержит поля:

co_inv_id

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

дата и время создания транзакции;
co_inv_prc

дата и время проведения транзакции;
co_inv_st

статус проведения платежа (“Success”);
co_order_no

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

сумма транзакции в валюте, разделитель точка “.”;
co_to_wlt

сумма зачисления на счет мерчанта (за вычетом комиссии);
co_cur

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

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

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

цифровая подпись ключом мерчанта (более детально расписано в разделе “Цифровая подпись в Callback”).
co_card_number

передача маски карты. Это поле по умолчанию отсутствует в ответе. Чтобы получать его в ответе, необходимо в настройках мерчанта установить значение “YES” в поле “Cardmask in callback”

В случае, если выполняется внутренняя конвертация, в коллбеке могут присутствовать дополнительные поля:

co_base_amount

базовая сумма, полученная в запросе;
co_base_currency

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

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

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

В ответ на принятый пакет сервер мерчанта должен ответить двумя английскими буквами «OK».

Пример:

Content type

application/json

Copy

Expand all

Collapse all

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

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

При отказе в проведении платежа на сервер магазина «process_url» передаются данные об ошибочном платеже методом POST:

co_inv_id

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

дата и время создания транзакции;
co_inv_prc

дата и время проведения транзакции;
co_inv_st

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

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

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

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

цифровая подпись ключом мерчанта (более детально расписано в разделе “Цифровая подпись в Callback”).

В ответ на принятый пакет сервер мерчанта должен ответить двумя английскими буквами «OK».

Пример:

Content type

application/json

Copy

Expand all

Collapse all

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

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

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

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

Колбек при выплате содержит поля:

co_inv_id

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

дата и время создания платежа;
co_inv_prc

дата и время проведения платежа;
co_inv_st

статус проведения («Success» или «Fail»);
co_payout_id

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

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

цифровая подпись ключом мерчанта (более детально расписано в разделе “Цифровая подпись в Callback”).

Пример Callback при выплате:

Copy

Expand all

Collapse all

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

Методы API

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

/payment/form

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

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

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

запрос на выплату
/merchant/api/payout_status

запрос статуса платежа (выплата)
/payment/balance

запрос баланса
/api/payment-list

запрос списка платежей

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

Первичный запрос

Запрос содержит поля:

merchant

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

номер транзакции в системе мерчанта;
amount

сумма транзакции в валюте, разделитель точка “.”;
currency

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

название товара;
first_name

имя клиента. Максимальная длина 30 символов (Допустимы только латинские буквы);
user_id

идентификатор клиента в системе мерчанта (поле не необязательно к передаче);
last_name

фамилия клиента (Допустимы только латинские буквы);
payment_url

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

страна клиента в ISO 3166-1 alpha-2 формате;
ip

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

для дополнительной информации о клиенте.
email

e-mail плательщика
phone

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

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

город проживания плательщика
post_code

почтовый код плательщика
region

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

язык (добавлено 26.07.2021), на котором будет отображаться платежная форма:

en — английский

ua — украинский
cpf

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

Поля «process_url», «success_url», «fail_url» (куда будет перенаправлен клиент после проведения платежа) передавать не нужно. Эти данные берутся автоматически с настроек мерчанта в личном кабинете.

В некоторых случаях в запросе используется поле “last_4” в котором передаются последние 4 цифры номера карты.

Важно! Строки запроса должны содержать исключительно латинские буквы и цифры.

GET

/payment/form

https://<предоставленный url>/payment/form

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

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

Внимание! Перевод покупателя на ”success_url” или «fail_url» является только информационным и НЕ МОЖЕТ подтверждать успех или отказ в приеме платежа!

После проведения платежа клиент перенаправляется на “success_url” или “fail_url”

Ответ содержит поля:

order_no

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

сумма транзакции в валюте, разделитель точка “.”;
currency_code

валюта транзакции (в которой был выставлен счет);
item_name

название товара (если передавалось);
co_inv_id

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

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

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

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа при отклонении платежа:

Content type

application/json

Copy

Expand all

Collapse all

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

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

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

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

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

Первичный запрос

Запрос содержит поля:

type

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

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

номер транзакции в системе мерчанта;
amount

сумма транзакции в валюте, разделитель точка “.”;
currency

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

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

месяц окончания срока действия карты;
card_exp_year

год окончания срока действия карты;
card_cvv

cvv карты;
process_url

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

название товара (поле не обязательное);
first_name

имя владельца карты (Допустимы только латинские буквы);
last_name

фамилия владельца карты (Допустимы только латинские буквы);
user_id

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

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

страна клиента в ISO 3166-1 alpha-2 формате;
email

e-mail плательщика
phone

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

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

город проживания плательщика
post_code

почтовый код плательщика
region

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

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

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

accept_header

color_depth

ip

language

screen_height

screen_width

time_different

window_width

window_height

Важно! Строки запроса должны содержать исключительно латинские буквы и цифры.

POST

/api/host2host

https://<предоставленный url>/api/host2host

Пример запроса PHP:

Copy

Expand all

Collapse all

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

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

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

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

status

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

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

номер транзакции в системе мерчанта (тот же, что и в запросе);
uuid

уникальный идентификатор транзакци, используйте его для поиска и при необходимости связаться с техподдержкой;
co_inv_id

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

ссылка на страницу 3DS, куда необходимо перенаправить клиента;
d3_pareq

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

данные для пересылки.

Пример ответа:

Content type

application/json

Copy

Expand all

Collapse all

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

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

status

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

код ошибки;
description

описание ошибки.

Пример ответа:

Content type

application/json

Copy

Expand all

Collapse all

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

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

При положительном ответе мерчанту необходимо переадресовать клиента на форму 3DS. Для этого используйте параметры из ответа при первичном запросе

Copy

Expand all

Collapse all

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

Итоговый запрос

*Обратите внимание! Не путайте d3_pares и d3_pareq:

d3_pareq вы получаете в ответ при первичном запросе и пересылаете в форму 3DS;
d3_pares вы получаете от формы 3DS и пересылаете в итоговом запросе.

Запрос содержит поля:

type

тип (3ds);
merchant

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

уникальный идентификатор транзакции (параметр, который получаете в ответе при первичном запросе);
order

номер транзакции в системе мерчанта (тот же что и в первичном запросе);
d3_pares

получаете в ответе от формы 3DS;
d3_md

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

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

POST

/api/host2host

https://<предоставленный url>/api/host2host

Пример:

Copy

Expand all

Collapse all

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

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

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

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

status

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

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

уникальный идентификатор транзакции, используйте его для поиска и при необходимости связаться с техподдержкой;
order

номер транзакции в системе мерчанта (тот же что и в запросе);

Пример ответа:

Content type

application/json

Copy

Expand all

Collapse all

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

При ошибке платежа ответ содержит поля:

status

статус платежа (error);
code

код ошибки;
description

описание ошибки.

Пример ответа:

Content type

application/json

Copy

Expand all

Collapse all

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

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

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

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

Первичный запрос

Запрос содержит поля:

type

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

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

номер транзакции в системе мерчанта;
amount

сумма транзакции в валюте, разделитель точка “.”;
currency

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

название товара;
country

страна клиента в ISO 3166-1 alpha-2 формате;
custom

для дополнительной информации о клиенте;
ip

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

цифровая подпись ключом мерчанта. Используются поля «type», «merchant», «order», «amount», «currency». Хешируется методом SHA256. (более детально расписано в разделе “Цифровая подпись в запросах”)

POST

/api/h2hpix

https://<предоставленный url>/api/h2hpix

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

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

status

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

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

номер транзакции в системе мерчанта (тот же, что и в запросе);
uuid

уникальный идентификатор транзакци, используйте его для поиска и при необходимости связаться с техподдержкой;
co_inv_id

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

строка в которой указан адрес оплаты PIX;
img

текстое отображение QR-кода закодированное base64;

Пример ответа:

Content type

application/json

Copy

Expand all

Collapse all

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

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

status

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

код ошибки;
description

описание ошибки;

Пример ответа:

Content type

application/json

Copy

Expand all

Collapse all

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

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

Метод передачи данных может быть POST или GET.

Запрос содержит поля:

merchant

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

номер транзакции в системе мерчанта;
co_inv_id

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

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

GET

/payment/status

https://<предоставленный url>/payment/status

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

В ответ на запрос возвращаются данные в формате JSON:

status

статус транзакции:

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

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

Fail – платеж отклонен (статус финальный)

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

Error – ошибка принятых данных (подпись в ответе пустая «sign» = «»)
order

номер транзакции в системе мерчанта;
description

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

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

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

Пример ответа – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

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

Для корректной настройки проведения выплат зайдите в “Личный кабинет” – “Редактирование мерчанта”.

Подробное описание этих настроек находится в разделе “Регистрация” (пункты 8-11)

Запрос на выплату

Запрос содержит поля:

merchant

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

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

1 - Visa/Mastercard UAH

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

9 - Mastercard EUR

11 - Visa/Mastercard AZN

12 - Visa/Mastercard KZT

16 - Visa/Mastercard UAH (Другой канал)

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

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

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

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

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

номер платежной карты (Visa или Mastercard);
amount

сумма транзакции в валюте, разделитель точка “.”;
currency

валюта транзакции, должна соответствовать полю «method»:

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

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

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

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

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

«UAH» для метода 16 (Другой канал)

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

«EUR» для метода 22 (Другой канал)

«EUR» для метода 23 (Другой канал)

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

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

POST

/merchant/api/payout_send

https://<предоставленный url>/merchant/api/payout_send

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

Ответ содержит поля:

status

статус транзакции:

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

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

Blocked – платеж отклонен (статус финальный)

Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
code

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

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

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

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

Пример ответа — статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Pending:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

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

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

Запрос выплаты на банковские счета (SEPA)

Запрос содержит поля:

merchant

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

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

15 — Payout Iban EUR;
payout_id

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

номер банковского счета;
full_name

имя, фамилия клиента. Максимальная длина 30 символов;
amount

сумма транзакции в валюте, разделитель точка “.”;
currency

валюта транзакции «EUR»:
sign

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

POST

/merchant/api/payout_send

https://<предоставленный url>/merchant/api/payout_send

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

Ответ содержит поля:

status

статус транзакции:

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

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

Blocked – платеж отклонен (статус финальный)

Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
code

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

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

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

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

Пример ответа — статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Pending:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

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

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

Запрос выплаты на банковские счета (PIX)

Запрос содержит поля:

merchant

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

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

21 — Payout PIX BRL;
payout_id

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

идентификационный номер налогоплательщика;
pix_key

ключ PIX пользователя;
amount

сумма транзакции в валюте, разделитель точка “.”;
currency

валюта транзакции «BRL»;
sign

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

POST

/merchant/api/payout_send

https://<предоставленный url>/merchant/api/payout_send

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

Ответ содержит поля:

status

статус транзакции:

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

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

Blocked – платеж отклонен (статус финальный)

Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
code

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

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

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

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

Пример ответа — статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Pending:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

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

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

Запрос статуса платежа (выплата)

Запрос содержит поля:

merchant

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

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

цифровая подпись ключом мерчанта. Используются поля «merchant» и «payout_id». Хешируется методом MD5. (детально расписано в разделе “Цифровая подпись в запросах”).

POST

/merchant/api/payout_status

https://<предоставленный url>/merchant/api/payout_status

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

В ответ на запрос возвращаются данные в формате JSON:

status

статус транзакции:

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

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

Blocked – платеж отклонен (статус финальный)

Error – ошибка принятых данных (подпись в ответе пустая «sign» = «»)
payout_id

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

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

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

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

Пример ответа – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Blocked:

Content type

application/json

Copy

Expand all

Collapse all

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

Запрос баланса

Запрос содержит поля:

merchant

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

запрашиваемая валюта (UAH, USD, EUR, KZT, BRL или AZN);
sign

цифровая подпись ключом мерчанта. Используются поля «merchant», «currency». Хешируется методом MD5 (детально расписано в разделе “Цифровая подпись в запросах”).

POST

/payment/balance

https://<предоставленный url>/payment/balance

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

Ответ содержит поля:

status

статус запроса:

Success – запрос успешен

Error – ошибка принятых данных (в случае, если мерчант не найден, подпись в ответе не передается)
currency

запрашиваемая валюта (UAH, USD, EUR, KZT, BRL или AZN);
balance

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

описание («Wallet balance»);
sign

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

Пример ответа – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

Запрос списка платежей

Методом передачи данных может быть POST или GET.

Запросы списка платежей обрабатываются не более одного в минуту.

Максимальное количество транзакций в ответе 10 000.

Запрос содержит поля:

merchant

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

запрашиваемая валюта (UAH, USD, EUR, KZT, BRL или AZN);
order

номер транзакции в системе мерчанта, с которой начинается выборка в заданном периоде (если передается 0, то возвращаются все транзакции);
start_date

дата и время начала периода в формате YYYY-MM-DD HH:ii:ss;
finish_date

дата и время окончания периода в формате YYYY-MM-DD HH:ii:ss;
status

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

тип транзакции (withdrawal или deposit);
sign

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

GET

/api/payment-list

https://<предоставленный url>/api/payment-list

Пример запроса:

Content type

application/json

Copy

Expand all

Collapse all

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

Ответ содержит поля:

id

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

уникальный идентификатор транзакции (тот же что и «uuid»);
order_id

номер транзакции в системе мерчанта;
subtotal

сумма, зачисленная:

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

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

удержанная комиссия (если тип комиссии процент):

при «Deposit» вычитается с «total»

при «Withdrawal» начисляется на «subtotal»
fee_fixed

удержанная комиссия (если тип комиссии фиксированный):

при «Deposit» вычитается с «total»

при «Withdrawal» начисляется на «subtotal»
total

общая сумма транзакции:

при «Deposit» – сумма пополнения без взимания комиссии

при «Withdrawal» – сумма выплаты с начисленной комиссией
type

тип транзакции (withdrawal или deposit);
status

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

дата и время создания транзакции;
updated_ad

дата и время проведения транзакции.

Пример ответа – статус Success:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Blocked:

Content type

application/json

Copy

Expand all

Collapse all

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

Пример ответа – статус Error:

Content type

application/json

Copy

Expand all

Collapse all

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

Запрос курсов валют

Метод передачи данных может быть POST или GET

Поля для запроса

merchant

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

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

GET

/api/rates

https://<предоставленный url>/api/rates

Content type

application/json

Copy

Expand all

Collapse all

{
    "status":"success",
    "description":"Описание ответа",
    "rates": {
          "CURR1":VAL1,
          "CURR2":VAL2,
    …}
}

Пример:

Content type

application/json

Copy

Expand all

Collapse all

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

или в случае ошибки

Content type

application/json

Copy

Expand all

Collapse all

{
    "status" => "Error",
    "description" => "Описание ошибки"
}

Запрос обмена валют

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

merchant

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

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

сумма обмена
currency_from

валюта обмена
currency_to

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

подпись запроса с использованием метода шифрования sha256

POST

/api/exchange

https://<предоставленный url>/api/exchange

Content type

application/json

Copy

Expand all

Collapse all

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

или в случае ошибки

Content type

application/json

Copy

Expand all

Collapse all

{
    "status": "Error",
    "description" => "Описание ошибки"
}

Коды статуса

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