欺诈和拒付通知

本参考资料描述了 Coda 发送的 webhook 通知，以便让您的后端了解拒付生命周期的变化以及交易中的早期欺诈警告。

注意：要启用拒付和欺诈更新功能，您的账户需要启用 POST 通知。请联系您的 Codapay 客户经理启用此功能。

概述

Codapay 使用 webhook 来通知您的“完整通知 URL”，每当拒付事件在其生命周期中进展到一定阶段，或者您的某笔交易收到早期欺诈警告时，都会收到通知。

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

事件类型

拒付事件

对于拒付生命周期事件，您的端点应准备好处理以下eventType值：

chargeback_created	已对某笔交易提出拒付申请
dispute_sent	拒付事件已升级，争议已提交至支付网关。
dispute_lost	争议最终以客户胜诉告终。
dispute_won	纠纷最终以商家的胜诉告终。

欺诈事件

对于欺诈事件，您的端点应准备好处理以下eventType值：

fraud_notification	已收到一笔交易的早期欺诈预警。

通知请求体结构

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

eventType	string	所报告的具体事件类型（例如，chargeback_created）
timestamp	string	通知时间戳
data.chargebackId	string	Coda 的内部拒付标识符
data.stage	string	拒付的生命周期阶段。请参见下方的阶段值。
data.txnId	string	Coda 的内部交易 ID
data.reason	string	发卡行提供的拒付原因（例如：其他欺诈 - 卡片不在场环境）
data.outcome	string | null	争议的最终结果：胜诉、败诉或因尚未解决而无效。
data.amountValue	decimal	交易金额
data.amountCurrency	string	ISO 4217 货币代码（例如 CHF、USD）
data.orderId	string	您的订单号（如有提供）

阶段值

CHARGEBACK	已创建拒付机制
DISPUTE_SENT	争议已提交至网关
DISPUTE_LOST	争议已解决——结果：败诉
DISPUTE_WON	争议已解决——结果：胜诉
EARLY_FRAUD_WARNING	在发起拒付之前已收到欺诈信号

拒付通知示例

chargeback_created

{
  "eventType": "chargeback_created",
  "timestamp": "1773860416000",
  "data": {
    "chargebackId": "CBKJTNRS9XDNBVQ9",
    "stage": "CHARGEBACK",
    "txnId": "7677293394619242496",
    "reason": "Other Fraud-Card Absent Environment",
    "outcome": null,
    "amountValue": 100,
    "amountCurrency": "CHF",
    "orderId": "c8856951-b495-4e9b-8b48-01123cf4f5eb"
  }
}

dispute_sent

{
  "eventType": "dispute_sent",
  "timestamp": "1773860416000",
  "data": {
    "chargebackId": "CBKJTNRS9XDNBVQ9",
    "stage": "DISPUTE_SENT",
    "txnId": "7677293394619242496",
    "reason": "Other Fraud-Card Absent Environment",
    "outcome": null,
    "amountValue": 100,
    "amountCurrency": "CHF",
    "orderId": "c8856951-b495-4e9b-8b48-01123cf4f5eb"
  }
}

dispute_lost

{
  "eventType": "dispute_lost",
  "timestamp": "1773860416000",
  "data": {
    "chargebackId": "CBKJTNRS9XDNBVQ9",
    "stage": "DISPUTE_LOST",
    "txnId": "7677293394619242496",
    "reason": "Other Fraud-Card Absent Environment",
    "outcome": "LOST",
    "amountValue": 100,
    "amountCurrency": "CHF",
    "orderId": "c8856951-b495-4e9b-8b48-01123cf4f5eb"
  }
}

dispute_won

{
  "eventType": "dispute_won",
  "timestamp": "1773860416000",
  "data": {
    "chargebackId": "CBKJTNRS9XDNBVQ9",
    "stage": "DISPUTE_WON",
    "txnId": "7677293394619242496",
    "reason": "Other Fraud-Card Absent Environment",
    "outcome": "WON",
    "amountValue": 100,
    "amountCurrency": "CHF",
    "orderId": "c8856951-b495-4e9b-8b48-01123cf4f5eb"
  }
}

欺诈通知示例

fraud_notification

{
  "eventType": "fraud_notification",
  "timestamp": "1773860416000",
  "data": {
    "chargebackId": "CBKJTNRS9XDNBVQ9",
    "stage": "EARLY_FRAUD_WARNING",
    "txnId": "7677293394619242496",
    "reason": "Other Fraud-Card Absent Environment",
    "amountValue": 100,
    "amountCurrency": "CHF",
    "orderId": "c8856951-b495-4e9b-8b48-01123cf4f5eb"
  }
}

通知签名验证

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

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

工作原理

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

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

使用您的商户密钥（API key）对该字符串应用 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 次。如果所有尝试均失败，系统将向您的技术联系人发送电子邮件提醒。