接入指南
在切换到 Production 之前，请先在 Sandbox 中完成完整打款链路验证。建议把环境准备、四阶段流程和回调处理一并验证，再进入上线阶段。
为什么要先在 Sandbox 完整验证
至少要先验证以下基础能力：
- 白名单和环境域名是否正确
- 商户凭证和签名是否可用
- 收款方资料是否能按字段模板准备成功
- 打款请求是否能进入处理流程
- 最终结果是否能通过 webhook 或查询接口闭环
如果这些环节只验证一部分，就很容易在上线时遇到“请求能发，但链路没有闭环”的问题。
建议验证内容
- 请求签名是否稳定可用
beneficiaryId的创建、复用和查询链路是否正常- 发起打款后是否能收到 webhook 通知
- 对于未闭环订单，主动查询是否能补齐结果
- 成功订单是否能按需下载电子回单
额外值得验证的点
除了验证主流程成功，还建议补充检查：
- 重复通知下的幂等处理
- 异常状态下的恢复逻辑
- 失败原因是否能在内部系统中被记录和展示
payer、beneficiary与业务订单 ID 的映射是否完整- 回单下载、归档和后续访问是否满足内部要求
推荐测试顺序
- 验证环境、白名单和密钥配置
- 确认目标国家、币种、主体类型下的打款方式
- 查询该组合下的必填字段
- 创建测试收款方
- 通过
beneficiaryId发起一笔打款 - 接收 webhook 并更新订单状态
- 对未闭环订单执行主动查询
- 对成功订单下载电子回单
如果您的业务同时使用 beneficiaryId 路径和“直接提交收款方信息”路径，请分别验证这两条路径，不要只验证其中一条。
上线前清单
- 生产域名和白名单配置已确认
- 生产密钥已安全存储
- 回调地址已可被公网访问
- 服务端已支持验签、幂等处理和重试安全
- 业务系统具备清晰的状态流转和异常恢复流程
- 已确认最终使用 webhook、主动查询或两者结合的闭环方式
常见问题
什么时候应该确认 merchantNo、密钥和回调地址？
最好在联调开始前确认，而不是等到上线前临时处理。否则很容易被签名失败、白名单不一致或回调不可达这类基础问题阻塞。
上线前最容易漏掉的是什么？
最常见的是异常闭环，包括 webhook 重试、主动查询补偿、失败原因落库，以及对未闭环订单的定时巡检。
只验证同步响应成功，是否足够？
不够。同步响应成功并不代表交易结束。至少还要验证 webhook 或主动查询能否拿到最终状态。
如果您的业务会批量提交打款，也建议在上线前一并验证批量查询、监控告警和对账流程。