法币充值 (入金 / 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. 充值订单状态机全生命周期