第三方回调机制

PayAll 平台会在特定事件发生时，主动向商户配置的回调地址推送通知。

回调配置

在申请商户账号时，需要提供回调地址（callback_url）。PayAll 会在以下场景触发回调：

• 开卡成功/失败

• 卡片充值成功/失败

• 卡片提现成功/失败

• 卡片交易

• 其他业务状态变更

回调请求格式

PayAll 会向商户的回调地址发送 POST 请求，请求格式如下：

请求头：

• Content-Type: application/json

• X-Event-Type: {事件类型} - 标识回调事件类型

• x-api-key: {API密钥} - 仅对特定商户（如 cat_wallet）需要

请求体： 回调数据以 JSON 格式发送，包含以下字段：

字段名	类型	必填	说明
event_type	string	是	事件类型（见下方事件类型列表）
user_id	integer	是	PayAll 用户ID
timestamp	integer	是	时间戳（秒级）
order_id	string	否	订单ID（第三方订单号）
user_name	string	否	第三方用户名
amount	string	否	金额（根据事件类型可能包含）
currency	string	否	币种（根据事件类型可能包含）
card_binding_id	integer	否	卡片绑定ID（卡片相关事件包含）
sign	string	否	RSA 签名（如果商户配置了私钥）

回调数据示例：

{
  "event_type": "card.issue.success",
  "user_id": 12345,
  "timestamp": 1698203395,
  "order_id": "open_card_12345_39_abc123",
  "user_name": "[email protected]",
  "card_binding_id": 12345,
  "amount": "30.00",
  "currency": "USD",
  "sign": "AJdzqyM5SSaewz7TF4M6cYK3NyVzz8tTjNpiGrlt3G+9Whncj2r8zMwNSkjyrvulSwZSIPFLCudIYiMI0BGSAGkLmVIwlZgZBvIRZwWlg0tt6hBvvEedRA1gCIVN4SSm4IKmnoxodOoRLL2MNrrTr7QvcUWZoSyElaCO3JL1cqwbReiAkIsy8kh0JQgZVhKX9fGlP07X3eXwdORr86DerBO/2Mv44XlJ8gTHwut9/pMkgveEh1pTKK0iFMIN00TA9wceRUZuuS7QegtK4hTLqoMz3m1saOYLNdTI7J9Qj1Wjf5SzGj5KIUkdqPK5GCAtzghRRWh4roYCiB0PE65crA=="
}

支持的事件类型

PayAll 支持以下事件类型的回调通知：

开卡相关

• card.issue.success - 开卡成功

卡片充值相关

• card.topup.success - 卡片充值成功

回调签名验证

如果商户在配置时提供了私钥，PayAll 会对回调数据进行签名。商户可以使用公钥验证签名：

1. 从回调数据中提取 sign 字段（Base64 编码的签名）

2. 将除 sign 外的所有字段按字典序排序

3. 将排序后的数据转换为 JSON 字符串（使用紧凑格式，无空格）

4. 使用 PayAll 提供的公钥验证签名（SHA256withRSA）

签名验证示例（伪代码）：

# 1. 提取签名
sign = callback_data.pop('sign')
sign_bytes = base64_decode(sign)

# 2. 准备验证数据
sorted_data = dict(sorted(callback_data.items()))
data_str = json.dumps(sorted_data, separators=(',', ':'))

# 3. 验证签名
is_valid = rsa_verify(data_str, sign_bytes, public_key)

响应要求

商户收到回调后，应该：

1. 验证签名（如果回调数据包含 sign 字段）

2. 验证时间戳（建议验证 timestamp 是否在合理范围内，防止重放攻击）

3. 处理业务逻辑（根据 event_type 和 order_id 更新本地订单状态）

4. 返回响应：

   • 成功处理：返回 HTTP 200 状态码，响应体可以是任意内容（建议返回 JSON 格式的成功响应）

   • 处理失败：返回 HTTP 4xx/5xx 状态码，PayAll 可能会重试

成功响应示例：

{
  "code": 200,
  "status": "true",
  "message": "Callback processed successfully"
}

重试机制

• PayAll 会在回调失败时进行重试

• 重试间隔和次数由 PayAll 内部策略决定

• 商户应该保证回调接口的幂等性（相同 order_id 的重复回调应该返回相同结果）

• 建议商户记录所有回调请求，避免重复处理

安全建议

1. 使用 HTTPS：回调地址必须使用 HTTPS 协议

2. 验证签名：始终验证回调数据的签名，确保数据来源可靠

3. 验证时间戳：检查 timestamp 字段，拒绝过期的回调请求

4. 幂等性处理：根据 order_id 实现幂等性，避免重复处理

5. 日志记录：记录所有回调请求，便于问题排查

回调调试

商户可以通过以下方式调试回调：

1. 使用 /getRecordDetail 接口查询订单状态，验证回调是否触发

2. 检查回调记录（如果 PayAll 提供回调记录查询接口）

3. 查看商户后台的回调日志