JSON-уведомления о переводах

При подключении по схеме HTTP+JSON магазин заранее определяет адреса, по которым будут приходить HTTP-уведомления от системы «Инвойсбокс».

Безопасность

Для защищенного взаимодействия магазина и системы «Инвойсбокс» можно использовать несколько вариантов:

• MD5 - базовый вариант, подключен по-умолчанию;
• SSL/ключи - альтернатива md5 с высоким уровнем безопасности.

Дополнительную информацию читайте на странице правил защиты информации.

Формат взаимодействия

Запросы передаются по протоколу HTTP 1.1 методом POST.

Формат передачи параметров в запросе:

• все параметры передаются в JSON строке в теле POST-запроса;
• MIME-тип: application/json;
• кодировка символов: UTF-8.

Параметры запроса

Параметр	Описание
participantId	Идентификатор магазина
participantOrderId	Номер заказа магазина, присвоенный заказу в системе учёта магазина
ucode	Уникальный номер счёта в системе «Инвойсбокс»
timetype	Формат временной точки платежа
time	Время платежа в формате ATOM
amount	Сумма платежа
currency	Валюта платежа
agentName	Место оплаты
agentPointName	Уточнение к месту оплаты
testMode	Флаг тестовой оплаты
sign	Подпись запроса

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

{
   "participantId":"0001",
   "participantOrderId":"1234",
   "ucode":"78001-42315-227456-61838",
   "timetype":"ATOM",
   "time":"2020-01-07T08:27:06+03:00",
   "amount":"1117.65",
   "currency":"RUB",
   "agentName":"Инвойсбокс",
   "agentPointName":"",
   "testMode":"0",
   "sign":"d26a7d920d27463c59c81a6318913044"
}

Параметры ответа

Параметр	Описание
resultCode	Код ответа магазина
resultMessage	Комментарий ответа магазина

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

{
   "resultCode":0,
   "resultMessage":"1234"
}

В случае успешной обработки информации об оплате, магазин должен вернуть значение resultCode=0. В случае возникновения ошибки, магазин должен вернуть детальное описание такой ошибки в параметре resultMessage, при этом значение параметра resultCode не должно равняться нулю.

Проверка параметров запроса

Подпись запроса

При использовании базового варианта безопасности с MD5, система «Инвойсбокс» добавляет в запросы параметр с именем sign (подпись запроса). Значение параметра — MD5-хэш от строки, собранной из значений параметров этого же запроса вместе с ключём безопасности.

При получении запроса магазину необходимо проверять, что запрос отправлен системой «Инвойсбокс» и данные в запросе пришли полностью. Для этого магазин проверяет значение параметра sign . Если значение sign не совпадает с результатом расчёта хэш-функции MD5 от переданных параметров, в обработке запроса нужно отказывать и вернуть ошибку.

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

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

Пример:

Исходная строка	Результат хеширования
131order112345-12345-12345-12345unixtime1231323231000.00RUBAlfa-Click0Password	59ce8e882ac936a0062a46a2d4055b0a

Часто-встречаемые проблемы при обработке подписи

• В строке для подписи используются значения с HTML-сущностями. Обратите внимание, в исходной строке для формирования подписи, кавычки (двойные, одинарные), знак амперсанда и другие специальные символы должны использоваться как есть, без преобразований.
  Правильно: 131order112345-12345-12345-12345unixtime1231323231000.00RUBООО "ОРЦ"0Password
  Не правильно: 131order112345-12345-12345-12345unixtime1231323231000.00RUBООО "ОРЦ"0Password.
• В строке для подписи используются кодировка, отличная от UTF-8. Обратите внимание, в исходной строке для формирования подписи используется кодировка только UTF-8.

Состав запроса

Магазин должен сверить сумму платежа в запросе с суммой заказа в системе учёта. Если сумма платежа не совпадает с суммой заказа, в обработке запроса нужно отказывать и вернуть ошибку.

Источник запроса

Рекомендуем дополнительно проверить IP-адрес отправителя запроса. Список IP системы «Инвойсбокс» вы можете найти на странице правил защиты информации или запросить в службе поддержки.