What is the retention/expiration window for an idempotency_key on the Payments API (POST /v2/payments / CreatePayment)? After how long does resending a request with a previously-used idempotency_key stop returning the original cached result and get processed as a new charge instead? Does this differ for card-not-present / merchant-initiated charges (saved card, no customer present) vs. card-present?
Welcome to the Developer Forum!
What is your use case, or what is your concern here? We do not publish a retention period for CreatePayment idempotency keys, but what’s the longest delay you anticipate you need to support between the original request and a retry?
Thanks for the quick response. Our use case: a daily cron job retries a merchant-initiated card-on-file charge (CreatePayment) for an invoice that’s past its due date, using one deterministic idempotency_key per invoice. We retry once a day for up to 3 total attempts, then pause and notify the customer — so the longest gap between the original request and a possible retry using that same key is roughly 48–72 hours.
Is that window safely within whatever retention/dedup period you do apply internally, even though it’s not publicly documented? And separately — is there any officially supported way to query for an existing payment by a given idempotency key (vs. listing payments and matching ourselves), in case we ever need to check status after a long gap?
Are the daily retries following a confirmed decline, or a timeout where the payment outcome is unknown? That changes how you should use the key:
- Unknown outcome: retry the same request with the same idempotency key. Don’t switch keys while the previous outcome is unresolved.
- Confirmed decline: if another collection attempt is appropriate, use a new key for that attempt, rather than one key across every attempt for the invoice.
Your 24-hour spacing and 3-attempt limit align with our card-on-file retry guidance, but retries should depend on the decline reason. I’d also say that you are in the safe zone as for a possible retry using the same key within 72 hours. There’s no read-only lookup by idempotency key.
You can subscribe to the payment.created webhook that will provide another reconciliation path, so that you can actively listen to the notification when an event happens. This would help reconcile even when the original response is lost.