> 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/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/xun-huan-fu-kuan-ji-jiang-tui-chu/shi-yong-token-hua-zhi-fu-fang-shi-fa-qi-kou-kuan/mi-deng-xing-qing-qiu.md).

# 幂等性请求

Token Charge（令牌扣款）支持幂等性，因此在超时或网络连接错误后您可以重试扣款，而不会对银行卡重复扣款。

在每次逻辑扣款尝试中发送唯一的 Idempotency-Key（每个预期的账单使用一个 Key，而不是每次 HTTP 重试使用一个 Key）。如果首次 HTTP 调用超时，请使用相同的 Key 重复发送相同的 JSON 请求体。Coda 将返回原始处理结果，而不是创建第二次扣款。

Init（初始化）、Inquiry（查询）以及 Webhook 不在此请求头的作用范围内。

#### 安全重试的工作原理

```mermaid
sequenceDiagram
  participant 商家后端
  participant Codapay API
  participant 支付服务商

商家后端 ->> Codapay API: POST /token/charge <br>Idempotency-Key K1 载荷 A
Codapay API ->> Codapay API: 创建支付交易 txnId=123
Codapay API ->> 支付服务商: 发起支付
Codapay API -->> 商家后端: 超时或连接错误

note over 商家后端,Codapay API: 若 iat/exp 过期请重新签名 JWT<br>切勿修改请求体或 Key

商家后端 ->> Codapay API: POST /token/charge <br>Idempotency-Key K1 载荷 A
Codapay API -->> 商家后端: 重放原始结果<br>相同的 txnId(123)，未产生二次扣款
```

#### 生成 Key

Key 由您生成。Coda 仅使用它来识别该次尝试的重试操作。

| **推荐做法 (Do)**                                   | **禁止做法 (Do not)**                            |
| ----------------------------------------------- | -------------------------------------------- |
| 使用 UUID v4（或其他高熵随机字符串）                          | 在不同的计费周期、用户或金额之间复用 Key                       |
| 为每次新的逻辑扣款创建新的 Key                               | 使用电子邮箱、买家 ID、卡号 (PAN) 或其他个人数据作为 Key          |
| 持久化保存该 Key 与对应尝试的关联，直到获取确定结果（HTTP 响应、完整通知或查询结果） | 如果您可能在 24 小时后复用 orderId，切勿仅基于 orderId 生成 Key |

作用域： 在您的账户中，一个 Idempotency-Key 仅映射一次 Token Charge 尝试。如果出现冲突，应视其为 Key 生成逻辑中的 Bug。

{% hint style="warning" %}
请在 24 小时内停止重试。Key 将至少保留 24 小时。在 Coda 清理该 Key 后，再次使用该 Key 将被视为全新的扣款请求。请勿跨越该时间限制重复使用同一个 Key 进行重试；只有当您确需发起新的扣款时，才应使用新的 Key 开启新的尝试。
{% 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/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/xun-huan-fu-kuan-ji-jiang-tui-chu/shi-yong-token-hua-zhi-fu-fang-shi-fa-qi-kou-kuan/mi-deng-xing-qing-qiu.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.