Перейти к содержимому

API

На странице

Обзор

Подключите Paymos к своему серверу через подписанные адреса вебхуков с разделением по окружениям и полным контролем доставки.

Paymos отправляет HTTPS POST, когда меняется состояние инвойса, вывода или депозита платёжного канала. Вебхуки — основной асинхронный сигнал для вашего сервера: API-ответ запускает операцию, а событие вебхука сообщает результат после обработки в блокчейне.

Схема интеграции

  1. Создайте адрес вебхука в Дашборд → Разработчик → Вебхуки.
  2. Выберите одну или несколько категорий событий: «Инвойсы», «Выводы», «Платёжные каналы».
  3. При необходимости ограничьте события инвойсов и платёжных каналов выбранными проектами — фильтр у них общий. События выводов действуют на весь аккаунт мерчанта, фильтр на них не влияет.
  4. Сохраните показанный секрет whsec_… на сервере.
  5. Проверяйте каждую доставку по неизменённому исходному телу запроса.
  6. Сохраняйте event_id, отвечайте 2xx и обрабатывайте событие асинхронно.

У рабочего и тестового режима отдельные адреса, секреты и события. Тестовое событие никогда не доставляется на рабочий адрес.

Правила адресов

  • URL должен использовать HTTPS.
  • Для одного мерчанта можно настроить до 10 адресов на окружение.
  • Один активный URL нельзя зарегистрировать дважды в одном окружении.
  • У адреса должна быть хотя бы одна категория событий.
  • Без фильтра проектов на адрес приходят события всех проектов.
  • Приостановка или удаление адреса прекращает новые доставки на него.

Заголовки доставки

Заголовок Контракт
Content-Type application/json; charset=utf-8
X-Webhook-Id Стабильный ID evt_…; не меняется при повторах и ручной переотправке
X-Webhook-Timestamp Unix-время этой попытки доставки в секундах
X-Webhook-Signature t={timestamp},v1={hmac_hex}; при ротации может содержать два значения v1

Доставка идёт не реже одного раза, а порядок не гарантируется. Дедуплицируйте по X-Webhook-Id и применяйте состояние ресурса из data — не считайте количество событий и не полагайтесь на порядок прихода.

Документация вебхуков

Симуляция депозита канала События вебхуков