Idempotency
Last updated: November 20, 2024
Occasionally, you may need to retry a request due to a disrupted API call. For example, if you encounter a network error or timeout.
Information
Some merchant-initiated transactions (MIT) may benefit from automatic downtime retries if they fail due to an issuer or acquirer network timeout.
The following endpoints from our API support idempotent requests, so you can safely retry them without the risk of a duplicate request:
/payment-contexts/payments/payments/{id}/authorizations/payments/{id}/cancellations/payments/{id}/captures/payments/{id}/refunds/payments/{id}/voids/transfers
To perform an idempotent payment or payment action request, provide a unique key in the Cko-Idempotency-Key HTTP header.
By default, keys expire after 24 hours for both the sandbox and production environments. After this window of time, the request will be processed as normal.
To change the default idempotency window for your production environment, contact your Account Manager or [email protected].
Information
We strongly recommend using V4 UUIDs.
Subsequent requests with the same key will return the same HTTP status code and response body as the original request, providing that it was processed successfully.
If the original request could not be processed, an idempotent result will not be saved and the payment will be reattempted. For example, if there was a validation error.
If we detect concurrent requests with the same idempotency key, only one request will be processed and the other requests will return a 429 Too many requests response. For example, if you automatically retry a payment after experiencing a network issue, while the original request is still being processed.
We recommend waiting at least 30 seconds before you reattempt a request.