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）與商戶自有業務帳單進行筆數與金額雙向核對。