异步回调

1. 接口说明

本接口为我方系统向贵方系统推送业务事件的异步回调接口，贵方需提供可公网访问的回调地址，并确保能正常接收、解析我方推送的回调报文，且完成签名验证。

2. 回调方式

请求方式：POST

数据格式：JSON

字符编码：UTF-8

超时时间：3秒

若贵方未在超时时间内返回成功响应，我方将进行重试。
重试规则：共3次，间隔5分钟。

请求头

请求头字段	类型	必填	说明
X-Signature	String	是	回调报文签名串（RSA-SHA256 Base64编码）
X-Timestamp	String	是	时间戳（毫秒级），格式：`1735689600000`

3. 回调报文整体结构

3.1 请求体结构

字段名	类型	必填	说明
notifyType	String	是	回调类型，枚举值见下表
data	Object	是	回调业务数据，不同notifyType对应不同结构

3.2 notifyType完整枚举值

枚举值	中文描述
CARD_AUTH	卡片授权订单回调
CARD_AUTH_FAIL	卡片VCC授权订单失败回调
CARD_AUTH_CANCEL	卡片授权订单撤销回调
CARD_AUTH_DISPUTE	卡片授权订单争议回调
CARD_SETTLEMENT	卡片授权订单结算回调
CARD_SETTLE_SUPPLEMENT	卡片结算补扣回调
CARD_SETTLE_REFUND	卡片结算退款回调
CARD_REFUND	卡片授权订单退款回调
CARD_CANCEL	卡片撤销回调
CARD_FREEZE	卡片冻结回调
CARD_UNFREEZE	卡片解冻回调
CARD_WALLET_AUDIT	卡钱包审核回调
CARD_WALLET_RECHARGE	卡钱包充值回调
CARD_WALLET_WITHDRAW	卡钱包提现回调
MERCHANT_ACCOUNT_AUDIT	商户账户审核回调

4. 签名验证规则

4.1 签名生成逻辑（服务端实现）

待签名字符串：请求体完整JSON字符串（无缩进、无多余空格，格式为{"notifyType":"xxx","data":{...}}）

签名算法：SHA256withRSA（RSA非对称加密，基于SHA256哈希算法）

签名结果：对JSON字符串签名得到字节数组，经Base64编码后作为X-Signature请求头的值

时间戳：X-Timestamp为签名时的系统当前时间（毫秒级），仅用于防重放，不参与签名计算

4.2 验签逻辑（客户端实现）

校验时间戳有效性：判断当前时间与X-Timestamp的差值是否在5分钟内，防止重放攻击

获取待验签数据：接收到的原始请求体JSON字符串（需保持和我方发送的一致，无缩进、无多余空格）

验签公钥：使用我方提供的RSA公钥（X509格式，Base64编码）

验签算法：通过SHA256withRSA算法验证X-Signature是否与待验签数据匹配

4.3 验签代码示例（Java版）

5.回调示例

5.1 请求头示例

X-Signature: 8e7f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f
X-Timestamp: 1735689600000

5.2 请求体示例

{
  "notifyType": "CARD_AUTH",
  "data": {
    "orderId": "AUTH20260131001",
    "cardNo": "6226********1234",
    "authAmount": 100.00,
    "authTime": "2026-01-31 15:30:20"
  }
}

6. 响应要求

贵方接收到回调报文并处理完成后，需返回如下格式的成功响应（HTTP状态码200），否则我方将判定为回调失败并触发重试：

{
  "code": 0,
  "msg": "success"
}

响应说明：

code：固定0表示处理成功，非0表示处理失败
msg：成功时固定为success，失败时可填写失败原因，便于我方排查

7. 补充说明

签名仅针对原始请求体JSON字符串计算，X-Timestamp只做超时校验，不参与签名拼接

客户端接收时必须使用原始请求体字符串验签，禁止格式化、增删空格、换行后再验签

我方RSA公钥由API申请通过后邮件发送，公钥格式为X509标准Base64编码，无额外头尾注释行

1. 接口说明#

2. 回调方式#

请求头#

3. 回调报文整体结构#

3.1 请求体结构#

3.2 notifyType完整枚举值#

4. 签名验证规则#

4.1 签名生成逻辑（服务端实现）#

4.2 验签逻辑（客户端实现）#

4.3 验签代码示例（Java版）#

5.回调示例#

5.1 请求头示例#

5.2 请求体示例#

6. 响应要求#

7. 补充说明#