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

Ключ идемпотентности - external_id

При создании платежа вы передаёте external_id - ваш собственный идентификатор заказа. Пара (мерчант, external_id) уникальна. Безопасный повтор должен сохранять тот же режим создания и тот же исходный payload.

Безопасные повторы

Это позволяет безопасно повторять запрос при таймаутах и сетевых сбоях: вы либо создадите платёж, либо получите тот, что уже был создан по этому external_id.

Поведение

Новый external_id → создаётся объект, ответ 201 Created
Прямой платёж с payment_method → повтор возвращает существующую транзакцию с кодом 201 Created
Общая форма без payment_method → точный повтор возвращает ту же checkout-сессию или уже созданную из неё транзакцию
Изменённый payload общей формы → API возвращает 409 Conflict, не изменяя исходный платёж
Смена режима (добавление или удаление payment_method при том же external_id) → API возвращает 409 Conflict

При retry повторяйте исходный запрос без изменений

При таймауте используйте тот же external_id и отправляйте тот же JSON. Не меняйте сумму, валюту, описание, metadata, URL или наличие payment_method. Состояние также можно безопасно получить через поиск по external_id.

# Тот же external_id - вернётся уже созданная транзакция
curl -X POST .../integration/transactions \
  -H "X-Api-Key: $CASHERA_API_KEY" \
  -d '{ "amount": 49900, "currency": "RUB",
        "payment_method": "sbp", "external_id": "order-10428",
        "description": "Подписка Pro, 1 мес." }'

Один external_id - один заказ

Генерируйте external_id на стороне вашей системы и привязывайте строго к одному заказу. Не переиспользуйте его для разных платежей - иначе получите ссылку на старую транзакцию.

Поиск по external_id

По этому же идентификатору можно в любой момент запросить статус через GET /integration/transactions/by-external-id/{externalId}, не сохраняя uuid Cashera на своей стороне.

Ключи операций с подпиской

Создание подписки используетexternal_id: один ID и исходные параметры соответствуют одной подписке. Повтор после смены тарифа также содержит первоначальные параметры создания. Заголовок Idempotency-Key для создания не заменяет external_id.

Изменение условий и внеочередное списание требуютIdempotency-Key. Ключ непустой, не более 200 символов, без управляющих символов. Он относится к одной подписке, одному действию и исходному JSON. Повтор с другими параметрами или для другого действия даёт 409.

Запрос	Защита повторов	Сохраняйте
Создание подписки	external_id	ID и первоначальные параметры создания
update	Idempotency-Key	UUID подписки, ключ и исходный JSON, включая дату
charge-now	Idempotency-Key	UUID подписки, ключ и UUID принятого платежа
cancel	Состояние самой подписки	UUID подписки и подтверждённый результат отмены

После тайм-аута не создавайте новый ключ

Сначала выясните результат старой попытки. Сохраните ключ до HTTP-запроса, чтобы worker после перезапуска не создал новый. Для update повторяйте также исходную дату; не пересчитывайте её от текущего времени. Подробно: ошибки и безопасные повторы подписок.