> ## 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 会把相关支付结果通过数据流的形式发送给商户，商户需要接收处理，并按文档规范返回应答。

1. 同样的通知可能会多次发送给商户系统，商户系统必须能够正确处理重复的通知。
2. 后台异步通知交互时，如果 GatePay 收到商户的应答不符合规范或超时，会判定本次通知失败，重新发送通知，直到成功为止。（在通知一直不成功的情况下，GatePay 会在 15秒 / 30秒 / 3分钟 / 10分钟 / 20分钟 / 30分钟 / 60分钟 / 3小时 / 6小时 后进行重试）

## 退款流程

1. 商户侧调用退款接口（`/v1/pay/order/refund`）创建退款单，注意退款是异步流程，该接口成功并不代表实际退款结果。
2. 等待退款回调通知，如果收到 GatePay 异步回调通知获取到退款结果，不用再调用查询接口。
3. 如果在 10s 内没有收到退款状态通知，调用（`/v1/pay/order/refund/query`）接口查询退款单状态，具体可参考支付回调和查单实现指引章节。

## 最佳安全实践

### 数据传输

使用 HTTPS 确保网络传输安全性。

禁用 SSL 等不安全协议和算法，建议使用 `TLS1.2` 及以上。

不要轻易的尝试设计和实现自己的加密传输算法，几乎都会存在问题。

### 数据存储

敏感信息禁止出现在日志中，如确实需要，需进行脱敏处理。

缓存和 DB 中的敏感数据需进行加密。

密码等关键认证必须采用加盐加密方式保存。

### 数据访问

外部请求数据访问必须进行鉴权操作。

对于内部的数据访问要严加控制，降低用户信息泄露风险。

### 防止逻辑处理不当导致的漏洞

支付成功回调通知必须验证 GatePay 签名，避免被恶意攻击。

在后台进行商户价格的判断逻辑，避免客户端篡改价格导致商户损失。

避免在 App 或者网站页面里面出现商户 `Securekey`。

## 常见问题

**Q：通过预下单接口生成的二维码多长时间有效？**

A：商户可指定订单过期时间，其中 Gate 支付订单最大有效期为 1 小时，地址支付订单最大有效期为 24 小时。

**Q：支持使用哪种币种下单？**

A：下单时可以选择使用加密货币币种和金额，或法币币种和金额。如选择使用法币会在下单时查询实时汇率自动转换成加密货币收款。