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

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

При создании платежа вы передаёте external_id — ваш собственный идентификатор заказа. Пара (мерчант, external_id) уникальна. Если вы повторитеPOST /integration/transactions с тем же external_id, Cashera не создаст новую транзакцию, а вернёт уже существующую.

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

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

Поведение

Новый external_id → создаётся объект, ответ 201 Created.
Существующий external_id → возвращается тот же самый ранее созданный объект с его текущим статусом — и снова с кодом 201 Created. Это не ошибка и не 409.
Тело при повторе игнорируется — возвращается исходный объект, даже если сумма или метод отличаются.

Повтор возвращает оригинал с кодом 201

Повторный запрос с тем же external_id возвращает исходный объект (а не новый и не 409) с тем же кодом 201 Created. Так работают и платежи, и выплаты. Код 409 Conflict возможен лишь в крайне редкой гонке БД при одновременном создании — тогда просто повторите запрос статуса.

# Тот же 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 на своей стороне.