Skip to main content
Пройдите этот список перед первым боевым трафиком. Каждый пункт ссылается на подробную страницу. Если весь список пугает объёмом — не пугайтесь. Сначала закройте короткий «минимум» ниже: этого достаточно, чтобы принять первый платёж безопасно. Остальное можно докручивать по мере роста.

​
Минимум, чтобы принять первый платёж безопасно

Пять пунктов, без которых нельзя выходить на боевой трафик:
  • Секрет не лежит в коде. Ключ читается из переменных окружения или секрет‑хранилища, не из репозитория и не с фронтенда. → Безопасность в проде
  • Есть HTTPS‑endpoint для вебхуков, доступный из интернета, и он проверяет подпись по сырому телу. → Настройка вебхуков
  • Статус заказа меняется только по вебхуку — и перепроверяется запросом /v1/payment/info, а не по редиректу пользователя. → Приём первого платежа
  • Обработка вебхука идемпотентна — дедуп по uuid + status, повтор той же доставки ничего не ломает. → Настройка вебхуков
  • Суммы хранятся строками (или в minor‑единицах), без float. → Форматы сумм и денег
Закрыли эти пять — можно принимать реальные деньги. Дальше идёт полный харденинг.

​
Полный прод‑харденинг (по мере роста)

Когда базовый чек‑лист пройден и трафик растёт, пройдитесь по областям ниже.

​
Безопасность и ключи

  • Секрет ключа хранится только на сервере — в секрет‑хранилище, не в браузере/мобильном приложении, не в репозитории. → Безопасность в проде
  • Включён IP‑allowlist для API‑ключа: сначала добавлен IP backend, затем включён контроль. → IP‑allowlist
  • Понятно, как ротировать ключ — только в личном кабинете под 2FA; в публичном API ротации нет; заморозки выплат при ротации нет. → Безопасность в проде
  • Часы сервера синхронизированы (NTP) — при расхождении больше ±5 минут подпись не проходит и приходит merchant.bad_signature (окно времени проверяется внутри сверки подписи). → Как подписать запрос

​
Подпись и идемпотентность

  • Тело сериализуется один раз и используется и для подписи, и для отправки (байт‑в‑байт). → Как подписать запрос
  • Заголовок Idempotency-Key на каждом денежном запросе. Значение генерируется до первой отправки и одинаково во всех попытках одного действия. Повтор вернёт тот же ответ и заголовок Idempotent-Replayed: true. → Идемпотентность
  • Каждый платёж создаётся с уникальным order_id, каждая выплата — с уникальным order_id/reference (для выплат он обязателен). Это второй, бизнес‑уровень дедупликации: он работает, даже если заголовок забыли. → Идемпотентность
  • Ретраи с backoff на 429/503/500.
  • 409 — НЕ всегда финал. Нельзя трактовать любой 409 как «уже обработано» и бросать операцию: так вы потеряете законную выплату. Разделяйте:
    • 409 payout.funds_maturing — повторяемая: средства ещё дозревают, повторите позже с backoff, и выплата пройдёт.
    • 409 idempotency.in_progress — повторяемая: запрос с этим Idempotency-Key ещё выполняется, подождите и повторите.
    • прочие 409 (например payout.insufficient_funds) — конфликт состояния: не повторяйте вслепую, сверьтесь через */info.
    → Рецепт устойчивого клиента

​
Вебхуки

  • Приёмник вебхуков настроен и проверен: endpoint зарегистрирован, секрет сохранён. → Настройка вебхуков
  • Подпись вебхука проверяется правильным алгоритмом (timestamp + . + сырое тело), по сырому телу. → Объект вебхука
  • Обработка идемпотентна: дедуп по uuid + status, порядок доставок не подразумевается. → Настройка вебхуков
  • 2xx возвращается только после успешной обработки.
  • Пробное событие доходит и возвращает status_code: 200. → Отладка вебхуков

​
Платежи

​
Выплаты и баланс

  • Учтены незрелые (maturing) средства — выводимый остаток может быть меньше показанного; 409 payout.funds_maturing обрабатывается как временная ошибка и повторяется, а не считается отказом. → POST /v1/balance
  • Адрес получателя валидируется до вызова выплаты (выплаты необратимы и уходят сразу). → Первая выплата
  • Большие списки выплат идут через батч POST /v1/payout/batch (до 5000, асинхронно), а не циклом и не пачками по 100. → Массовые операции
  • Результат батча разбирается поэлементно (частичный успех — норма), статус опрашивается через /v1/batch/info. → Массовые операции

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

  • Мониторинг баланса и статусов выплат настроен.
  • Хранится сопоставление order_id ↔ ваш заказ на вашей стороне.
  • Суммы хранятся строками/в minor‑единицах, без float. → Форматы сумм и денег
  • Поддерживаемые сети/валюты сверяются программно через */services, а не только по таблице. → POST /v1/payment/services

​
Связанные страницы

Безопасность в проде

Настройка вебхуков

Приём первого платежа

Первая выплата