Идемпотентность

Создание платежа (POST /v1/payments) идемпотентно. Это защищает от двойного создания при потерянных ответах и повторах.

Правило

Одна логическая команда создания → один стабильный Idempotency-Key.

• Тот же ключ + тот же семантический запрос → возвращается исходный платёж (повтор).
• Тот же ключ + другой запрос → 409 idempotency_conflict.

Заголовок обязателен:

Idempotency-Key: <ваш-ключ>

Ключ — печатаемые ASCII‑символы (без пробелов и управляющих символов), длина 1–255.

Генерация ключа

Генерируйте высокоэнтропийный, стабильный ключ на одну логическую команду создания — например, UUID, сохранённый вместе с вашим заказом, чтобы повтор использовал тот же ключ. В примерах документации ключ вроде order_demo_1001_attempt_1 выбран для читаемости — в продакшене не используйте предсказуемые ключи.

Потерянный ответ — повторяйте с тем же ключом

Не генерируйте новый ключ при потере ответа

Если вы отправили POST /v1/payments, но не получили ответ (таймаут, обрыв сети), повторите тот же запрос с тем же Idempotency-Key и тем же телом. Eleven Pay вернёт исходный платёж.

Никогда не создавайте второй платёж и не берите новый ключ только потому, что HTTP‑ответ потерян — это приведёт к дублю.

Различайте заголовок ответа Idempotency-Replayed: true|false — он показывает, был ли ответ повтором.

Конфликт (409)

409 idempotency_conflict означает, что этот ключ уже использован для другого логического запроса (например, другая сумма или другой merchant_order_id). Не переиспользуйте один ключ для разных команд. Для новой логической команды создания возьмите новый ключ.

GET не требует ключа

GET /v1/payments/{reference} — безопасный для повторов метод и не требует Idempotency-Key. См. Сверка.