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" : "https://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" => "https://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"
}

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

Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “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 Нет Ошибка не документирована