Idempotency

Idempotency is an important property of our API that prevents you from changing a record if you make the same request multiple times. If you send the same request, we return the same response that we returned for the initial request. We do not update the record.

Example use case for idempotency

1. You send a request to take a payment of $20 from a customer's account.
2. Our gateway successfully processes the payment and takes $20 from the account.
3. Our gateway sends you a response to notify you of the successful transaction.
4. There is a network error, and the response doesn't reach you.
5. You resend the request to process the payment.
6. Our gateway detects that the request is the same as the initial request and resends the initial response. Our gateway does not process an additional $20 payment.

We follow RESTful standards when designing our API, which means that all GET requests, PUT requests, and DELETE requests are idempotent. We have also implemented additional features to guarantee that POST requests are idempotent.

Idempotent POST requests

To implement idempotency on POST requests, you must include an Idempotency-Key header with each request. If your POST request does not include an Idempotency-Key header, we return a 400 "Bad Request" error. To support idempotent POST requests, we save the following information for seven days:

• The Idempotency-Key value, URI, and body of your initial request
• The response body and status code that we returned for your initial request

How we process POST requests

When we receive a POST request, we verify that it is unique by checking the combination of Idempotency-Key value, URI, and request body. Depending on the results of our verification, we complete one of the following actions:

• We have not processed the request previously: we process the request.
• We have processed the request previously: we return the saved response.
• The Idempotency-Key value is saved with a different URI, response body, or both: we return a 409 "Conflict" error.