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

Ключ идемпотентности - 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 на своей стороне.