I’m planning to charge a saved card on file using the Payments API (CreatePayment), and I want to make sure a customer is never charged twice when we retry after a network timeout.
The Idempotency documentation explains how duplicate requests are handled, but I couldn’t find how long an idempotency key is retained.
How long does Square keep an idempotency key for CreatePayment? (For example, 24 hours, or indefinitely?)
After that period, if the same key is sent again, will a new payment be created?
If our server loses the response, what is the recommended way to confirm whether the payment was created? (For example, searching payments by reference_id?)
1 & 2. 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?
You can subscribe to the payment.created webhook that will provide another reconciliation path. At the end of the day, idempotency is built for this exact purpose to help you try another request with the relief that it will not execute another attempt if the previous one was already taken care of.
To make this reliable, generate the key once per checkout on your server and store it with the order before the first attempt. Only generate a new key when the customer deliberately starts a new payment.