Idempotency
The Payment API supports idempotency, if requested by the client, by supplying the Idempotency-Key header. If you retry an idempotent call multiple times, the server will only create the resource once.
You do not need to provide the Idempotency-Key header for GET, PUT, and DELETE requests, as these are idempotent by definition.
The Idempotency-Key header is a string of up to 64 single-byte characters. It must be generated by the client. Ratepay recommends using a UUID v4 to generate it. It is not allowed to reuse the same idempotency key for different calls.
The response of the retried idempotent call depends on the result of the first call. If the first call failed with a server error as denoted by an HTTP 5xx status code, the Payment API executes your call again. If the internal problem was rectified in the meantime, this may result in a proper response. In all other cases, such as HTTP 2xx or 4xx, the exact same response is returned as in the first call.
The following table describes possible outcomes while retrying an idempotent call:
| Result of first idempotent call | Result of retried idempotent call |
|---|---|
| Success, HTTP 2xx status code | Exact same response even if the resource has changed internally (e.g. order was captured in the meantime) |
| Business error, HTTP 4xx status code | Exact same response |
| Internal error, HTTP 5xx status code | The request is retried, as no change to any resource was done in the meantime. Instead of retrying, you can also submit a new request with a new Idempotency-Key. |
To retry an idempotent call, you must send the exact same request again. If you change the request body or any of the request parameters, the Payment API will reject your call with HTTP status code 409 Conflict.
If you retry an idempotent request while another retry is still running, your request is paused internally till the other request is completed.