payment-idempotency — скилл для Claude Code: защита от двойных

Что делает payment-idempotency

Скилл включается, когда вы пишете обработчики Create Payment, Cancel, Capture и Refund в платёжном коннекторе или разбираетесь с дублирующимися запросами. Он задаёт правила идемпотентности: paymentId служит ключом для Create Payment, requestId — для отмены, подтверждения и возврата. Повторный вызов с тем же paymentId должен вернуть сохранённый ответ, а не идти в эквайер заново.

Внутри — разбор состояний платежа (undefined → approved → settled, undefined → denied, approved → cancelled) и примеры кода на TypeScript: как проверить хранилище перед обработкой и как отдать тот же ответ. Отдельно сказано про асинхронные методы вроде Boleto и Pix: до подтверждения эквайером статус остаётся undefined, синхронное одобрение недопустимо.

Хранить ответы нужно в постоянном хранилище — PostgreSQL, DynamoDB или VBase для VTEX IO. In-memory не подходит: после перезапуска записи пропадут, и Gateway, который повторяет запросы со статусом undefined до 7 дней, снова дойдёт до эквайера. Если два повтора приходят одновременно, обычная запись «последний победил» теряет обновление статуса — нужен etag или ifMatch. Это повод проверить свой слой хранения до релиза.

Скилл не покрывает формы ответов и HTTP-методы PPP, логику асинхронных callback-уведомлений, PCI-требования и терминальные платежи POS — для них есть отдельные скиллы.