Песочница, ошибки и go-live

Песочница

Маршруты /api/v1/integration/sandbox/transactions/{transaction}/... симулируют колбэки провайдера:

Действие	Смысл
`pay`	успешная оплата
`fail`	отказ
`timeout`	истечение / expired
`out-of-order`	сначала fail, потом запоздавший paid

Песочница работает на том же API-домене, в том числе в production. В ЛК откройте «Настройки → Интеграция и API → Песочница» и создайте дополнительный test_ ключ. Его можно отдельно перевыпустить или отозвать; боевой ключ продолжит работать. Полный токен показывается один раз и используется одновременно как X-Api-Key и секрет HMAC. Все sandbox-запросы требуют HMAC, включая GET.

Создайте платёж: POST /api/v1/integration/sandbox/transactions. Тело как у обычного создания платежа: amount в minor units, currency (RUB/USD), payment_method, external_id, description, необязательные metadata и callback_url.

Используйте полученный uuid для сценариев выше. Реальные провайдеры не вызываются; payment_url, h2h_url, requisites и expires_at равны null. Истечение имитируется явно через timeout; комиссии в песочнице равны нулю.

Проверьте состояние через GET /api/v1/integration/sandbox/transactions/{uuid}, поиск /by-external-id/{externalId} или GET списка /api/v1/integration/sandbox/transactions с cursor-пагинацией и фильтрами.

Настройте и включите webhook кассы и его HMAC-секрет в ЛК. Смена статуса создаёт обычный transaction.status_updated webhook с дополнительным transaction.environment: test. Подпись проверяется webhook-секретом кассы, а не API-ключом. При необходимости передайте отдельный тестовый callback_url. Доставка использует существующие outbox и очередь webhooks: они должны работать.

Ответы API содержат environment: test. Проверяйте transaction.environment в webhook: тестовые события не должны выдавать реальные товары. События и их повторы сохраняют свой webhook ID. Повтор сценария не создаёт новое событие. После paid поздние fail/timeout игнорируются; после failed/expired возможен поздний paid.

Тестовые платежи хранятся отдельно, не попадают в боевые списки, оборот, баланс, выплаты или расчёты с провайдерами. external_id изолирован от боевых платежей: одинаковый запрос возвращает тот же sandbox-платёж, изменённое тело — 409. test_ ключ работает только с sandbox-маршрутами; live_ ключи не допускаются в sandbox. Возвраты, выплаты, подписки, реальная платёжная форма и H2H-реквизиты не симулируются.

Ошибки

Типичные HTTP-коды:

Код	Смысл
401	не прошла аутентификация / HMAC
403	ключ ок, но действие запрещено (IP allowlist, disabled merchant, …)
404	сущность не найдена
409	конфликт идемпотентности
422	ошибка валидации полей
429	rate limit

Для метода оплаты может действовать дневной лимит оборота по каждой валюте (календарные сутки по МСК, 00:00–24:00). В лимит входят платежи в статусах pending и paid; failed и expired лимит освобождают. Платёж, который превысил бы лимит, отклоняется с 422 и "message": "Daily turnover limit for this payment method is exceeded.", транзакция при этом не создаётся. Повтор того же платежа будет отклоняться, пока лимит не освободится или не начнутся следующие сутки.

Для касс Telegram Stars платёж без Telegram ID покупателя отклоняется с 422 ("Telegram Stars payments require the buyer Telegram ID in metadata.userId." или, если формат не tg123456789, "metadata.userId must be the buyer Telegram ID in the format tg123456789."). Если Telegram ID заблокирован, возвращается 403 и "message": "Payments for this Telegram user are blocked."; повторять такой платёж бесполезно. Подробнее — в «Платежи».

X-Request-Id/request_id — корреляционный идентификатор для поддержки; он не заменяет X-Smerch-Request-Id, входящий в HMAC-подпись.

Если create завершился таймаутом или 5xx, исход операции неизвестен. Не создавайте новый бизнес-ID: повторите запрос с тем же external_id и тем же телом. Для платежа также доступен поиск по external_id; возврат повторяется с тем же Idempotency-Key. Изменение тела при повторе приводит к 409.

В v2 ошибки ближе к Problem Details (RFC 9457). В v1 чаще JSON с message / errors.

Чеклист перед боем

HMAC-подпись на всех Integration-запросах.

API-ключ и webhook secret только на сервере.

Webhook URL на HTTPS, проверка подписи включена.

Обработка webhook идемпотентна.

Суммы в минорных единицах.

Для возвратов всегда Idempotency-Key.

Sandbox прогнан: pay / fail / timeout / out-of-order; поздний paid после failed обработан корректно.

IP allowlist (если включён) содержит ваши egress IP.