payment-idempotency — Claude Code skill: stop duplicate charges

What payment-idempotency does

The skill applies when you write Create Payment, Cancel, Capture or Refund handlers in a payment connector, or when duplicate payment requests show up in your logs. It sets the idempotency rules: paymentId is the key for Create Payment, requestId for cancel, capture and refund. A repeat call with the same paymentId returns the stored response instead of calling the acquirer again.

Inside are the payment state transitions (undefined → approved → settled, undefined → denied, approved → cancelled) and TypeScript examples: query the store before processing, then return the exact stored response. Async methods such as Boleto and Pix must stay at status: "undefined" until the acquirer confirms — approving them synchronously is wrong.

Responses belong in a persistent store: PostgreSQL, DynamoDB or VBase for VTEX IO. In-memory storage loses records on restart, and the Gateway retries Create Payment with undefined status for up to 7 days, so each retry reaches the acquirer again. When two retries overlap, last-write-wins can drop a status update, so persist with an etag or ifMatch. Worth checking your storage layer before release.

The skill leaves PPP response shapes and HTTP methods, async callback notifications, PCI compliance and POS terminal payments to their own skills.