Webhook URL

Описание

Задача этого функционала передать данные об оплаченном счете на сервер продавца. Это нужно для того, чтобы автоматически обработать платеж в магазине продавца и выдать товар или услугу вашему покупателю.

WH URL устанавливается индивидуально для каждого проекта в виде ссылки на скрипты и обработчики платежей внутри магазина продавца. Адрес должен быть на https и на доменном имени: IP-адреса не принимаются, сертификат проверяется при каждой отправке.

Каждый раз, когда статус счета сменяется на «Оплачен», сервис отправляет POST запрос на этот URL в следующем формате:

{
   "wallet":{
      "id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
      "name":"usdt-tron",
      "blockchain":"tron",
      "cryptocurrency":"usdt",
      "address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
   },
   "project":{
      "id":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
      "name":"My project",
      "commissionPayer":"seller",
      "commissionRate":1
   },
   "invoice":{
      "id":"a4c9e2ee-9a03-43e5-a1a1-00caf679d16a",
      "uid":"AFhygKX21ecd",
      "createDatetime":"2024-02-26 13:29:24",
      "timeToPayDatetime":"2024-02-27 01:29:24",
      "commissionFiatUSD":0.05,
      "amountFiatUSD":5.02,
      "amountFiat":5,
      "calcAmountFiat":5.02,
      "currencyFiat":"USD",
      "description":null,
      "serviceData":null,
      "status":"paid"
   },
   "payment":{
      "id":"f986ad8d-2298-473d-982a-efbc817b975d",
      "amount":5.02,
      "hash":"74763b65e43bcc9492a6ce9a7f26fbfdbd7635aecd3454420b5e9534cba50ee6",
      "transactionDatetime":"2024-02-26 13:32:57"
   }
}

Уведомление отправляется при любом переходе счета в статус «Оплачен» — и когда сервис нашел платеж автоматически, и когда продавец привязал платеж к счету вручную.

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

Параметр	Описание
`wallet.id`	ID кошелька в формате UUID
`wallet.name`	Название кошелька
`wallet.blockchain`	Блокчейн крипто кошелька
`wallet.cryptocurrency`	Криптовалюта кошелька
`wallet.address`	Адрес крипто кошелька
`project.id`	ID проекта в формате UUID
`project.name`	Название проекта
`project.commissionPayer`	Плательщик комиссии
`project.commissionRate`	Размер комиссии в %
`invoice.id`	ID счета в формате UUID
`invoice.uid`	ID счета (для покупателя)
`invoice.createDatetime`	Дата и время создания счета (UTC)
`invoice.timeToPayDatetime`	Дата и время, до которого счет действителен для покупателя (UTC). Поиск платежей по счету продолжается еще 1 час после этой отметки — с учетом медленных сетей. Поэтому уведомление может прийти по счету, который уже отображался как просроченный
`invoice.commissionFiatUSD`	Сумма комиссии сервиса. Рассчитывается относительно суммы `invoice.amountFiatUSD`
`invoice.amountFiatUSD`	Сумма в валюте USD. При создании счета рассчитывается по текущему курсу относительно суммы `invoice.amountFiat`. В момент оплаты перезаписывается фактически поступившей суммой, приведенной к USD по курсу на этот момент. От нее же пересчитывается комиссия в `invoice.commissionFiatUSD`
`invoice.amountFiat`	Оригинальная сумма счета в фиатной валюте. Не меняется
`invoice.calcAmountFiat`	Рассчитанная сумма в валюте `invoice.currencyFiat` по курсу криптовалюты на момент оплаты. Этот параметр может отличаться от суммы в `invoice.amountFiat` из-за того, что покупатель мог оплатить счет не сразу после создания, а через некоторое время. За это время курс криптовалюты относительно `invoice.currencyFiat` мог поменяться в любую сторону
`invoice.currencyFiat`	Валюта фиата
`invoice.description`	Описание, которое было задано при создании счета
`invoice.serviceData`	Служебные данные, которые были заданы при создании счета
`invoice.status`	Статус счета
`payment.id`	ID платежа в формате UUID
`payment.amount`	Сумма платежа в криптовалюте
`payment.hash`	Хэш транзакции в блокчейне
`payment.transactionDatetime`	Дата и время транзакции в блокчейне (UTC)

Подпись уведомления

Каждый запрос подписывается секретом вебхука. Подпись передается в заголовках X-Timestamp и X-Signature и позволяет убедиться, что уведомление отправил сервис, а не посторонний, узнавший адрес вашего обработчика.

Проверяйте подпись до обработки заказа. Механика и готовые примеры — в разделе «Проверка подписи вебхука».

Периодичность доставки

По адресу WH URL сервер должен ответить с HTTP кодом 2xx. Любой другой код, таймаут или обрыв соединения считаются неудачной доставкой.

Редиректы не выполняются: ответ 301 или 302 — это неудачная доставка, а не переход по новому адресу. Указывайте конечный адрес обработчика.

На соединение отводится 5 секунд, на весь запрос — 10 секунд. Если обработчик не уложился, доставка считается неудачной.

При неудачной доставке сервис отправляет повторные запросы со следующей периодичностью:

Через 5 минут после последней неудачной доставки
Через 15 минут
Через 30 минут
Через 1 час
Через 3 часа
Через 6 часов
Через 12 часов
Через 24 часа

Дальнейшие попытки доставки уведомления прекращаются.

Отключение WH URL

Иногда WH скрипт интернет-магазина при корректной обработке платежа отдает HTTP код отличный от 2xx. Это приводит к частым повторным периодическим запросам нашим сервером по таймингам, указанным в предыдущем разделе, что дает лишнюю нагрузку на наш и клиентский сервер.

Для предотвращения таких случаев у нас работает механизм отключения WH URL в проекте. Чтобы этого не происходило, выполните следующие шаги:

Измените программный код WH URL так, чтобы при успешной обработке платежа он отдавал код 2xx, обычно 200. Проверьте, используя любой эмулятор, например, Postman.
Напишите в тех. поддержку для коррекции настроек.
Снова включите WH URL в настройках проекта и сохраните проект.

Описание​

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

Подпись уведомления​

Рекомендации по обработке​

Периодичность доставки​

Отключение WH URL​

Описание

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

Подпись уведомления

Рекомендации по обработке

Периодичность доставки

Отключение WH URL