> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/codapay/recurring-payments/submit-charge-with-tokenized-payment-method/idempotent-requests.md).

# Idempotent requests

Token Charge supports idempotency so you can retry a charge after a timeout or connection error **without charging the card twice**.

Send a unique `Idempotency-Key` on every **logical** charge attempt (one key per intended bill, not one key per HTTP try). If the first HTTP call times out, repeat the **same JSON body** with the **same key**. Coda returns the original outcome instead of creating a second charge.

Init, Inquiry, and webhooks are not covered by this header.

#### How a safe retry works

```mermaid
sequenceDiagram
  participant Merchant Backend
  participant Codapay API
  participant Payment Provider
  
  Merchant Backend ->> Codapay API: POST /token/charge <br>Idempotency-Key K1 payload A
  Codapay API ->> Codapay API: create payment txnId=123
  Codapay API ->> Payment Provider: Payment
  Codapay API -->> Merchant Backend: timeout or connection error
  note over Merchant Backend,Codapay API: Resign JWT if iat/exp expired<br>Do not change body or key
  Merchant Backend ->> Codapay API: POST /token/charge <br>Idempotency-Key K1 payload A
  Codapay API -->> Merchant Backend: Original result replayed<br>Same txnId(123) without second charge
  
```

#### Generate the key

You generate the key. Coda uses it only to recognise retries of that attempt.

<table><thead><tr><th width="379">Do</th><th>Do not</th></tr></thead><tbody><tr><td>Use a <strong>UUID v4</strong> (or another high-entropy random string)</td><td>Reuse a key across billing cycles, users, or amounts</td></tr><tr><td>Create a <strong>new</strong> key for every new logical charge</td><td>Use email, shopper id, PAN, or other personal data as the key</td></tr><tr><td>Persist the key with the attempt until you have a durable result (HTTP response, complete notification, or Inquiry)</td><td>Derive the key only from <code>orderId</code> if you might reuse that <code>orderId</code> after 24 hours</td></tr></tbody></table>

Scope: one `Idempotency-Key` maps to one Token Charge attempt for your account. Treat collisions as a bug in key generation.

{% hint style="warning" %}
**Stop before 24 hours.** Keys are retained for **at least 24 hours**. After Coda prunes the key, a reuse is treated as a **new** charge. Do not retry the same key across that boundary; start a new attempt with a new key only when you intend a new charge.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coda.co/codapay/recurring-payments/submit-charge-with-tokenized-payment-method/idempotent-requests.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.