法幣儲值 (入金 / Pay-in)

法幣儲值服務允許商戶為終端買家提供法幣購買數位資產（如 USDT）並完成儲值入帳的能力。網關負責聚合承兌商報價、鎖定匯率並生成統一的收銀台網頁地址（payUrl），使用者在收銀台向撮合的承兌商完成法幣匯款後，承兌商確認放行，網關自動將數位資產記入商戶帳戶並通過 Webhook 回調商戶系統。

1. 業務交互時序

mermaid

sequenceDiagram
    autonumber
    actor User as 終端買家
    participant Merchant as 商戶系統
    participant Gateway as SureLink 網關
    actor Trader as 場外承兌商

    User->>Merchant: 1. 發起儲值請求 (購買 100 USDT)
    Merchant->>Gateway: 2. POST /api/v1/orders (建立儲值訂單)
    Gateway-->>Merchant: 3. 返回 orderNo 與收銀台 payUrl
    Merchant-->>User: 4. 引導使用者跳轉或在 WebView 中打開 payUrl
    User->>Gateway: 5. 造訪收銀台，查看承兌商收款銀行卡資訊
    User->>Trader: 6. 使用者通過手機銀行向承兌商法幣匯款
    User->>Gateway: 7. 在收銀台點擊「我已完成付款」
    Trader->>Gateway: 8. 承兌商查帳確認收到法幣並點擊放行
    Gateway->>Gateway: 9. 結算入帳至商戶代幣帳戶
    Gateway->>Merchant: 10. Webhook 異步推送 order.completed
    Merchant-->>User: 11. 商戶業務系統為使用者發放相應權益/額度

2. 建立儲值訂單

POST /api/v1/orders

請求頭 (Headers)

請求頭	類型	是否必填	說明
`Content-Type`	`string`	必填	固定 `application/json`
`X-Api-Key`	`string`	必填	商戶 API Key
`X-Timestamp`	`string`	必填	毫秒級時間戳
`X-Nonce`	`string`	必填	16-64 位隨機串
`X-Signature`	`string`	必填	HMAC-SHA256 簽名 hex
`Idempotency-Key`	`string`	推薦	唯一冪等鍵，缺省時自動取 `merchantOrderNo`

請求體 (Body)

欄位	類型	是否必填	約束說明
`merchantOrderNo`	`string`	必填	商戶系統唯一訂單號，長度 1 ~ 64 位字元。
`direction`	`string`	否	固定 `'DEPOSIT'`（入金/儲值），預設 `'DEPOSIT'`。
`pair`	`string`	否	交易對，目前固定為 `'USDT/CNY'`。
`assetSymbol`	`string`	否	資產代幣符號，目前固定為 `'USDT'`。
`assetAmount`	`string`	選填*	欲購買的數位資產數量（正數，最多 6 位小數，如 `"100.000000"`）。
`fiatCurrency`	`string`	否	法幣幣種，目前固定為 `'CNY'`。
`fiatAmount`	`string`	選填*	欲支付的法幣金額（正數，必須嚴格 2 位小數，如 `"725.50"`）。
`metadata`	`object`	否	商戶自訂透傳鍵值對物件（`Record<string, string>`）。

金額參數說明

assetAmount 與 fiatAmount 二者必填其一：

若傳入 assetAmount，網關將根據當前鎖定匯率即時換算使用者需支付的 fiatAmount。
若傳入 fiatAmount，網關將根據匯率自動計算最終到帳的 assetAmount。

請求範例

cURLNode.js

bash

curl -X POST "https://api-sandbox.surelink.io/api/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: mch_key_your_api_key" \
  -H "X-Timestamp: 1715000000000" \
  -H "X-Nonce: 9f8e7d6c5b4a392817263544a1b2c3d4" \
  -H "X-Signature: c8b9...f01" \
  -H "Idempotency-Key: MCH_PAYIN_20261011_001" \
  -d '{
    "merchantOrderNo": "MCH_PAYIN_20261011_001",
    "assetAmount": "100.000000",
    "pair": "USDT/CNY",
    "metadata": {
      "userId": "user_8848"
    }
  }'

typescript

import { sendSignedRequest } from './signer';

const response = await sendSignedRequest({
  apiKey: 'mch_key_...',
  apiSecret: 'sec_...',
  method: 'POST',
  url: 'https://api-sandbox.surelink.io/api/v1/orders',
  body: {
    merchantOrderNo: 'MCH_PAYIN_20261011_001',
    assetAmount: '100.000000',
    pair: 'USDT/CNY'
  }
});

回應說明 (Response)

HTTP 狀態碼：201 Created

json

{
  "orderId": "698c56fa-b0f1-460d-8302-39c09c916781",
  "orderNo": "ORD20261011000001",
  "status": "PENDING_PAYMENT",
  "assetAmount": "100.000000",
  "fiatAmount": "725.50",
  "fiatCurrency": "CNY",
  "usdAmount": "100.00",
  "usdFeeAmount": "0.50",
  "feeBps": 50,
  "expiresAt": "2026-10-11T08:50:00.000Z",
  "payUrl": "https://pay.surelink.io/orders/ORD20261011000001",
  "pricingSnapshot": {
    "fxRate": "7.2550",
    "fiatCurrency": "CNY",
    "fiatAmount": "725.50",
    "feeAmount": "0.50",
    "quotedAt": "2026-10-11T08:35:00.000Z"
  }
}

回應核心欄位

欄位	類型	說明
`orderId`	`string`	網關系統內部唯一 UUID
`orderNo`	`string`	網關業務訂單號（以 ORD 開頭，全域唯一）
`status`	`string`	初始狀態（通常為 `PENDING_PAYMENT` 或 `PENDING_MATCH`）
`assetAmount`	`string`	最終入帳代幣數量
`fiatAmount`	`string`	終端使用者需支付的法幣金額 (CNY)
`expiresAt`	`string`	訂單支付有效截止時間 (ISO 8601)，超時未付款自動取消
`payUrl`	`string`	收銀台連結。商戶應將買家重定向至此連結或在客戶端內嵌 WebView 展示
`pricingSnapshot`	`object`	鎖定價格與匯率快照詳情

3. 分頁查詢儲值訂單列表

GET /api/v1/orders

商戶可透過本接口批量分頁拉取自身建立的儲值訂單記錄，支援按平台單號、商戶單號、訂單狀態以及時間範圍多維度組合檢索。

請求頭 (Headers)

攜帶標準 HMAC 鑑權請求頭（X-Api-Key、X-Timestamp、X-Nonce、X-Signature）。

Query 參數

參數名	類型	是否必填	預設值	描述
`page`	`number`	否	`1`	當前頁碼，從 1 開始
`pageSize`	`number`	否	`20`	每頁數量，最大 100
`orderNo`	`string`	否	-	按平台業務訂單號精準篩選（如 `ORD20261011000001`）
`merchantOrderNo`	`string`	否	-	按商戶外部訂單號精準篩選（如 `MCH_PAYIN_20261011_001`）
`status`	`string`	否	-	訂單狀態篩選，多個狀態可用逗號分隔（如 `COMPLETED` 或 `PENDING_PAYMENT,PAYMENT_SUBMITTED`）
`direction`	`string`	否	`DEPOSIT`	訂單方向，查詢入金儲值固定或預設為 `DEPOSIT`
`from`	`string`	否	-	建立時間起始範圍 (ISO 8601，如 `2026-10-01T00:00:00.000Z`)
`to`	`string`	否	-	建立時間截止範圍 (ISO 8601，如 `2026-10-11T23:59:59.000Z`)

請求範例

cURLNode.js

bash

curl -X GET "https://api-sandbox.surelink.io/api/v1/orders?page=1&pageSize=20&status=COMPLETED" \
  -H "X-Api-Key: mch_key_your_api_key" \
  -H "X-Timestamp: 1715000000000" \
  -H "X-Nonce: 9f8e7d6c5b4a392817263544a1b2c3d4" \
  -H "X-Signature: c8b9...f01"

typescript

import { sendSignedRequest } from './signer';

const result = await sendSignedRequest({
  apiKey: 'mch_key_...',
  apiSecret: 'sec_...',
  method: 'GET',
  url: 'https://api-sandbox.surelink.io/api/v1/orders?page=1&pageSize=20&status=COMPLETED'
});
console.log('總訂單數:', result.total);
console.log('訂單列表:', result.items);

回應說明 (Response)

HTTP 狀態碼：200 OK

json

{
  "items": [
    {
      "id": "698c56fa-b0f1-460d-8302-39c09c916781",
      "orderNo": "ORD20261011000001",
      "merchantOrderNo": "MCH_PAYIN_20261011_001",
      "merchantId": "mch_12345",
      "traderId": "tra_67890",
      "direction": "DEPOSIT",
      "status": "COMPLETED",
      "pair": "USDT/CNY",
      "assetSymbol": "USDT",
      "assetAmount": "100.000000",
      "fiatCurrency": "CNY",
      "fiatAmount": "725.50",
      "fxRate": "7.2550",
      "usdAmount": "100.00",
      "usdFeeAmount": "0.50",
      "paymentSubmittedAt": "2026-10-11T08:38:12.000Z",
      "completedAt": "2026-10-11T08:40:05.000Z",
      "createdAt": "2026-10-11T08:35:00.000Z",
      "updatedAt": "2026-10-11T08:40:05.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

4. 查詢單筆儲值訂單詳情

GET /api/v1/orders/:orderNo

支援按 平台業務訂單號（orderNo） 或 商戶外部訂單號（merchantOrderNo） 查詢單筆儲值訂單的狀態與詳情。

路由參數

orderNo (string): 平台的訂單號（如 ORD20261011000001）或商戶自訂單號（如 MCH_PAYIN_20261011_001）。

回應說明 (Response)

HTTP 狀態碼：200 OK

json

{
  "id": "698c56fa-b0f1-460d-8302-39c09c916781",
  "orderNo": "ORD20261011000001",
  "merchantOrderNo": "MCH_PAYIN_20261011_001",
  "merchantId": "mch_12345",
  "traderId": "tra_67890",
  "direction": "DEPOSIT",
  "status": "COMPLETED",
  "pair": "USDT/CNY",
  "assetSymbol": "USDT",
  "assetAmount": "100.000000",
  "fiatCurrency": "CNY",
  "fiatAmount": "725.50",
  "fxRate": "7.2550",
  "usdAmount": "100.00",
  "usdFeeAmount": "0.50",
  "paymentSubmittedAt": "2026-10-11T08:38:12.000Z",
  "completedAt": "2026-10-11T08:40:05.000Z",
  "disputeReason": null,
  "chainTxKey": null,
  "source": "API",
  "createdAt": "2026-10-11T08:35:00.000Z",
  "updatedAt": "2026-10-11T08:40:05.000Z"
}

租戶安全隔離

若嘗試查詢屬於其他商戶的訂單，系統統一返回 404 Not Found (ORDER_NOT_FOUND)，杜絕訂單號撞單列舉探測。

5. 儲值訂單狀態機全生命週期

狀態代碼	狀態名稱	說明	是否終態
`PENDING_MATCH`	待匹配承兌商	訂單已建立，網關正在撮合最優承兌商分配收款卡	否
`PENDING_PAYMENT`	待買家支付	承兌商已鎖定，買家可在收銀台查看收款卡並轉帳	否
`PAYMENT_SUBMITTED`	買家已付款	買家在收銀台點擊「我已付款」，等待承兌商查帳核驗	否
`PENDING_RELEASE`	待放行	承兌商確認收到法幣，進入代幣解凍與劃轉階段	否
`SETTLING`	結算中	系統正在執行帳本變更與出入金分帳	否
`COMPLETED`	交易成功	代幣已劃轉至商戶帳戶，終態，觸發 Webhook	是
`CANCELLED`	訂單取消	超過支付時限未付款或使用者自主取消，終態	是
`DISPUTED`	爭議中	承兌商未收到款或金額不符發起申訴，客服介入處理	否
`FAILED`	交易失敗	結算失敗或仲裁撤銷，終態	是

法幣儲值 (入金 / Pay-in) ​

1. 業務交互時序 ​

2. 建立儲值訂單 ​

請求頭 (Headers) ​

請求體 (Body) ​

請求範例 ​

回應說明 (Response) ​

回應核心欄位 ​

3. 分頁查詢儲值訂單列表 ​

請求頭 (Headers) ​

Query 參數 ​

請求範例 ​

回應說明 (Response) ​

4. 查詢單筆儲值訂單詳情 ​

路由參數 ​

回應說明 (Response) ​

5. 儲值訂單狀態機全生命週期 ​

法幣儲值 (入金 / Pay-in)

1. 業務交互時序

2. 建立儲值訂單

請求頭 (Headers)

請求體 (Body)

請求範例

回應說明 (Response)

回應核心欄位

3. 分頁查詢儲值訂單列表

請求頭 (Headers)

Query 參數

請求範例

回應說明 (Response)

4. 查詢單筆儲值訂單詳情

路由參數

回應說明 (Response)

5. 儲值訂單狀態機全生命週期