前置条件
应用已通过签名调试;已了解产品编码与配置参数;回调地址可公网访问并支持验签。
操作步骤
- 调用创建订单接口,传入产品编码、配置、数量、客户标识与幂等键。同一业务请求必须复用同一幂等键,有效期 24 小时。
- 订单创建成功后返回订单号与支付链接;将支付链接交给终端用户完成支付,不要在服务端代替用户支付。
- 支付完成后,通过订单查询接口获取状态;也可等待 Webhook 通知。
- 开通是异步过程,订单状态依次为待支付、已支付、开通中、已开通;开通失败会返回失败原因。
- 配置 Webhook:设置回调地址与签名密钥,收到通知后先验签,再处理业务,最后返回成功响应。
- Webhook 失败会按策略重试;同一事件可能重复投递,业务侧需按事件 ID 做幂等。
结果验证
订单查询返回最新状态与交付信息;Webhook 日志显示投递成功;重复通知不会造成重复开通或重复记账。
出问题怎么办
- 订单一直待支付:确认用户已完成支付,支付链接未过期;必要时重新获取链接。
- 支付成功但状态未更新:先查询订单,等待回调;超过预计时间提交工单并附订单号。
- Webhook 收不到:检查回调地址公网可达、证书有效、防火墙放行。
- 重复开通:检查事件幂等与订单幂等键,避免重复提交。
注意:接口字段、状态枚举与回调事件结构以开放平台文档为准;响应中不会返回成本、毛利或供给源信息。
常见报错与处理
重复创建订单 原因:重试时更换了幂等键。
处理:同一业务请求固定使用同一幂等键,先查询再重试。
Webhook 验签失败 原因:使用了错误的密钥或对原始报文做了改写。
处理:使用平台提供的验签密钥与原始请求体验签。
回调重复处理 原因:未按事件 ID 做幂等。
处理:落库事件 ID,重复事件直接返回成功不再执行业务。