Idempotency
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 the Idempotency-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 GUID
We strongly recommend generating a globally unique identifier (GUID) as your idempotency key.
Using an idempotency key is optional; the API will function normally without it.
Note – Idempotency key required for some features
The 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.
{
"Message": "A resource has already been created with this Idempotency Key",
"Type": "idempotent_creation_conflict",
"Id": "bf6cce22-4c12-454f-ac05-ca20c8683735#1452723935",
"Date": 1452723944,
"errors": null
}
Idempotent requests are blocked regardless of the HTTP response code of the first API call. This means you can’t re-use an idempotency key that was used on a failed call.
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 hours
This only works within 24 hours after the initial use of the idempotency key.
Was this page helpful?