SureLink 開放平台

平台概覽與準備 ​

歡迎使用 SureLink 網關 開放平台。SureLink 提供了一站式加密資產與法幣清結算處理解決方案，協助商戶高效連接全球承兌商與數位資產網路，實現安全、合規、低延遲的資金流轉。

1. 核心架構與業務模型 ​

SureLink 網關採用撮合與託管分離的安全架構，支援以下核心業務形態：

                    ┌────────────────────────┐
                    │      商戶業務系統       │
                    └───────────┬────────────┘
                                │ 1. 下單/查詢/代付 (API / HMAC)
                                ▼
                    ┌────────────────────────┐
                    │      SureLink 網關     │
                    └─────┬────────────┬─────┘
           2. 喚起收銀台   │            │ 3. 撮合派單 & 憑證流轉
                          ▼            ▼
┌────────────────────────┐              ┌────────────────────────┐
│     終端消費者 / 買家    │              │     場外承兌商 / 交易員  │
│    (向承兌商匯款法幣)   │              │   (提供法幣流動性與放行)│
└────────────────────────┘              └────────────────────────┘

1.1 業務能力全景 ​

模組業務功能核心價值
法幣儲值 (Pay-in)消費者在商戶平台購買數位資產或法幣入金商戶調用 API 取得專屬收銀台（payUrl），使用者無需離開商戶閉環即可快速完成法幣匯款，承兌商確認後自動入帳。
法幣代付 (Pay-out)商戶向使用者指定銀行帳戶匯款下發法幣出金商戶發起代付請求，平台自動鎖定商戶結算資產並撮合承兌商匯款，支援承兌商上傳轉帳憑證、商戶核對放行與異常爭議機制。
鏈上充提幣 (Crypto)原生區塊鏈數位資產充值與提現 (如 USDT)動態分配鏈上充幣地址，監聽區塊確認數；提供免人工干預的自動化鏈上資金歸集與提幣審核下發通道。
異步通知 (Webhook)訂單全生命週期事件推送訂單完成、取消、承兌商上傳付款憑證等重要事件均通過毫秒級 Webhook 通知商戶系統。

2. 商戶接入四部曲 ​

接入 SureLink 僅需以下四個步驟：

mermaid
flowchart LR
    Step1["1. 註冊入駐與資質核驗"] --> Step2["2. 取得 API 金鑰"]
    Step2 --> Step3["3. 設定安全白名單與回調"] --> Step4["4. 沙盒聯調與正式上線"]

步驟 1：商戶註冊與資質審核 (KYC) ​

  1. 訪問 SureLink 商戶管理後台，註冊商戶管理員帳號。
  2. 提交企業資質認證（KYC / KYB），包含營業執照、法人身份證明及業務合規證明文件。
  3. 審核通過後，商戶帳戶將自動啟用入金與代付權限。

步驟 2：生成 API Key 與 API Secret ​

  1. 登入商戶後台，進入 「開發者中心」->「API 金鑰管理」。
  2. 建立一組 API Key，系統將生成：
    • API Key：公鑰標識，用於在每次 API 請求中標識商戶身份。
    • API Secret：HMAC 對稱加密金鑰，僅在建立時完整展示一次，請立即保存在私密安全之金鑰管理系統中。
  3. 若金鑰遺失或洩漏，可隨時在後台撤銷舊金鑰並建立新金鑰。

步驟 3：設定 IP 白名單與 Webhook 回調地址 ​

  1. IP 白名單 (IP Whitelist)：
    • 為了防範金鑰洩漏帶來的風險，商戶需在商戶後台 「安全設定」 中設定調用網關 API 的伺服器公網出口 IP 地址。
    • 只有處於白名單列表內的 IP 請求才會被受理，非白名單 IP 將直接返回 403 Forbidden (IP_NOT_WHITELISTED)。
  2. Webhook 回調地址 (Callback URL)：
    • 設定接收訂單交易結果、憑證上傳等事件推送的 HTTPS 伺服端介面地址。
    • 平台禁止向內網私有 IP（如 127.0.0.1, 192.168.x.x）推送 Webhook（內建 SSRF 防禦）。

步驟 4：沙盒聯調與正式投產 ​

  1. 利用沙盒聯調環境進行全流程介面調用、簽名測試與 Webhook 驗簽演練。
  2. 完成端到端聯調後，切換為生產環境 Base URL 與生產金鑰，正式上線展業。

3. 環境與通訊規範 ​

3.1 網關服務地址 (Base URL) ​

環境Base URL說明
沙盒測試環境 (Sandbox)https://api-sandbox.surelink.io用於對接調試與模擬交易測試，不產生真實資金流動
生產環境 (Production)https://api.surelink.io正式交易環境，高可用部署，資金真實結算

3.2 基礎通訊協定規範 ​

  • 通訊協定：必須採用 HTTPS (TLS 1.2+)，保障傳輸層數據機密性。
  • 字元編碼：所有請求與回應統一採用 UTF-8 編碼。
  • 資料格式：請求主體（Request Body）與回應主體（Response Body）統一使用 application/json。
  • 時間格式：時間戳欄位統一採用 毫秒級 Unix 時間戳（如 1715000000000）或 標準 ISO 8601 格式（如 2026-10-11T08:30:00.000Z）。
  • 金額精度與表示：
    • 數位資產金額（如 USDT）：固定採用字串形式傳輸，最多保留 6 位小數（如 "100.500000"）。
    • 法幣金額（如 CNY）：固定採用字串形式傳輸，必須保留 2 位小數（如 "725.50"）。