SureLink 開放平台

鏈上充幣訂單 (Crypto Deposit) ​

SureLink 網關支援商戶為自有系統或使用者建立專屬的鏈上數位資產（USDT）充幣地址，即時監聽區塊鏈節點交易並自動確認入帳。

1. 業務交互時序 ​

mermaid
sequenceDiagram
    autonumber
    participant Merchant as 商戶系統
    participant Gateway as SureLink 網關
    participant Blockchain as 區塊鏈網路 (TRON / ETH)

    Merchant->>Gateway: 1. POST /api/v1/crypto-deposit-orders (建立充幣訂單)
    Gateway-->>Merchant: 2. 返回充幣錢包地址 walletAddress 與有效截止期
    Merchant-->>Merchant: 3. 展示充幣二維碼與地址給使用者
    Blockchain->>Gateway: 4. 使用者鏈上轉帳，網關掃塊監聽到交易 (DETECTED)
    Blockchain->>Gateway: 5. 區塊確認數達到安全閾值
    Gateway->>Gateway: 6. 記帳至商戶可用資產 (COMPLETED)
    Gateway->>Merchant: 7. Webhook 異步推送鏈上入帳通知

2. 建立鏈上充幣訂單 ​

POST /api/v1/crypto-deposit-orders

為本次充幣申請分配專屬的區塊鏈錢包收款地址。

請求頭 (Headers) ​

攜帶標準 HMAC 簽名頭及 Idempotency-Key。

請求體 (Body) ​

欄位類型是否必填說明
chainstring必填目標區塊鏈網路代碼（如 "TRON", "ETH", "BSC"），需從 GET /api/v1/chains 中取得。
amountstring必填預期充幣數量（USDT），保留 2 ~ 6 位小數（如 "100.00", "50.123456"）。

請求範例 ​

bash
curl -X POST "https://api-sandbox.surelink.io/api/v1/crypto-deposit-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: CRYPTO_DEP_001" \
  -d '{
    "chain": "TRON",
    "amount": "100.00"
  }'
typescript
import { sendSignedRequest } from './signer';

const result = await sendSignedRequest({
  apiKey: 'mch_key_...',
  apiSecret: 'sec_...',
  method: 'POST',
  url: 'https://api-sandbox.surelink.io/api/v1/crypto-deposit-orders',
  body: {
    chain: 'TRON',
    amount: '100.00'
  }
});

回應說明 (Response) ​

  • HTTP 狀態碼：201 Created
json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "orderNo": "CD202610110001",
  "ownerType": "MERCHANT",
  "ownerId": "mch_12345",
  "chain": "TRON",
  "assetSymbol": "USDT",
  "expectedAmount": "100.000000",
  "creditedAmount": null,
  "status": "PENDING_DEPOSIT",
  "walletAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "txHash": null,
  "expiresAt": "2026-10-11T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-10-11T09:00:00.000Z",
  "updatedAt": "2026-10-11T09:00:00.000Z"
}

3. 分頁查詢充幣訂單列表 ​

GET /api/v1/crypto-deposit-orders

Query 參數 ​

參數名類型是否必填預設值說明
pagenumber否1當前頁碼，從 1 開始
pageSizenumber否20每頁數量（最大 100）
chainstring否-按鏈代碼篩選（如 TRON）
statusstring否-按狀態篩選（如 COMPLETED）

4. 查詢單筆充幣訂單詳情 ​

GET /api/v1/crypto-deposit-orders/:id

通過內部 ID 或訂單號查詢指定充幣單詳情。

回應說明 (Response) ​

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "orderNo": "CD202610110001",
  "ownerType": "MERCHANT",
  "ownerId": "mch_12345",
  "chain": "TRON",
  "assetSymbol": "USDT",
  "expectedAmount": "100.000000",
  "creditedAmount": "100.000000",
  "status": "COMPLETED",
  "walletAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "txHash": "0x5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "expiresAt": "2026-10-11T10:00:00.000Z",
  "completedAt": "2026-10-11T09:05:32.000Z",
  "createdAt": "2026-10-11T09:00:00.000Z",
  "updatedAt": "2026-10-11T09:05:32.000Z"
}

5. 鏈上充幣狀態機 ​

狀態代碼說明是否終態
PENDING_DEPOSIT待充幣入帳，等待鏈上檢測到轉帳交易否
DETECTED鏈上已監聽到入帳交易，正在等待安全區塊確認數否
MANUAL_REVIEW充值金額與預期偏差較大或風險預警，人工審核中否
COMPLETED充幣已成功入帳，終態是
EXPIRED在有效期截止前未檢測到交易，地址已失效，終態是
CANCELLED訂單已取消，終態是