What problem does it solve?
It prevents duplicate payment processing caused by gateway retries and replays, ensuring the same request identifiers always yield the same stored outcome instead of triggering multiple acquirer charges.
Core Features & Use Cases
- Deterministic idempotency for Create Payment: Enforces
paymentId as the idempotency key and returns the exact stored response for duplicates, avoiding repeated acquirer calls.
- Safe operation idempotency for Cancel/Capture/Refund: Enforces
requestId as the idempotency key for operational endpoints so retries don’t double-cancel or double-refund.
- Correct payment state machine transitions: Validates allowed transitions (e.g., no capture after cancellation) to keep reconciliation consistent across retries, including the 7-day retry window for
undefined status payments.
Quick Start
Use payment-idempotency when implementing your payment connector handlers so that duplicate Create Payment requests with the same paymentId return the previously stored response, and Cancel/Capture/Refund requests with the same requestId do not re-process the underlying acquirer operation.
