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

API

На странице

Обзор

Подключите Paymos к своему backend через подписанные webhook-endpoint'ы с разделением по окружениям и полным контролем доставки.

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

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

  1. Создайте webhook endpoint в Панель → Разработчикам → Вебхуки.
  2. Выберите категорию Invoice, Withdrawal или обе.
  3. При необходимости ограничьте события инвойсов выбранными проектами. События выплат действуют на весь аккаунт мерчанта.
  4. Сохраните показанный секрет whsec_… на сервере.
  5. Проверяйте каждую доставку по неизменённому raw body запроса.
  6. Сохраняйте event_id, отвечайте 2xx и обрабатывайте событие асинхронно.

У Production и Sandbox отдельные endpoint'ы, секреты и события. Тестовое событие никогда не доставляется на production endpoint.

Правила endpoint'ов

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

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

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

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

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

Получение балансов События вебхуков