先保存業務訂單
生成唯一 client_order_id,先在資料庫保存數量、租期與接收地址,並建立唯一約束。本文是接入參考,不是客戶案例。
保存完整報價
GET /prices/quote 必須對應實際數量與租期。回應包含 price_sun、currency 及 priced_at;price_sun 是整數 SUN 字串,用作目前參考價。POST /orders 受理時會重新計算並鎖定訂單價格,不需提交報價編號。
簽名與請求一致
憑據只保留在伺服器。將 JSON 序列化一次,依規範對實際傳送位元組簽名。日誌隱藏密鑰和認證標頭。
同時保存冪等鍵
POST /orders 除 client_order_id 外,還要求 8–128 個可見 ASCII 字元的 Idempotency-Key。提交前保存鍵值及原始請求。重試不確定結果時保持兩者不變,重新生成時間戳、nonce 與簽名。商戶下單不會回傳 QUOTE_EXPIRED。Webhook 規則見公開 Skill,地址啟動沒有回呼,需查詢結果。
超時先查單
POST /orders 超時後,先以 GET /orders?client_order_id={client_order_id} 查詢。已有訂單繼續追蹤,適合重試時保留相同編號與參數,冪等衝突應排查。
受理與完成分開
保存平台訂單號與狀態,依据終態和交付證據更新本地紀錄,HTTP 成功不能視為已委託。失敗與待審核狀態保留給人員處理。
回呼驗簽與去重
按規範驗證 Webhook,依事件編號去重,可靠保存或處理後再回覆。容忍重複通知,狀態不一致時透過查單對帳。
限制重試並驗證異常
使用超時、指數退避及有限重試。記錄不含秘密的訂單狀態變化。上線前檢查餘額不足、過期報價、重複訂單、超時與錯誤簽名;實際傳輸格式以下方規範為準。