Documentation Index
Fetch the complete documentation index at: https://docs.gate.com/llms.txt
Use this file to discover all available pages before exploring further.
支付回调与查单
背景 由于网络异常或者系统的波动，可能会导致用户支付成功，但是商户侧未能成功接收到支付结果通知，进而显示订单未支付的情况。商户侧的订单状态更新不及时，容易造成用户投诉，甚至是重复支付的情况发生。 目标 商户在未能收到支付结果通知时，也能及时、准确地获取到订单的支付状态，提升商户系统的健壮性，减少因为订单状态不同步导致的用户投诉。 商户后端服务处理 商户后台需要准确、高效地处理 GatePay 发送的异步支付结果通知，并按接口规范把处理结果返回给 GatePay 服务。 定时轮询查单 如果长时间没有收到支付结果通知，商户后台应该定时轮询调用订单状态查询接口（/v1/pay/order/query）去核实订单状态。
方案一
以订单下单成功时间为基准，每隔 5秒 / 10秒 / 30秒 / 1分钟 / 3分钟 / 5分钟 / 10分钟 / 30分钟 调用订单状态查询接口（/v1/pay/order/query）查询一次，最后一次查询还是未返回支付成功状态，则停止后续查询。并调用关单接口（/v1/pay/order/close）关闭订单。（轮询时间间隔和次数，商户可以根据自身业务场景灵活设置）
方案二
定时任务每隔 30 秒启动一次，找出最近 10 分钟内创建并且未支付的订单，调用订单状态查询接口（/v1/pay/order/query）核实订单状态。系统记录订单查询的次数，在 10 次查询之后状态还是未支付成功，则停止后续查询，并调用关单接口（/v1/pay/order/close）关闭订单。（轮询时间间隔和次数，商户可以根据自身业务场景灵活设置）
注意
支付完成后，GatePay 会把相关支付结果通过数据流的形式发送给商户，商户需要接收处理，并按文档规范返回应答。
- 同样的通知可能会多次发送给商户系统，商户系统必须能够正确处理重复的通知。
- 后台异步通知交互时，如果 GatePay 收到商户的应答不符合规范或超时，会判定本次通知失败，重新发送通知，直到成功为止。（在通知一直不成功的情况下，GatePay 会在 15秒 / 30秒 / 3分钟 / 10分钟 / 20分钟 / 30分钟 / 60分钟 / 3小时 / 6小时 后进行重试）
退款流程
- 商户侧调用退款接口（
/v1/pay/order/refund）创建退款单，注意退款是异步流程，该接口成功并不代表实际退款结果。 - 等待退款回调通知，如果收到 GatePay 异步回调通知获取到退款结果，不用再调用查询接口。
- 如果在 10s 内没有收到退款状态通知，调用（
/v1/pay/order/refund/query）接口查询退款单状态，具体可参考支付回调和查单实现指引章节。
最佳安全实践
数据传输
使用 HTTPS 确保网络传输安全性。 禁用 SSL 等不安全协议和算法，建议使用TLS1.2 及以上。
不要轻易的尝试设计和实现自己的加密传输算法，几乎都会存在问题。
数据存储
敏感信息禁止出现在日志中，如确实需要，需进行脱敏处理。 缓存和 DB 中的敏感数据需进行加密。 密码等关键认证必须采用加盐加密方式保存。数据访问
外部请求数据访问必须进行鉴权操作。 对于内部的数据访问要严加控制，降低用户信息泄露风险。防止逻辑处理不当导致的漏洞
支付成功回调通知必须验证 GatePay 签名，避免被恶意攻击。 在后台进行商户价格的判断逻辑，避免客户端篡改价格导致商户损失。 避免在 App 或者网站页面里面出现商户Securekey。