Idempotency overview

Amazon Pay enforces idempotency for POST requests, so that the requests can be retried safely. This is useful when an API request is disrupted during transit.

Amazon Pay saves the response to the first request made with an idempotency key. Subsequent requests using the same key will return the saved result. If you change any values in the subsequent request, instead of returning the saved result, the response will be a DuplicateIdempotencyKey error.

Note: idempotency keys are unique to each Amazon Pay merchant account and they are stored indefinitely. This means that the same key can be used for different accounts.

Idempotency header

To make an indempotent request, set the x-amz-pay-idempotency-key request header. The key is a unique value that will be used to recognize subsequent retries of the same request. We recommend using V4 UUIDs to avoid collisions.

The idempotency key can have a maximum of 32 characters, using only these character options:

  1. Lower case letters: a-z
  2. Upper case letters: A-Z
  3. Number: 0-9
  4. Dash (-)
  5. Underscore (_)


-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"

Note: we do NOT recommend setting the x-amz-pay-idempotency-key header for GET, PATCH and DELETE requests, as they have no effect, since those requests are idempotent by definition.