Skip to main content
Повторный вызов создающего эндпоинта не должен создавать второй объект. Иначе обычный сетевой таймаут (ответ потерялся, хотя платёж уже создан) обернётся дублем — вторым счётом или второй выплатой. Защититься можно двумя способами — они работают вместе.

​
1. Заголовок Idempotency-Key (рекомендуемый)

Как пользоваться:
  • Значение — любая уникальная строка до 255 символов (обычно UUID v4). Сгенерируйте его до первой отправки запроса и передавайте одно и то же во всех повторах одного действия. Новое действие — новый ключ.
  • Где работает — на всех создающих операциях: платёж, выплата, возврат, статический кошелёк, перевод, батч.
  • Поведение повтора — повтор с тем же ключом вернёт тот же ответ, что и первая успешная попытка (второй объект не создаётся), и заголовок ответа Idempotent-Replayed: true — по нему видно, что это переигранный результат, а не новая операция.

​
2. Ваш order_id

Второй, бизнес-уровень дедупликации — он работает, даже если заголовок забыли:
  • Платежи — order_id необязателен, но настоятельно рекомендуется. Повтор с order_id, для которого уже есть живой счёт, вернёт этот же счёт, а не создаст дубль (терминальный или просроченный счёт создание нового не блокирует). Проверка-и-создание защищены advisory-локом по паре (мерчант, order_id) от гонки одновременных запросов.
  • Выплаты — order_id обязателен (без него — 400 payout.order_id_required). Идемпотентность по (мерчант, order_id): повтор вернёт уже созданную выплату.
Механизмы независимы и работают вместе: order_id дедуплицирует на уровне бизнес-сущности, а заголовок Idempotency-Key защищает сам HTTP-вызов. Заголовок поддерживают: POST /v1/payment, /v1/payment/refund, /v1/payment/resolve, /v1/payment/batch, /v1/refund/batch, /v1/payout, /v1/payout/mass, /v1/payout/batch, /v1/transfer/to-personal. На выплатных ссылках заголовок не действует — там дедупликация через поле reference.

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

Устойчивый клиент

Создание платежа

Создание выплаты

Формат запросов