> 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/hou-duan-api-ji-cheng/direct-card-api-ji-cheng/huo-qu-kou-kuan-zhuang-tai-bian-geng-tong-zhi.md).

# 获取扣款状态变更通知

Coda 将通过服务器间通知功能，实时更新您关于支付状态的最新信息。根据交易的进展情况，您可能会收到一条或多条通知，每条通知均反映当前支付的最新状态。

## **前置条件**

已配置交易完成通知的回调 URL。

## **支付通知**

您将会收到以下支付状态的通知：

* Authorize（已授权）
* Captured（已扣款）
* Succeed（成功）
* Failed（失败）

#### **当前环境可用性**

| 环境   | 是否可用 |
| ---- | ---- |
| 沙盒环境 | 是    |
| 正式环境 | 是    |

### **通知参数说明**

| 参数名称 | 数据类型    | 描述          |
| ---- | ------- | ----------- |
| id   | String  | 通知事件的唯一标识符  |
| data | JSON 对象 | 包含扣款信息的对象数据 |

#### **Headers**

| 键值             | 描述                                                   |
| -------------- | ---------------------------------------------------- |
| x-signature    | 由 requestTime 和 requestBody 生成的签名，使用 HMAC512 算法进行加密。 |
| x-request-time | 请求创建时的 Unix 时间戳。                                     |

**步骤：**

1. 将下列值以字符串形式附加到请求体上，格式如下：*“{requestTime}.{requestBody}”。例如：*

```
// Java
RequestTime = 1700486578888
RequestBody = {"type":"charge.status.succeeded","data":{"id":"evt_sg18c678ba5af0019"}}
String message =
"1700486578888.{"type":"charge.status.succeeded","data":{"id":"evt_sg18c678ba5af0019"}}"
```

2. 使用您的签名密钥作为密钥，计算字符串的 HMAC-SHA512 哈希值。签名密钥是为您的 Webhook 端点配置的预共享密钥。HMAC-SHA512 算法将返回一个字节数组值。

*例子：*

```
// Java
SigningSecret = "BbCVjTu59yVUMMon8mgN9C37piCGfijN"
```

3. 将字节数组值转换为十六进制字符串。结果类似于：

“a0c2d905877e9282a3954743f918f98f991c144020c535458c84767b6e146cf8 cad4433accc2047258f6d5c4be07264596cfc58cfeea9e8551090f26e828e6bd“

**验证签名**

1. 从 webhook 请求中提取 X-Request-Time 和 X-Signature 标头
2. 获取原始请求体字符串（未经任何解析）
3. 按照上述步骤 1-3 生成预​​期签名。
4. 使用恒定时间比较算法，将生成的签名与 X-Signature 标头值进行比较。
5. 验证 X-Request-Time 是否在可接受的时间范围内（例如，最近 5 分钟内），以防止重放攻击。

#### **data** 该字段包含一个对象，结构与通过 “Get Charge Data” 接口返回的 charge 对象相似。

以下是需重点关注的字段：

<table><thead><tr><th width="196.78033447265625">参数名称</th><th width="131.38720703125">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>扣款的唯一标识符</td></tr><tr><td>created_at</td><td>Instant</td><td>扣款创建的时间戳</td></tr><tr><td>status_code</td><td>String</td><td>当前支付状态，详见 <a data-mention href="/pages/k8NV4oKrszJRAQq4wSrY">/pages/k8NV4oKrszJRAQq4wSrY</a></td></tr><tr><td>error_code</td><td>String</td><td>扣款失败时的错误码，详见 <a data-mention href="/pages/aXsbN2QLD1XPWPcxDIW8">/pages/aXsbN2QLD1XPWPcxDIW8</a></td></tr><tr><td>error_description</td><td>String</td><td>扣款失败时的错误描述，详见 <a data-mention href="/pages/aXsbN2QLD1XPWPcxDIW8">/pages/aXsbN2QLD1XPWPcxDIW8</a></td></tr><tr><td>partner_reference</td><td>String</td><td>商户提供的用于识别该笔支付的唯一标识符</td></tr></tbody></table>

## **扣款确认通知（Capture Approval Notification）**

#### **当前环境可用性**

| 环境   | 是否可用 |
| ---- | ---- |
| 沙盒环境 | 是    |
| 正式环境 | 是    |

Codapay 会在支付授权成功后，通过服务器对服务器（Server-to-Server）的 REST 请求联系您，以确认接下来应执行的操作。

### **扣款确认参数说明（Capture Parameters）**

Capture 请求的结构与[支付通知](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/hou-duan-api-ji-cheng/direct-card-api-ji-cheng/huo-qu-kou-kuan-zhuang-tai-bian-geng-tong-zhi.md)类似，不同之处在于它不包含在 `data` 对象中。

以下是需重点关注的字段：

<table><thead><tr><th width="167.967041015625">参数名称</th><th width="106.875">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>扣款的唯一标识符</td></tr><tr><td>created_at</td><td>Instant</td><td>扣款创建的时间戳</td></tr><tr><td>status_code</td><td>String</td><td>当前支付状态（您应预期收到的状态为 <code>waiting_capture_approval</code>）</td></tr><tr><td>partner_reference</td><td>String</td><td>商户提供的用于识别该笔支付的唯一标识符</td></tr></tbody></table>

#### **如何启用扣款确认通知（Capture Approval Notification）**

要启用该功能，您需在[提交扣款请求](/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/hou-duan-api-ji-cheng/direct-card-api-ji-cheng/ti-jiao-kou-kuan-qing-qiu.md)（Submit Charge）时传入 `pre_capture_ack_url` 参数。\
若未传入该参数，所有已授权的扣款将自动执行扣款操作（auto capture）。

流程如下：

* 一旦发卡银行成功授权付款，若 Coda 收到 `pre_capture_ack_url`，将向该地址发送一条 REST 请求通知。
* 请求内容中将包含一个 `charge` 对象，其 `status_code` 为：`waiting_capture_approval`。
* 这表示授权已完成，Coda 正等待您的确认以继续扣款。

#### **您应如何回应**

在用户确认付款并获得发卡银行授权后，您可以选择是否批准该笔交易。

若您希望具备以下决策能力：

(a) 继续扣款（确认扣款）

(b) 取消已授权的交易

则必须对扣款确认通知（capture request notification）进行响应，告知 Codapay 是否可以继续扣款操作。

**响应格式如下：**

<table><thead><tr><th width="164.10418701171875">参数名称</th><th width="104.35943603515625">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>charge_id</td><td>String</td><td>扣款的唯一标识符</td></tr><tr><td>perform_action</td><td>String</td><td><p>表示是否批准扣款请求，需通过返回 <code>confirm_capture</code> 或 <code>decline_capture</code> 来指示：</p><ul><li><code>confirm_capture</code>：确认执行扣款</li><li><code>decline_capture</code>：拒绝执行扣款</li></ul></td></tr></tbody></table>

## **重试策略（Retry Policy）**

**当前环境可用性：**

| 环境   | 是否可用 |
| ---- | ---- |
| 沙盒环境 | 即将开放 |
| 正式环境 | 即将开放 |

**重试规则说明：**

请注意，如果我们未收到捕获通知的回复，我们将间隔几分钟重新发送捕获请求，最多重试 3 次。如果重试仍不成功，我们将视为商户拒绝此次扣款，不再执行资金扣款操作。

对于所有通知请求，如我们的 **POST 请求未收到 2XX 响应**，我们将采用指数级重试策略，并最多重试三次。

**初次失败后的重试计划：**

* 首次重试：1 分钟
* 第二次重试：5 分钟
* 第三次重试：30 分钟

若 3 次重试均失败：

* 我们将 **不再处理该事件**
* 对于 **扣款确认请求**，我们将视为商户已拒绝扣款
* 扣款将被取消，并发送一条状态变更通知，**支付状态为 canceled**


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/hou-duan-api-ji-cheng/direct-card-api-ji-cheng/huo-qu-kou-kuan-zhuang-tai-bian-geng-tong-zhi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.