Регистрация
Для начала работы пройдите регистрацию 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:
Цифровая подпись в 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:
Проверка цифровой подписи
Проверка цифровой подписи проводится при получении запроса. Также, настоятельно рекомендуем, реализовать проверку на стороне мерчанта.
Проверка цифровой подписи
Коллбеки
Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “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_error_resolution
описание ошибки платежа
В случае, если выполняется внутренняя конвертация, в коллбеке могут присутствовать дополнительные поля:
-
co_base_amount
базовая сумма, полученная в запросе;
-
co_base_currency
базовая валюта, получения в запросе платежа;
-
co_rate
курс конвертации;
При конвертации в поле co_cur будет валюта процессинга, а в полях co_amount и co_to_wlt будут суммы в валюте процессинга.
В ответ на принятый пакет сервер мерчанта должен ответить двумя английскими буквами «OK».
Пример:
Коллбек при отказе в проведении платежа (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_error_resolution
описание ошибки платежа
-
co_sign
цифровая подпись ключом мерчанта (более детально расписано в разделе “Цифровая подпись в Callback”).
В ответ на принятый пакет сервер мерчанта должен ответить двумя английскими буквами «OK».
Пример:
Коллбек при выплате
Уведомление будет отправлено в случае изменения статуса транзакции (например с «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 при выплате:
Методы 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, INR и 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 цифры номера карты.
Важно! Строки запроса должны содержать исключительно латинские буквы и цифры.
Пример запроса:
Перенаправление покупателя после проведения платежа
Внимание! Перевод покупателя на ”success_url” или «fail_url» является только информационным и НЕ МОЖЕТ подтверждать успех или отказ в приеме платежа!
После проведения платежа клиент перенаправляется на “success_url” или “fail_url”
Ответ содержит поля:
-
order_no
номер транзакции в системе мерчанта (тот же что и в запросе «order»);
-
amount
сумма транзакции в валюте, разделитель точка “.”;
-
currency_code
валюта транзакции (в которой был выставлен счет);
-
item_name
название товара (если передавалось);
-
co_inv_id
уникальный номер транзакции;
-
co_inv_st
статус транзакции в платежной системе (Success или 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
фамилия владельца карты (Допустимы только латинские буквы);
-
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
Важно! Строки запроса должны содержать исключительно латинские буквы и цифры.
Пример запроса PHP:
При успешном приеме данных (для дальнейшего проведения платежа) ответ содержит поля:
-
status
статус транзакции (3ds);
-
merchant
уникальный идентификатор мерчанта;
-
order
номер транзакции в системе мерчанта (тот же, что и в запросе);
-
uuid
уникальный идентификатор транзакци, используйте его для поиска и при необходимости связаться с техподдержкой;
-
co_inv_id
уникальный номер транзакции;
-
d3_acs_url
ссылка на страницу 3DS, куда необходимо перенаправить клиента;
-
d3_pareq
данные для пересылки;
-
d3_md
данные для пересылки.
Пример ответа:
При отклонении платежа ответ содержит поля:
-
status
статус транзакции (error);
-
code
код ошибки;
-
description
описание ошибки.
Пример ответа:
Перенаправление покупателя на форму 3DS
При положительном ответе мерчанту необходимо переадресовать клиента на форму 3DS. Для этого используйте параметры из ответа при первичном запросе
Итоговый запрос
*Обратите внимание! Не путайте 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. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример:
При успешной обработке запроса ответ содержит поля:
-
status
статус платежа (success);
-
merchant
уникальный идентификатор мерчанта;
-
uuid
уникальный идентификатор транзакции, используйте его для поиска и при необходимости связаться с техподдержкой;
-
order
номер транзакции в системе мерчанта (тот же что и в запросе);
Пример ответа:
При ошибке платежа ответ содержит поля:
-
status
статус платежа (error);
-
code
код ошибки;
-
description
описание ошибки.
Пример ответа:
Финальный статус (коллбек)
Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “Pending” на “Success”), используется механизм коллбеков.
Подробно расписано в разделе “Коллбеки”:
Прием платежей 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. (более детально расписано в разделе “Цифровая подпись в запросах”)
Пример запроса:
При успешном приеме данных (для дальнейшего проведения платежа) ответ содержит поля:
-
status
статус транзакции (pending);
-
merchant
уникальный идентификатор мерчанта;
-
order
номер транзакции в системе мерчанта (тот же, что и в запросе);
-
uuid
уникальный идентификатор транзакци, используйте его для поиска и при необходимости связаться с техподдержкой;
-
co_inv_id
уникальный номер транзакции;
-
qr_code
строка в которой указан адрес оплаты PIX;
-
img
текстое отображение QR-кода закодированное base64;
Пример ответа:
При отклонении платежа ответ содержит поля:
-
status
статус транзакции (error);
-
code
код ошибки;
-
description
описание ошибки;
Пример ответа:
Запрос статуса платежа (прием)
Метод передачи данных может быть POST или GET.
Запрос содержит поля:
-
merchant
уникальный идентификатор мерчанта;
-
order
номер транзакции в системе мерчанта;
-
co_inv_id
уникальный номер транзакции (номер передается после обработки платежа на Process URL мерчанта);
-
sign
цифровая подпись ключом мерчанта. Используются поля «merchant», «order», «co_inv_id». Хешируется методом MD5. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
В ответ на запрос возвращаются данные в формате JSON:
-
status
статус транзакции:
Success – платеж проведен успешно (статус финальный)
Pending – платеж новый или находится в очереди на обработку
Fail – платеж отклонен (статус финальный)
Refund – по платежу был произведен возврат (статус финальный)
Error – ошибка принятых данных (подпись в ответе пустая «sign» = «»)
-
order
номер транзакции в системе мерчанта;
-
description
описание статуса;
-
card_number
маска карты (в формате NNNNNN******NNNN, где N – цифра);
-
error_resolution
описание ошибки платежа;
-
sign
цифровая подпись ключом мерчанта.
Пример ответа – статус Success:
Пример ответа – статус Error:
Выплаты на карту
Для корректной настройки проведения выплат зайдите в “Личный кабинет” – “Редактирование мерчанта”.
Подробное описание этих настроек находится в разделе “Регистрация” (пункты 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. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
Ответ содержит поля:
-
status
статус транзакции:
Success – платеж проведен успешно (статус финальный)
Pending – платеж новый или находится в очереди на обработку. Статус Pending требует дополнительного запроса (подробно расписано в разделе “Запрос статуса платежа (выплата)”).
Blocked – платеж отклонен (статус финальный)
Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
-
code
код статуса транзакции;
-
payout_id
номер исходящего платежа в системе мерчанта;
-
description
описание статуса;
-
sign
цифровая подпись ключом мерчанта.
Пример ответа — статус Success:
Пример ответа – статус Pending:
Пример ответа – статус Error:
Финальный статус (коллбек)
Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “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. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
Ответ содержит поля:
-
status
статус транзакции:
Success – платеж проведен успешно (статус финальный)
Pending – платеж новый или находится в очереди на обработку. Статус Pending требует дополнительного запроса (подробно расписано в разделе “Запрос статуса платежа (выплата)”).
Blocked – платеж отклонен (статус финальный)
Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
-
code
код статуса транзакции;
-
payout_id
номер исходящего платежа в системе мерчанта;
-
description
описание статуса;
-
sign
цифровая подпись ключом мерчанта.
Пример ответа — статус Success:
Пример ответа – статус Pending:
Пример ответа – статус Error:
Финальный статус (коллбек)
Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “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. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
Ответ содержит поля:
-
status
статус транзакции:
Success – платеж проведен успешно (статус финальный)
Pending – платеж новый или находится в очереди на обработку. Статус Pending требует дополнительного запроса (подробно расписано в разделе “Запрос статуса платежа (выплата)”).
Blocked – платеж отклонен (статус финальный)
Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
-
code
код статуса транзакции;
-
payout_id
номер исходящего платежа в системе мерчанта;
-
description
описание статуса;
-
sign
цифровая подпись ключом мерчанта.
Пример ответа — статус Success:
Пример ответа – статус Pending:
Пример ответа – статус Error:
Финальный статус (коллбек)
Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “Pending” на “Success”), используется механизм коллбеков.
Подробно расписано в разделе “Коллбеки”
Запрос выплаты на банковские счета (UPI)
Запрос содержит поля:
-
merchant
уникальный идентификатор мерчанта;
-
method
метод выплаты, целое число:
26 — Payout UPI INR;
-
payout_id
номер исходящего платежа в системе мерчанта;
-
account
идентификационный номер налогоплательщика;
-
full_name
имя, фамилия клиента. Максимальная длина 30 символов;
-
customs_phone
номер телефона плательщика, +91XXXXXXXXXX;
-
customs_email
e-mail плательщика;
-
customs_ifsc
IFSC (Код финансовой системы Индии);
-
customs_ip
IP-адрес клиента;
-
amount
сумма транзакции в валюте, разделитель точка “.”;
-
currency
валюта транзакции “INR”;
-
sign
цифровая подпись ключом мерчанта. Используются поля “merchant”, “method”, “payout_id”, “account”, “amount”, “currency”, “customs_phone”, “customs_email”, “customs_ifsc”, “customs_ip”. Хешируется методом MD5. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
Ответ содержит поля:
-
status
статус транзакции:
Success – платеж проведен успешно (статус финальный)
Pending – платеж новый или находится в очереди на обработку. Статус Pending требует дополнительного запроса (подробно расписано в разделе “Запрос статуса платежа (выплата)”).
Blocked – платеж отклонен (статус финальный)
Error – ошибка принятых данных. Ответ содержит подпись пустым ключом (статус не финальный и является основанием для выяснения причины возникновения данного статуса)
-
code
код статуса транзакции;
-
payout_id
номер исходящего платежа в системе мерчанта;
-
description
описание статуса;
-
sign
цифровая подпись ключом мерчанта.
Пример ответа — статус Success:
Пример ответа – статус Pending:
Пример ответа – статус Error:
Финальный статус (коллбек)
Для уведомления мерчанта о том, что транзакция получила финальный статус (например, с “Pending” на “Success”), используется механизм коллбеков.
Подробно расписано в разделе “Коллбеки”
Запрос статуса платежа (выплата)
Запрос содержит поля:
-
merchant
уникальный идентификатор мерчанта;
-
payout_id
номер исходящего платежа в системе мерчанта;
-
sign
цифровая подпись ключом мерчанта. Используются поля «merchant» и «payout_id». Хешируется методом MD5. (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
В ответ на запрос возвращаются данные в формате JSON:
-
status
статус транзакции:
Success – платеж проведен успешно (статус финальный)
Pending – платеж новый или находится в очереди на обработку
Blocked – платеж отклонен (статус финальный)
Error – ошибка принятых данных (подпись в ответе пустая «sign» = «»)
-
payout_id
номер исходящего платежа в системе мерчанта;
-
code
код статуса платежа;
-
description
описание статуса;
-
sign
цифровая подпись ключом мерчанта.
Пример ответа – статус Success:
Пример ответа – статус Error:
Пример ответа – статус Blocked:
Запрос баланса
Запрос содержит поля:
-
merchant
уникальный идентификатор мерчанта;
-
currency
запрашиваемая валюта (UAH, USD, EUR, KZT, BRL, INR или AZN);
-
sign
цифровая подпись ключом мерчанта. Используются поля «merchant», «currency». Хешируется методом MD5 (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
Ответ содержит поля:
-
status
статус запроса:
Success – запрос успешен
Error – ошибка принятых данных (в случае, если мерчант не найден, подпись в ответе не передается)
-
currency
запрашиваемая валюта (UAH, USD, EUR, KZT, BRL, INR или AZN);
-
balance
доступная сумма в валюте с двумя знаками после запятой, разделитель точка (например — 212.07);
-
description
описание («Wallet balance»);
-
sign
цифровая подпись ключом мерчанта.
Пример ответа – статус Success:
Пример ответа – статус Error:
Запрос списка платежей
Методом передачи данных может быть POST или GET.
Запросы списка платежей обрабатываются не более одного в минуту.
Максимальное количество транзакций в ответе 10 000.
Запрос содержит поля:
-
merchant
уникальный идентификатор мерчанта;
-
currency
запрашиваемая валюта (UAH, USD, EUR, KZT, BRL, INR или 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 (детально расписано в разделе “Цифровая подпись в запросах”).
Пример запроса:
Ответ содержит поля:
-
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:
Пример ответа – статус Blocked:
Пример ответа – статус Error:
Запрос курсов валют
Метод передачи данных может быть POST или GET
Поля для запроса
-
merchant
идентификатор мерчанта
-
currency_from
базовая валюта
Пример:
или в случае ошибки
Запрос обмена валют
Поля для проведения рекуррентного платежа
-
merchant
идентификатор мерчанта
-
order
номер платежа в системе мерчанта
-
amount
сумма обмена
-
currency_from
валюта обмена
-
currency_to
валюта результата
-
currency sign
подпись запроса с использованием метода шифрования sha256
или в случае ошибки
Коды статуса
Код статуса | Статус | Финальный | Описание |
---|---|---|---|
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 | Нет | Ошибка не документирована |