获取扣款状态变更通知

在用户完成支付流程时，实时接收交易状态变更通知。

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"}}"

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

例子：

// Java
SigningSecret = "BbCVjTu59yVUMMon8mgN9C37piCGfijN"

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

“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 对象相似。

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

参数名称	数据类型	描述
id	String	扣款的唯一标识符
created_at	Instant	扣款创建的时间戳
status_code	String	当前支付状态，详见 Direct Card API 扣款状态说明
error_code	String	扣款失败时的错误码，详见 Direct Card API 扣款错误码
error_description	String	扣款失败时的错误描述，详见 Direct Card API 扣款错误码
partner_reference	String	商户提供的用于识别该笔支付的唯一标识符

扣款确认通知（Capture Approval Notification）

当前环境可用性

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

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

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

Capture 请求的结构与支付通知类似，不同之处在于它不包含在 data 对象中。

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

参数名称	数据类型	描述
id	String	扣款的唯一标识符
created_at	Instant	扣款创建的时间戳
status_code	String	当前支付状态（您应预期收到的状态为 waiting_capture_approval）
partner_reference	String	商户提供的用于识别该笔支付的唯一标识符

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

要启用该功能，您需在提交扣款请求（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 是否可以继续扣款操作。

响应格式如下：

参数名称	数据类型	描述
charge_id	String	扣款的唯一标识符
perform_action	String	表示是否批准扣款请求，需通过返回 confirm_capture 或 decline_capture 来指示： confirm_capture：确认执行扣款 decline_capture：拒绝执行扣款

重试策略（Retry Policy）

当前环境可用性：

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

重试规则说明：

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

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

初次失败后的重试计划：

• 首次重试：1 分钟

• 第二次重试：5 分钟

• 第三次重试：30 分钟

若 3 次重试均失败：

• 我们将 不再处理该事件

• 对于 扣款确认请求，我们将视为商户已拒绝扣款

• 扣款将被取消，并发送一条状态变更通知，支付状态为 canceled