Idempotent checkouts: why a retry should never charge twice
Send a stable Idempotency-Key with every POST /v2/checkouts — derived from your order id, not generated per attempt — and a retry after a timeout returns the original checkout instead of creating a second charge.
Updated · by T3raTech · Free: 25 payments per 30 days, $0; Basic: 250 payments per 30 days for $9/month; Pro: 2,500 payments per 30 days for $29/month
The failure it prevents
A request times out and the client cannot tell whether the checkout was created. Without a key the safe-looking retry creates a second checkout and can charge the buyer twice.
Choosing the key
Use something stable per order, such as order-1001. A random value per attempt defeats the point: each retry would look like a new request.
Where it applies
Every checkout, hosted or wallet push. Settlement polling and webhooks are reads and need no key.
Reconciling
Match on the checkout reference (pay_…) that comes back; the ledger holds one row per settlement.