​
1. WaaS回调处理流程

回调请求处理流程：
⚠️ 这是WaaS系统向商户回调URL发起的请求流程
商户需要按照以下流程处理从WaaS收到的回调请求
回调数据加密
1
WaaS准备JSON业务数据
2
WaaS使用商户私钥RSA加密
3
Base64编码用于传输
回调请求验证
A
WaaS在请求头携带X-API-KEY
B
商户校验API KEY有效性
C
验证失败返回401 Unauthorized
商户解密回调数据
α
从原始输入流读取回调数据
β
Base64解码得到加密数据
γ
商户使用公钥RSA解密
WaaS回调请求示例：

// WaaS发送到商户回调URL的请求
POST /your-callback-endpoint HTTP/1.1
Host: your-merchant-domain.com
Content-Type: application/x-www-form-urlencoded
X-API-KEY: merchant_api_key_12345


ew0KICAib3JkZXJJZCI6ICIxMjM0NTY3ODk…

​
2. 商户处理回调的要点

回调API Key验证：
处理来自WaaS的回调请求时：
  • 从HTTP头X-API-KEY获取WaaS提供的密钥
  • 验证密钥是否有效且在有效期内
  • 验证失败返回401 Unauthorized

注：该API Key与商户调用WaaS API时使用的密钥不同

回调数据解密规范：
处理WaaS回调数据需注意：
  • 必须使用HttpServletRequest原始输入流读取
  • Base64解码获取加密字节数据
  • 使用商户私钥进行RSA解密

常见错误：误用request.getParameter(“data”)会返回null

回调处理说明：

WaaS系统向商户配置的回调URL发送事件通知，商户需要正确处理这些回调请求。 加解密流程与商户调用WaaS API时相同，主要区别在于回调数据读取方式。

​
3. 回调幂等性处理

回调幂等性要求：
WaaS可能重发相同事件回调
商户需保证相同事件只处理一次
回调类型幂等键组成说明
存款回调(txid, chain, symbol, toAddress)组合哈希解决包装合约重复存款问题
提款回调txidWaaS控制的全局唯一交易ID
其他回调(type, trackingId, callBackId…)所有回调类型均需实现幂等

WaaS提示：切勿使用每次不同的requestUUID作为幂等键

回调处理原则：
  • 存储已处理回调事件的唯一标识
  • 对重复回调直接返回成功状态(不重复业务处理)
  • 当回调处理失败时(仅当errCode=0时，WaaS才认为回调成功)，WaaS将重试回调