Table of contents
- Quick read
- Readiness check
- Separate safe retries from duplicate charges
- Require a durable idempotency key on every write
- Record the key lifecycle and the conflict behavior
- Define the retry and reconciliation window
- Test duplicate delivery and partial failure
- Alert on duplicate attempts and orphaned keys
- Review after a provider or flow change
- Role brief
- Frequently asked questions
- Sources
Is the handoff ready?
Use these checks before access expands or the first ticket begins.
Intent model
Ready: Define the payment intent, amount, and final states in writing.
Needs work: The lane has no written record for this check.
Key storage
Ready: Store the key, request hash, provider, and creation time durably.
Needs work: The lane has no written record for this check.
Reconciliation
Ready: Run a scheduled comparison of local and provider payment state.
Needs work: The lane has no written record for this check.
Failure test
Ready: Simulate timeout, restart, and redelivery without a duplicate charge.
Needs work: The lane has no written record for this check.
Separate safe retries from duplicate charges
List the payment calls that create or change money, such as a charge, a refund, a capture, and a payout. Record which calls are safe to repeat and which must never run twice for the same intent. Note the provider endpoints that accept a client-supplied key. A retry rule that treats every call the same will eventually duplicate a charge.
Write the definition of one payment intent and the record that represents it. Note the order, invoice, or subscription that the intent belongs to and the amount it authorizes. Record the state that means the intent is final and the states that may still be retried. The key is only meaningful when the intent behind it is defined.
Require a durable idempotency key on every write
Generate the key before the first provider call and store it with the payment intent. Record the key, the request body hash, the provider, and the creation time. Reuse that key for every retry of the same intent, including retries from a different worker. A key generated at retry time is a new request and defeats the protection.
Store the key in durable storage that survives a process restart and a queue redelivery. Record the database row or table and the retention period. Note the rule for a key that is older than the provider retention window. A key held only in memory disappears exactly when a crash makes the retry necessary.
Record the key lifecycle and the conflict behavior
Write what happens when the provider reports a key conflict or returns the stored response for a repeated key. Record the fields the team compares before accepting the stored result, such as amount, currency, and customer. Note the path for a conflict that represents a different request with the same key. A conflict is a signal to stop and reconcile, not to generate a new key and try again.
Record the retention and cleanup rule for keys and their responses. Note the period when a late retry could still match the original intent. Keep the key and the outcome together so support can answer a customer question. A key that is deleted before the provider forgets it creates a window for a duplicate.
Define the retry and reconciliation window
Write the retry schedule with a maximum attempt count and a clear backoff. Record which error classes are retried, such as a timeout or a provider server error, and which are final, such as a declined card. Note the point when the system stops retrying and moves the intent to manual review. An uncapped retry loop can turn a provider delay into a flood.
Write the reconciliation job that compares local payment state with the provider after a timeout. Record the interval, the matching key, and the person who reviews a mismatch. Note how the job handles a payment that succeeded at the provider but failed locally. Reconciliation is the control that catches the case the retry logic cannot see.
Test duplicate delivery and partial failure
Run a test that sends the same request twice with the same key and confirm the provider returns one result. Record the response, the local state, and the customer-visible outcome. Note the worker that handled each request and the timing. A test that only checks the happy path does not exercise the protection.
Simulate a timeout after the provider accepted the request and before the application stored the response. Record the reconciliation path and the final state of the intent. Repeat the test across a process restart and a queue redelivery. The rule is proven when the system recovers without a second charge.
Alert on duplicate attempts and orphaned keys
Alert when the same intent produces more than one provider request with different keys. Record the alert owner and the first evidence to collect. Note the dashboard that shows intent, key, and provider request together. A duplicate key alert that no one owns is only a log line.
Alert on intents that have a key but no final state after the agreed window. Record the age threshold and the reconciliation owner. Note the customer message for a payment that is still pending. The alert should reach a person who can finish the reconciliation, not a shared queue.
Review after a provider or flow change
Review the rule when the provider changes its idempotency behavior, its retention window, or its error codes. Record the new behavior and the date of the change. Re-run the duplicate and timeout tests against the new behavior. A rule written for the old provider version can fail silently after an upgrade.
Review the rule when a new payment method, currency, or checkout flow is added. Record the new intent shape and the key fields that must match. Note the test that proves the new flow is idempotent. New payment paths are where duplicate charges most often appear.
Copy-ready brief
Put the operating agreement in writing.
List charge, refund, capture, and payout calls that change money.
Generate once per intent, store before the call, and reuse on every retry.
Compare amount and customer before accepting a stored response.
Keep the duplicate test, timeout test, and reconciliation output.
Frequently asked questions
Can the retry job generate a fresh key?
No. A fresh key creates a new intent at the provider and can duplicate the charge.
What if the provider stores the response but the app crashed?
The reconciliation job must match the stored key and apply the provider outcome locally.
Should a declined card be retried?
Usually no. Classify final declines separately from timeouts and provider server errors.
How long should keys be kept?
Keep them at least as long as the provider retention window and the reconciliation period.
Sources
- Stripe idempotent requests
Key behavior, retention, and replay semantics.
- IETF Idempotency-Key header draft
A proposed cross-vendor idempotency header.
- PayPal idempotency
How a second provider describes key reuse and conflicts.
- RFC 9110 HTTP semantics
Method safety and idempotence definitions.
