Idempotency

Network requests fail. A POST can time out after the server charged the card but before your code saw the response, so a blind retry would charge twice. Idempotency keys make a retried request return the original result instead of running again.

The Idempotency-Key header is REQUIRED, not optional, on every money-moving endpoint. Omit it and the request is rejected with 400 idempotency_key_required before anything is charged:

Endpoint
POST /v1/payment_intents	create a Payment Element intent (names the amount)
POST /v1/charges	create a charge
POST /v1/charges/:id/capture	capture an authorization
POST /v1/charges/:id/void	void an authorization
POST /v1/refunds	refund a charge
POST /v1/subscriptions	create a subscription
POST /v1/3ds/sessions	open a 3DS session
POST /v1/3ds/retry-decline	retry a soft decline

Everything else is read-only or naturally safe to retry, and ignores the header. Confirming an intent (POST /payment_intents/:client_secret/confirm) does not take an idempotency key: the client secret already addresses one unpaid session.

On POST /payment_intents, POST /charges, POST /3ds/sessions and POST /3ds/retry-decline you may send the key in the JSON body as idempotency_key instead of the header. The header wins if both are present; one of the two must be there.

How to use it#

Send an Idempotency-Key header with a value you generate; a UUID v4 is ideal. Reuse the same key when you retry the same request:

curl https://api.worthypayments.com/v1/charges \
  -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36" \
  -H "x-api-key: sk_test_xxx" \
  -H "Idempotency-Key: 5f3b9c1e-7a2d-4e88-9f1a-2c4d6e8b0a11" \
  -H "Content-Type: application/json" \
  -d '{"amount":4999,"currency":"usd","card":{"number":"ev:...","cvv":"ev:...","exp_month":"12","exp_year":"30"}}'

• First call with that key → runs normally, the result is stored.
• Any retry with the same key → returns the stored response (same status, same body), with headers Idempotency-Replayed: true and X-Idempotency-Replayed: true (same value; the X- name is the documented alias). The card is not charged again. A request with no Chrome User-Agent never reaches this layer, Cloudflare answers 1010.

Always generate a fresh key per logical operation. Two genuinely different charges must use two different keys, or the second will replay the first.

Stable per order, not per click. Use something tied to the payment you mean once (your order id, cart id, or a UUID you store with that order). Do not call crypto.randomUUID() on every “Pay” press. A double-submit or network retry then becomes a second charge. The reference checkout derives the key from the order for this reason.

Scope and lifetime#

The key is namespaced to your API key, so you can use any value scheme you like (order-1234-charge works as well as a UUID) without worrying about global collisions.

Concurrent retries#

If two requests with the same key arrive at the same time (e.g. an aggressive retry fires before the first finished), the second one gets a 409:

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_in_progress",
    "message": "Idempotency key is currently processing"
  }
}

This is your signal to wait a moment and retry. The first request is still running. Once it completes, retrying the same key replays its stored result.

The in-progress claim expires after 10 minutes. If the first request never settles (the process died mid-charge, the connection dropped before a result was recorded) the key stays locked for ten minutes and then becomes claimable again, so a stuck key cannot wedge an order forever. The tradeoff is the reason for the number: while the claim holds, a retry is correctly refused; once it lapses, a retry runs the request for real rather than replaying. Ten minutes is comfortably longer than any charge takes, so in practice the lapse only fires when the first attempt truly never completed.

Backing off on a 409 is therefore the right move, and giving up on it is not: keep retrying the same key with a short delay until you get a real answer. Switching to a fresh key after a 409 is the one thing that turns a protected retry into a double charge.

What gets replayed#

• Success (2xx): stored and replayed for 24h, with one exception: a pending charge whose outcome is not known yet (see below).
• A card decline (402) raised by the charge itself: stored and replayed, so a retry returns the same decline rather than attempting the card again. A gateway refusal (decline_code duplicate_transaction, processing_error, …) is a decline like any other and is replayed the same way.
• A fraud block 400 (FRAUD_BLOCKED / failed_precondition), pre-screen or scored: stored and replayed exactly. A scored block is terminal under its key: the retry returns the same refusal naming the same failed charge, records no second charge and sends no second charge.failed webhook. A 400 without charge (a pre-screen block, or a scored block whose charge id was not returned) is replayed for 24 hours exactly as it was, still without charge, even if the failed charge was recorded and its webhooks fired. A retry must not come back as a different 402 card_declined. Trying again after a block takes a new key, which is a new attempt and is screened again. See Fraud blocks.
• Server errors (5xx), 408, 409, 429: not stored. The key is released so a genuine retry can run the request again.
• Other settled 4xx (the envelope the client actually received): stored and replayed. The edge no longer releases a DONE 4xx on a later null settle. That is what turned a 400 FRAUD_BLOCKED into a 402 on retry.

A pending charge is not a final answer#

POST /v1/charges answers status: "pending" when the gateway did not tell us in time whether the card was charged (a timeout or a broken connection after the request may have reached it). That pending is not stored under your key: the key is released at once.

• Retry with the same key after a short delay. The payments service first asks the gateway what happened to that attempt. If it charged, you get that charge back (nothing is charged twice). If it provably did not, the retry runs the payment, once. While the answer cannot be established yet, the retry gets 409 idempotency_in_progress: wait and retry the same key again until you get a charge or a 402.
• Never retry it under a new key. If the first attempt lands, that is a second charge.
• You can also follow the charge by its id (GET /v1/charges/{id}, or the charge.succeeded / charge.failed webhooks): a pending charge resolves on its own within minutes.

Only this unknown outcome is released. A pending ACH debit (accepted by the bank network, settling over days) is a real answer and is stored and replayed for 24 hours as usual.

Reusing a key with a different body#

A key is bound to the request that claimed it. Send the same Idempotency-Key with a different body and the call is rejected with 400 idempotency_error. It does not replay the first response, and it does not run the second request.

The comparison is a hash of the fields that decide the money: for a charge that is amount, currency, capture mode and payment method; for a refund it is the whole body, so adding a reason to an otherwise identical retry counts as a different request. This matters if you key on your order id, which is otherwise good practice: an order whose amount changes (cart edit, tax recalculation) must claim a new key rather than reuse the old one.

Where the guarantee lives#

Re-running is safe rather than a second charge because the payments service keeps its own idempotency record keyed off the same request: it replays its stored outcome instead of authorizing again. The edge cache is a latency and consistency layer on top of that, not the only thing standing between you and a double charge.

One consequence worth planning for: the edge's replay cache is best-effort. If its store is unavailable the cache degrades to a per-process fallback, which does not span instances. The downstream record still holds, but you should not treat an edge replay as a guarantee you can build settlement logic on. Reconcile on the charge id.

The key is required#

On the money-moving POSTs listed at the top of this page the header is mandatory. Omitting it does not run the request unprotected. It is rejected outright, before anything is charged:

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "Idempotency-Key header is required for this request",
    "param": "Idempotency-Key"
  }
}

On POST /charges, POST /3ds/sessions and POST /3ds/retry-decline an idempotency_key field in the JSON body satisfies the requirement instead; the header wins when both are present.

Every other endpoint is read-only or naturally safe to retry, and ignores the header.

A second guard you do not control: the acquirer's own duplicate window#

Idempotency above is ours, and it is keyed on your Idempotency-Key. Your acquirer runs a second, independent check that is keyed on the payment itself (same card and same amount inside a window) and it does not know or care what key you sent. NMI's default window is 20 minutes. On NMI's sandbox the order reference is not part of the check: two charges with different order references on the same card and amount were still refused.

That means the two can disagree, and the case that surprises people is this one:

POST /v1/charges   Idempotency-Key: order_A   $9.11 on card ...1111   -> succeeded
POST /v1/charges   Idempotency-Key: order_B   $9.11 on card ...1111   -> failed

A new key, so our replay logic correctly treats it as a new payment, and the acquirer still refuses it as a duplicate. The second call comes back at once as a 402 with code: "card_declined", decline_code: "duplicate_transaction" and the gateway's own text in message (Duplicate transaction REFID:…). Read back, the charge is failed with outcome.network_status: "not_sent_to_network": the card network never saw it. Through the Payment Element the same refusal reaches onError as card_declined with declineCode: "duplicate_transaction". See Gateway refusals.

This is a protection, not a defect. It is what stops a double-submitted cart or a retrying job from charging a cardholder twice when the retry legitimately carries a different key. Treat it the same way you treat a decline: surface it, do not hammer it.

What to do about it:

• Do not retry the identical charge to "get past" it. A retry inside the window fails the same way, and outside it you risk the second charge actually going through.
• Know what a genuine second payment looks like to the acquirer. Two separate orders for the same amount on the same card are unusual but legitimate. A different order reference tells them apart only where the acquirer includes it in its check; NMI's sandbox does not, so the second is refused until the window passes.
• Watch for it in testing. Firing the same fixture amount repeatedly against a sandbox is the fastest way to hit this, and it reads as "the money path broke" when nothing did. Vary the amount between test runs.

The window length and whether it can be tuned at all are set by the acquirer, not by this API, some refuse to let it be adjusted per charge. You cannot switch it off from the request.