Skip to main content

Idempotency

Every POST in this API takes an Idempotency-Key, and it is the one thing standing between a retried request and a second charge to the buyer.

Send Idempotency-Key on every POST. A retry with the same key returns the original resource without creating a duplicate operation. The replay is signalled by the status code: the original create returns 201, while an idempotent replay returns 200. For POST /v1/payment_intents the status code is the only replay signal. The replay body carries the payment's status and amounts, its decline fields (decline_code, action, decline_message and rule_code, as on the original) and its metadata. It can leave out card and client_confirm: read GET /v1/payment_intents/{id} for those. Capture and void mark a replay with the header Idempotent-Replayed: true instead; their status and body are the stored ones. POST /v1/refunds and POST /v1/tokens additionally echo an idempotent: true field in the replay body. The browser charge POST /v1/public/sessions/{sessionId}/charge marks a replay both ways: the header Idempotent-Replayed: true and replayed: true in the body (Charge at submit). Choose keys that uniquely identify your server-side operation — <order_id>_<operation> is the convention used in this guide (ord_42_create, ord_42_capture, ord_42_refund). Generate keys server-side; never derive them from buyer-supplied input (cookies, query strings, request bodies). Keys starting with vp_sys: (any letter case) are reserved for platform use: POST /v1/payment_intents and its capture and void refuse one with 400 validation_error before anything is charged, so choose a different key. POST /v1/refunds refuses those keys too, and also keys in the forms the platform uses for refunds it issues itself, before anything is refunded. A UUID never collides with either. One exception to "reuse the key": a replayed POST /v1/sessions returns the original session as it is now, so if its status reads failed, reusing the key only hands back that finished session. Start the new attempt with a new key (Create a session).

Reuse the key when you retry — never add a counter to it

A timeout or a 5xx is a retry of the same operation, and collapsing it is the entire job the key does. A key carrying an attempt or retry counter changes on every attempt, so the duplicate check never matches and the retry goes through as a fresh request: on POST /v1/payment_intents that is a second real charge, and on POST /v1/refunds a second real refund to the buyer.

Change the key only for an operation that is genuinely different — a deliberate second refund of the same payment (ord_42_refund_2), or a new order.

Two exceptions, both after a finished answer:

  • A confirmed decline. A charge that came back 201 with status: "failed" is finished. Its key only returns that decline, and never reaches the card again. The next attempt (another card, or the same card after the buyer fixes it) takes a new key, for example ord_42_charge_2. A timeout or a 5xx is not a decline: keep the key.
  • A canceled refund. A refund the provider voided before it settled comes back 200 with status: "canceled", terminal, with no money returned, and reissuing it under the same key replays that response forever. That one needs a new key: a canceled refund is not a completed refund.
The mirror image: a second deliberate operation of the same kind needs a NEW key

<order_id>_<operation> is the convention, and it has a sharp edge in the other direction. Any repeat of the same operation type on the same order needs its own suffix — not just a second full refund.

The case that bites: you issue a $5.00 partial refund on ord_42 as a shipping adjustment, then weeks later a second, unrelated $5.00 goodwill credit on the same order. Same key, same amount, same body — so the second call is a replay. It returns 200 with idempotent: true, and the buyer never receives the second $5.00. Your records say two refunds succeeded; their statement shows one.

Give the second one its own key (ord_42_partial_refund_2, or your support-ticket id), and read the idempotent field on every refund response before recording it as a fresh refund — see Refunds — the Refund response. A replay is not a failure, so nothing else will tell you.

Every charge needs a key by 28 October 2026​

On POST /v1/payment_intents, keyless charges are being retired, and 28 October 2026 is the cut-off. Today a charge with no Idempotency-Key still goes through, and its response carries three headers saying so:

Deprecation: true
Sunset: Wed, 28 Oct 2026 00:00:00 GMT
Link: <https://docs.vonpay.com/reference/error-codes#idempotency_key_required>; rel="deprecation"; type="text/html"

From that date a keyless charge can be refused at any time with 400 idempotency_key_required, before anything is charged. If your charge responses carry a Sunset header today, that call is the one to fix.

Some connections already refuse a keyless charge or refund with the same code, because there the key is the only record that tells a retry from a new payment. The identical keyless request fails identically; add a stable key and reuse it verbatim. Send it on every POST and you never have to track which routes enforce it.

The three outcomes, and why two of them must not be retried the same way​

Three responses look alike and mean opposite things — the split is not along the usual 4xx/5xx line.

ResponseWhat happened to the buyerWhat to do
400 idempotency_key_requiredNothing — refused before chargingAdd a stable key and send again
409 charge_in_progressA charge for this key is already running or already done, this request's own outcome is not confirmed yet, or an earlier charge on the same saved card has not resolvedDo not retry, and never change the key. Read the original payment's status first: the buyer may already have been charged
503 charge_reservation_unavailableNothing. The key could not be recorded, so nothing reached your providerRetry shortly with the same key
503 service_unavailableThis request reached nothing. If the message says we could not check your key, an earlier request with this key may already have charged the buyer, so do not mark the order unpaidRetry the same request with the same key; the retry returns the earlier payment if there was one
A 409 here is the one that can cost a buyer real money

"Conflict" reads as collision — mint a fresh key and try again, and that is the single action that can double-charge: the earlier attempt may already have succeeded. On 409, read the original payment's status and never vary the key; if it persists, contact support with that Idempotency-Key.

await vonpay.paymentIntents.create(
{ amount: 1499, currency: "USD", captureMethod: "automatic" },
{ idempotencyKey: "ord_42_create" },
);
vonpay.payment_intents.create(
amount=1499,
currency="USD",
capture_method="automatic",
idempotency_key="ord_42_create",
)
-H "Idempotency-Key: ord_42_create"

Reusing a key with a different request body returns 422 idempotency_replay_incompatible rather than silently overwriting — a reason to reuse the key, not to vary it.

How long a key lasts​

On POST /v1/payment_intents we keep a key for at least 30 days after the request that first used it. This rule is for payment intents only; a refund's key returns that refund as described on Refunds. Within that time, send every retry with the same key and the same body. A retry gets one of these answers:

  • The recorded result of the earlier request.
  • 409 charge_already_in_flight or 409 charge_in_progress, while the outcome of the earlier request is not known yet. After charge_in_progress, do not retry: read the original payment's status.
  • 503 service_unavailable, when we could not check the key at that moment. Retry again with the same key.

Do not change the key to get past any of these answers. We free a key sooner only when we know that nothing was charged, so that a corrected request can use it. After 30 days, do not rely on a key to detect a duplicate.