> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Idempotent Requests

> Use the X-Idempotency-Key header to retry a Payrails API request safely, without creating duplicate records or repeating an update.

Our API offers idempotency features to ensure safe retries of requests without unintentional duplicate operations. Integrating an idempotency key can prove invaluable if you're working on actions like record creation or updates. This key allows you to re-initiate a request, especially in situations like connectivity disruptions, ensuring no unwanted duplications or repeated updates.

## Making an idempotent request

For an idempotent request, include an extra header: `X-Idempotency-Key: <key>`

Upon receiving a request with a unique idempotency key, our system commits to memory the status code and the response body. This holds irrespective of whether the request was a success or a failure. Any subsequent requests with the same key will fetch identical responses, preserving this consistency even in case of server errors.

## What is an idempotency key?

This key is a unique marker, generated on the client side, which our server leans on to detect and avert potential repetitions stemming from retried requests. Key aspects include:

* **Generation:** While the method for generating unique keys rests with you, we accept only UUIDs as idempotency keys. This ensures a low likelihood of overlapping keys.
* **Storage considerations:** It's important to note that results are only stored if an API endpoint has started processing. Should the incoming parameters fail validation, or if another conflicting request is being processed simultaneously, no idempotent result will be stored. In such scenarios, it's safe to reinitiate these requests.

## Idempotency in different HTTP Methods

* **POST, PUT, PATCH:** All requests must be paired with idempotency keys to ensure safe retries.
* **GET:** Attaching idempotency keys to GET requests is unnecessary and should be refrained from, given that it is inherently idempotent.
* **DELETE:** We require an idempotency key in soft-delete operations. However, hard-delete operations cannot be idempotent because the previous record will not exist on subsequent calls.


## Related topics

- [Detach a Tag from a Dispute](/reference/detachdisputetag.md)
- [Event-Driven Auto-Capture](/docs/orchestration/workflow-studio/examples/event-driven-auto-capture.md)
- [Track and reconcile](/docs/orchestration/payment-links/track-and-reconcile.md)