Идемпотентность ломают не платежи — её ломают кривые ключи и лень в ретраях

Идемпотентность ломают не платежи — её ломают кривые ключи и лень в ретраях

90% команд думают, что idempotency-key — это магический антидубль. Нет. Если ключ живёт 10 минут, а ваш шлюз отвечает через час, вы уже открыли дверь двойному списанию. Ключ должен покрывать весь жизненный цикл операции: создание, ретраи, вебхуки, ручную проверку статуса.

Типовые косяки:
— Ключ генерят на клиенте и меняют при каждом чихе.
— В хранилище кладут только запрос, но не ответ и финальный статус.
— Сравнивают payload «примерно такой же» и ловят фантомные дубли.
— Не отделяют sync-ответ от async-уведомления, а потом удивляются, почему платёж «успешен» дважды.

Правильная схема скучная, как аудитор PCI DSS: один бизнес-идентификатор операции, жёсткое TTL, атомарная запись результата, и неизменяемый маппинг request → response → final state. Идемпотентность должна переживать падение API, повтор webhook и ручной повтор запроса. Документация — это ложь, логи — истина.

Если у вас нет гарантии на уровне БД, а есть только “не шлите дважды”, то это не архитектура, а костыль на костыле и финтехом погоняет. Идемпотентность или смерть.