Introduction

To ensure safe retries and prevent duplicate operations, REST 2.0 supports idempotency keys provided by merchants in the request header.

Using the Idempotency-key Header in an API Request

A merchant can include an Idempotency-key header in an API request. If the same key is used in multiple requests within a fifteen-minute TTL (time-to-live) window, REST 2.0 returns the same response as the original request. This mechanism helps avoid unintended side effects from repeated requests due to network issues or client retries.

Example Header

POST /paymentsIdempotency-Key: 123e4567-e89b-12d3-a456-426614174000

TTL Duration

The cached response associated with an idempotency key is retained for fifteen minutes. After the TTL expires, a new request with the same key is treated as a new operation.

Behavior After TTL Expiry

If a merchant sends a request with an idempotency key after the TTL has expired, REST 2.0 does the following:

• Does not find a cached response associated with the key.
• Processes the request again, potentially creating a new resource or triggering a new action.
• Generates a new response and stores it under the same idempotency key.
• Resets the TTL countdown thus ensuring that idempotency only applies within the defined TTL window. If expired, the key no longer guarantees repeatable results.