payment-idempotency

What problem does it solve?

Apply when implementing idempotency logic in payment connector code or handling duplicate payment requests. Covers paymentId as idempotency key, payment state machine transitions, retry semantics for cancellation and refund operations, and requestId handling. Use for preventing duplicate charges and ensuring correct Gateway retry behavior across Create Payment, Cancel, Capture, and Refund endpoints.

Core Features & Use Cases

• Prevent duplicate charges by enforcing idempotency across payment endpoints using paymentId and requestId
• Manage a payment state machine to ensure valid transitions across Create Payment, Cancel, Capture, and Refund
• Support retry semantics for gateway retries within the 7-day window and preserve exact responses for duplicates
• Example: a connector stores the initial response and reuses it for retry requests to the same paymentId

Quick Start

Configure your payment handlers to check a persistent store for existing paymentId before processing and return the exact stored response on duplicates.