Чек-лист интеграции

​

Ключи и доступ

• Отдельные API-ключи для боевого и sandbox-сайта; секреты хранятся в секрет-менеджере CMS, не в репозитории.
• Scope ключа минимально достаточный: deposit_only для приёма, deposit_and_payout только там, где CMS делает выплаты/возвраты, read_only для дашбордов.
• IP-адреса серверов CMS добавлены в whitelist сайта (и в allow-list ключа, если используете).
• Часы серверов синхронизированы (NTP): подпись действует ±300 с (TIMESTAMP_SKEW).
• Legacy-заголовок X-Api-Secret не используется — только X-Signature (HMAC-SHA256).

​

Депозиты

• order_id уникален на вашей стороне; повтор трактуется по политике сайта (DUPLICATE_ORDER_ID или идемпотентный возврат).
• lifetime соответствует сценарию (сеть, скорость клиента); истёкшие депозиты обрабатываются по deposit.failed/expired.
• Обработаны все исходы: paid, paid_over, wrong_amount (+ окно доплаты / допуск недоплаты, если включены).
• Для memo-сетей (TON, XRP…) клиенту показываются и адрес, и memo.
• Статусы читаются из вебхуков, а GET /v1/public/deposits/{uuid} используется для сверки, не для поллинга каждую секунду (isFinal — сигнал остановки).

​

Выплаты

• Адрес получателя валидируется на вашей стороне до вызова API; для memo-сетей передаётся destinationMemo.
• Учтено одобрение оператора (pending_approval) и лимиты — CMS не считает выплату отправленной до payout.broadcasted.
• Идемпотентность: повтор POST /v1/public/payouts с тем же order_id не создаёт вторую выплату.
• Обрабатывается payout.failed (возврат средств клиенту / ручная проверка), см. failReason.

​

Вебхуки

• Подпись X-Signature проверяется до обработки; X-Event-Id хранится для идемпотентности (повторы бывают).
• Обработчик отвечает 2xx за 10 с и не делает тяжёлую работу синхронно (очередь на вашей стороне).
• Подписка на события настроена (opt-in: deposit.confirmation, deposit.underpaid, deposit.refund_failed…).
• Ротация callback-секрета отрепетирована: принимаются X-Signature и X-Signature-Prev в grace-период.
• Мониторится авто-отключение вебхуков сайта (callback.auto_disabled) и есть процедура replay.

​

Песочница и тесты

• Полный сценарий прогнан в песочнице: создание → эмуляция платежа → вебхуки → выплата → исход.
• Проверены негативные сценарии: неверная подпись, просроченный timestamp, чужой uuid, дубликат order_id.
• Постановка на мониторинг: rate-limit заголовки (X-RateLimit-*), ошибки 5xx, задержки вебхуков.

​

Эксплуатация

• Есть контакт дежурного платформы и понимание, кто одобряет выплаты и возвраты.
• Возвраты (POST /v1/public/deposits/{uuid}/refund) — договорённость, кто их инициирует (CMS или оператор).
• Ключи ротируются по регламенту; старые отзываются в админке.