身份验证和捕获通知

本文档介绍了专门用于授权和捕获分离的 Webhook 通知。这些通知可确保您的后端在交易经历授权、捕获或取消阶段时保持同步。

注意：授权和捕获分离需要启用 POST 通知。您的账户必须同时启用这两项功能。请联系您的 Codapay 客户经理启用它们。

概述

Codapay 使用 webhook 在交易达到最终状态或授权和捕获流程中的关键里程碑时通知您的“完成通知 URL”。

请确保已在发布商门户中配置“完整通知 URL”。有关详细说明，请参阅“设置付款”指南。

事件类型

为了实现授权和捕获的分离，您的端点应准备好处理以下eventType值：

authorization_successful	用户已成功授权交易（例如，3DS）。
authorization_failed	用户授权失败或银行拒绝了请求
cancelled	您已决定在成功授权后、捕获前取消交易。
capture_initiated	系统已开始收取授权资金。
capture_successful	款项已成功扣款。交易完成。
capture_failed	授权成功后，捕获过程失败。

通知请求体结构

通知以请求的形式发送，POST请求体为 JSON 格式。

eventType	string	所报告的具体事件类型（例如，capture_successful）
timestamp	string	通知时间戳
data.txnId	string	Coda 生成的唯一交易 ID
data.orderId	string	订单的商家端唯一标识符
data.amountValue	decimal	以结算货币向用户收取的最终金额。
data.amountCurrency	string	收费金额的 ISO 4217 货币代码（例如，MYR）
data.originalValue	decimal	商品原价（未进行任何货币转换）
data.originalCurrency	string	原价的 ISO 4217 货币代码
data.resultCode	integer	交易状态码。0如果成功，则表示交易成功；其他值表示交易失败。
data.resultDesc	string	对交易结果进行易于理解的描述。
data.shopper	object	包含购物者详细信息的对象，例如 ID、电子邮件或合作伙伴特定标识符。
data.paymentMethod	object	有关所用支付工具的信息（例如，卡类型、后四位数字）。
data.transactionData	object	一个灵活的对象，包含特定于交易或支付渠道的补充元数据。

成功通知示例

以下示例显示了一条CAPTURE_SUCCESSFUL通知，表明资金已成功捕获：

{
  "eventType": "capture_successful",
  "timestamp": "1776084951007",
  "data": {
    "txnId": "7760845022800001729",
    "orderId": "12321312321314",
    "amountValue": 1,
    "amountCurrency": "EUR",
    "originalValue": 1,
    "originalCurrency": "EUR",
    "resultCode": 0,
    "shopper": {},
    "paymentMethod": {},
    "transactionData": {}
  }
}

通知失败示例

当发生诸如authorization_failed、capture_failed或cancelledresultCode之类的事件时，将包含一个非零值。

{
  "eventType": "cancelled",
  "timestamp": "1776085975305",
  "data": {
    "txnId": "7760859208170001746",
    "orderId": "12321312321314",
    "amountValue": 1,
    "amountCurrency": "EUR",
    "originalValue": 1,
    "originalCurrency": "EUR",
    "resultCode": 221,
    "shopper": {},
    "paymentMethod": {},
    "transactionData": {}
  }
}

您可以在这里找到完整的错误代码及其含义列表。

通知签名验证

每个 POST 通知都包含两个标头，使您可以验证请求是否来自 Codapay 且未被篡改：

X-Request-Time	请求的时间戳，以时间戳毫秒表示（数字字符串）
X-Signature	Codapay 使用您的商户密钥计算的 HMAC-SHA512 十六进制摘要

工作原理

Codapay 和您的服务器都同意使用同一个 UTF-8 字符串进行签名：

X-Request-Time + "." + raw POST body (UTF-8)

使用您的商户密钥对该字符串应用 HMAC-SHA512 算法，生成128 个字符的小写十六进制摘要。

Codapay 会将此摘要放在X-Signature邮件头中发送。您的服务器必须重新计算相同的十六进制摘要，并将其与接收到的值进行比较。

验证步骤

1. 读取传入请求中的请求头X-Request-Time和响应头。X-Signature

2. 读取请求的原始字节。

3. 构建签名字符串：（requestTime + "." + body解释为 UTF-8）。

4. 计算预期签名：HMAC-SHA512(secretKey, signedString)→ 小写十六进制。

5. 使用恒定时间expectedHex比较与头部值进行比较，以防止计时攻击。比较不区分大小写。X-Signature

如果值不匹配，则拒绝请求。

示例 — Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class SignatureValidator {

    private static final String HMAC_SHA512 = "HmacSHA512";

    public static boolean validate(String secretKey, String requestTime, byte[] body, String xSignature) {
        String bodyUtf8 = new String(body, StandardCharsets.UTF_8);
        String text = requestTime + "." + bodyUtf8;
        String expected = hmacSha512Hex(secretKey, text);
        return MessageDigest.isEqual(
            expected.toLowerCase().getBytes(),
            xSignature.toLowerCase().getBytes()
        );
    }

    private static String hmacSha512Hex(String secretKey, String text) {
        try {
            Mac mac = Mac.getInstance(HMAC_SHA512);
            mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA512));
            byte[] raw = mac.doFinal(text.getBytes(StandardCharsets.UTF_8));
            return HEX.formatHex(raw);
        } catch (Exception e) {
            throw new IllegalStateException("HMAC-SHA512 not available", e);
        }
    }
}

回复通知

为确认收到通知，您的服务器必须响应一个包含200 OK以下 JSON 正文的响应：

{
  "ResultCode": 0
}

重试策略：如果未收到有效响应，Codapay 将每隔 5 分钟重新发送一次通知，共发送 3 次。如果所有尝试均失败，系统将向您的技术联系人发送电子邮件提醒。