Outsourced ProgrammersPowered by StealthAgents

Write a payment retry idempotency rule for an outsourced integration

A rule that gives every payment write a durable key, separates safe retries from duplicate charges, and proves the behavior under timeout and replay.

Write a payment retry idempotency rule for an outsourced integration
WORK_LANE / FIELD GUIDE / APIREVIEW QUEUEACCEPTANCEPASSowner review requiredEVIDENCE TRAILTICKET → BRANCH → REVIEW → CLIENT RELEASE
Table of contents
  1. Quick read
  2. Readiness check
  3. Separate safe retries from duplicate charges
  4. Require a durable idempotency key on every write
  5. Record the key lifecycle and the conflict behavior
  6. Define the retry and reconciliation window
  7. Test duplicate delivery and partial failure
  8. Alert on duplicate attempts and orphaned keys
  9. Review after a provider or flow change
  10. Role brief
  11. Frequently asked questions
  12. 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.

Put the operating agreement in writing.

Writes to protect

List charge, refund, capture, and payout calls that change money.

Key rule

Generate once per intent, store before the call, and reuse on every retry.

Conflict rule

Compare amount and customer before accepting a stored response.

Evidence

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

  1. Stripe idempotent requests

    Key behavior, retention, and replay semantics.

  2. IETF Idempotency-Key header draft

    A proposed cross-vendor idempotency header.

  3. PayPal idempotency

    How a second provider describes key reuse and conflicts.

  4. RFC 9110 HTTP semantics

    Method safety and idempotence definitions.

Build a programming lane your technical owner can review.

Bring the stack, backlog, acceptance checks, and release boundaries. We will help scope the role around the work.

Discuss your programming needs