Idempotent requests

To prevent certain operations from accidentally being performed twice, our API supports idempotent requests. If you attempt an operation twice or more, only the first attempt will be processed.

To perform an idempotent request, send the request with HTTP header X-GCS-Idempotence-Key. All requests with the same key will be considered attempts for the same request. It is therefore important that you use unique keys, for example UUIDs. These keys are stored for a period of 24 hours.

If a second attempt is sent with the same key, there are two possible outcomes:

• If the first request has finished, the same response is sent. However, some information in this response may be updated; for example, the current status of a payment.
• If the first request has not finished yet, a response with HTTP response code 409 (Conflict) is sent instead. You should be prepared to handle this case.

To distinguish the first attempt from subsequent attempts with the same key, responses for all subsequent requests all include HTTP header X-GCS-Idempotence-Request-Timestamp, with as its value the timestamp of the first request, as the number of milliseconds since January 1^st 1970 00:00:00 UTC.

The following methods currently support idempotent requests:

• Create payment
• Create refund
• Create payout
• Create dispute