SureLink 开放平台

幂等性与最佳实践 ​

在金融与数字货币支付清结算场景中，网络超时、网络重试和并发请求是常态。为了确保资金安全、避免商户系统重复扣款或漏单，SureLink 网关提供了系统级的幂等性设计与双重核验机制。

1. 幂等性设计 (Idempotency-Key) ​

1.1 什么是幂等性 ​

接口幂等性是指：使用相同的参数和相同的幂等凭证对同一个接口发起多次调用，服务端保证只执行一次实际业务逻辑，并返回完全一致的成功结果。

1.2 网关幂等性运作机制 ​

网关在所有写操作接口（如 POST /api/v1/orders、POST /api/v1/withdrawals、POST /api/v1/crypto-deposit-orders）上支持 Idempotency-Key 请求头：

  1. 唯一性标识：商户应为每一次业务尝试生成唯一的 Idempotency-Key（如 UUID v4，例如 a9b2c3d4-e5f6-7890-1234-567890abcdef）。
  2. 自动回退策略：若商户未在 Header 中显式传递 Idempotency-Key，网关将默认提取请求体中的 merchantOrderNo 作为幂等标识。
  3. 缓存与原子执行：网关在处理请求时，通过分布式锁锁定幂等键；成功处理后将响应报文持久化在 Redis 中。当后续收到完全相同的幂等键请求时，网关直接返回已保存的响应结果，避免向数据库二次插入重复订单。

建议实践

在因网络超时（如 HTTP 504、TCP 连接重置）未收到网关即时响应时，商户重试请求必须携带与首次请求完全相同的 Idempotency-Key 和请求报文。

2. 状态机双重核验策略 (Webhook + Polling) ​

尽管 Webhook 具备极高的高可用性与重试机制，但极端网络故障仍可能导致单边延迟。推荐商户系统实施 “Webhook 驱动为主，主动轮询补偿为辅” 的双重核验策略：

mermaid
flowchart TD
    Create["1. 商户系统创建订单"] --> Wait["2. 监听 Webhook 异步回调"]
    Wait -->|收到回调且验签通过| Update["3. 更新本地订单状态为 COMPLETED"]
    Wait -->|超时未收到回调| Poll["4. 主动调用 GET /api/v1/orders/:orderNo"]
    Poll --> Check{"5. 网关订单状态?"}
    Check -->|已完成| Update
    Check -->|处理中| Delay["延迟 30 秒再次轮询"] --> Poll
    Check -->|已取消/超时| Fail["更新本地订单状态为 CANCELLED"]

最佳轮询节奏： ​

  • 前 15 分钟：每隔 15~30 秒轮询一次（用户正在收银台打款的主要时间段）。
  • 15 ~ 30 分钟：每隔 1~2 分钟轮询一次。
  • 30 分钟以上：如果订单仍未完成且到达超时时间，触发系统自动核对或标记为待人工排查。

3. 防重入与资金安全防范 ​

  1. 数据库乐观锁/行级锁：
    • 商户系统在接收到 order.completed 回调时，应通过 WHERE status = 'PENDING' 的条件进行状态更新，切忌无条件覆盖，防止并发重复入账。
  2. 敏感信息安全存储：
    • 严禁将商户 API Secret 硬编码在前端代码或客户端 APP 中，所有签名与调用必须在商户受信任的后端服务器完成。
    • 代付收款人银行账户属于敏感 PII，网关在数据库采用 AES-GCM 强加密存储，且在列表和日志中全量脱敏；商户在自身业务端也应遵循相关金融合规要求妥善保管。
  3. 每日对账机制：
    • 建议商户系统在每日 T+1（如凌晨 02:00）通过接口对前一日所有终态订单（COMPLETED、CANCELLED）与商户自有业务账单进行笔数与金额双向核对。