Introduction
The Mangopay API supports idempotency for all POST calls, which means that a request can be retried several times without performing the same operation. This avoids unwanted duplicated calls that can have detrimental consequences, for example in case of a network error. You can make calls idempotent by including theIdempotency-Key
header in your request. The unique value that you generate for each idempotency key allows Mangopay to recognize subsequent retries of the same request.
The idempotency key must contain between 16 and 36 alphanumeric characters or dashes (-).
Best practice – Use UUIDWe strongly recommend generating a universally unique identifier (UUID) as your idempotency key.
Note – Idempotency key required for some featuresThe idempotency key is required to accept two subsequent pay-ins of the same amount within 24 hours if they rely on the same preauthorization (including for multi-capture).
Benefits
By using an idempotency key, you’ll be able to avoid duplicated calls and retrieve missed API responses.Blocking duplicated calls
If you use the same idempotency key within 24 hours Mangopay will block all but the first request. This means you are able to rerun the same request knowing that it is only going to be processed once. When an idempotent request is blocked, the 409 HTTP response code is returned.409 response example
Retrieving missed API responses
In the event of a timeout or a loss of connection, the idempotency key can be used to retrieve the missed API responses using the GET View an API Response endpoint.Caution – Limited to within 24 hoursThis only works within 24 hours after the initial use of the idempotency key.