Idempotency
What is idempotency?
An API call or operation is idempotent if it always produces the same outcome, regardless of how many times it is executed. This ensures that accidental duplicate calls do not cause unintended consequences.
This feature is especially valuable when an API call fails due to network issues or the temporary unavailability of Yoco’s services.
Idempotent requests using our API
The Checkout API enables idempotency by allowing API operations to include
an optional unique string as an idempotency key in an additional Idempotency-Key
header. When the request is retried with the same key, the API will return the
same result, status code and a additional HTTP response header of
Idempotent-Replayed set to true.
The method for creating unique idempotency keys is up to you, but we recommend using 128-bit keys to avoid accidental key collisions.
If you want to keep things simple, use UUIDv4.
Replayed responses returns the status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed.
Keys are removed from the system automatically after 24 hours. A later request with the same key after its expiry period will be treated as a new request.
Idempotency is only supported for POST requests.