Idempotency

We explain our idempotency scheme to prevent creating two or more resources for the same request.

Since an HTTP request can timeout, we need to ensure that when retrying, it is processed only once. To achieve this, in every request, we will send a header x-idempotency-key with a unique ID that you must process with an in-memory cache (e.g. Redis).

At the beginning of each transaction, you should verify whether the idempotency key we send is already in the in-memory cache, and depending on whether it is or not, you should do the following:

Idempotency header does not exist in the cache

You should store in the in-memory cache the idempotency key → order relation, with an in-progress status and a TTL of 3 minutes.

When you approve or reject the transaction, you must store the result in the cache and update the status of the idempotency key to 'completed'.

Idempotency header exists in the cache

In the case of a duplicate request, you should verify the transaction status in the cache.

• If it is in a completed state, you should respond with an HTTP 200 code and the expected body for the endpoint, completing it with the result from the cache.
• If it is in an in-progress state, you should respond with an HTTP 425 code (Too Early: RFC 8470) and the expected body for the endpoint. We will attempt to fetch the response for this request a few milliseconds later.

Ongoing Requests

If you receive a second request with the same idempotency ID and the first one is still in progress, you should respond with an http-status 425 and an empty body.