Fiat Pay-in (Deposit)

The Fiat Pay-in service enables merchants to let end users purchase cryptocurrency (USDT) with fiat currency. The gateway aggregates real-time quotes from liquidity providers, locks the exchange rate, and returns a checkout portal URL (payUrl). Once the buyer transfers fiat to the matched trader, the trader releases the crypto, and the gateway credits the merchant's balance and dispatches a Webhook callback.

1. Sequence Flow

mermaid

sequenceDiagram
    autonumber
    actor User as Buyer / End User
    participant Merchant as Merchant System
    participant Gateway as SureLink Gateway
    actor Trader as Trader / Acceptor

    User->>Merchant: 1. Request deposit (buy 100 USDT)
    Merchant->>Gateway: 2. POST /api/v1/orders (Create pay-in order)
    Gateway-->>Merchant: 3. Return orderNo and payUrl
    Merchant-->>User: 4. Redirect user or open payUrl in WebView
    User->>Gateway: 5. Visit checkout page to view trader bank card info
    User->>Trader: 6. Transfer fiat to trader via mobile banking
    User->>Gateway: 7. Click "I Have Paid" on checkout page
    Trader->>Gateway: 8. Verify bank receipt and release crypto
    Gateway->>Gateway: 9. Settle crypto to merchant balance
    Gateway->>Merchant: 10. Webhook dispatches order.completed
    Merchant-->>User: 11. Credit user account in merchant application

2. Create Pay-in Order

POST /api/v1/orders

Headers

Header	Type	Required	Description
`Content-Type`	`string`	Yes	Fixed `application/json`
`X-Api-Key`	`string`	Yes	Merchant API Key
`X-Timestamp`	`string`	Yes	Millisecond timestamp
`X-Nonce`	`string`	Yes	16-64 char random string
`X-Signature`	`string`	Yes	HMAC-SHA256 hex digest
`Idempotency-Key`	`string`	Recommended	Unique key; defaults to `merchantOrderNo` if omitted

Body Parameters

Field	Type	Required	Description
`merchantOrderNo`	`string`	Yes	Unique merchant order ID (1–64 characters).
`direction`	`string`	No	Fixed `'DEPOSIT'`. Defaults to `'DEPOSIT'`.
`pair`	`string`	No	Currency pair. Fixed `'USDT/CNY'`.
`assetSymbol`	`string`	No	Asset symbol. Fixed `'USDT'`.
`assetAmount`	`string`	Optional*	Target crypto quantity (positive decimal with $\le 6$ decimal places, e.g., `"100.000000"`).
`fiatCurrency`	`string`	No	Fiat currency. Fixed `'CNY'`.
`fiatAmount`	`string`	Optional*	Target fiat amount (positive decimal with exactly 2 decimal places, e.g., `"725.50"`).
`metadata`	`object`	No	Optional key-value pairs (`Record<string, string>`).

Amount Constraints

Either assetAmount or fiatAmount must be provided:

If assetAmount is specified, the gateway computes the required fiatAmount using the locked rate.
If fiatAmount is specified, the gateway computes the credited assetAmount.

Request Example

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

Status Code: 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"
  }
}

Key Fields

Field	Type	Description
`orderId`	`string`	Internal unique UUID
`orderNo`	`string`	Public platform order number (prefixed with ORD)
`status`	`string`	Initial order status (`PENDING_PAYMENT` or `PENDING_MATCH`)
`assetAmount`	`string`	Settled cryptocurrency quantity
`fiatAmount`	`string`	Fiat amount payable by buyer
`expiresAt`	`string`	Payment expiration deadline (ISO 8601 UTC)
`payUrl`	`string`	Checkout Portal URL. Direct the buyer here to complete payment
`pricingSnapshot`	`object`	Snapshot of effective FX rates and fee breakdown

3. List Pay-in Orders

GET /api/v1/orders

Retrieve a paginated list of pay-in orders created by the authenticated merchant, with multi-dimensional filtering by platform order number, merchant order number, order status, and time range.

Request Headers

Include standard HMAC authentication headers (X-Api-Key, X-Timestamp, X-Nonce, X-Signature).

Query Parameters

Parameter	Type	Required	Default	Description
`page`	`number`	No	`1`	Page number, starting from 1
`pageSize`	`number`	No	`20`	Page size, maximum 100
`orderNo`	`string`	No	-	Filter by platform order number (e.g., `ORD20261011000001`)
`merchantOrderNo`	`string`	No	-	Filter by merchant external order number (e.g., `MCH_PAYIN_20261011_001`)
`status`	`string`	No	-	Filter by status; comma-separated for multiple statuses (e.g., `COMPLETED` or `PENDING_PAYMENT,PAYMENT_SUBMITTED`)
`direction`	`string`	No	`DEPOSIT`	Order direction, fixed to or defaults to `DEPOSIT` for pay-in
`from`	`string`	No	-	Creation start timestamp (ISO 8601, e.g., `2026-10-01T00:00:00.000Z`)
`to`	`string`	No	-	Creation end timestamp (ISO 8601, e.g., `2026-10-11T23:59:59.000Z`)

Request Examples

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('Total Orders:', result.total);
console.log('Orders List:', result.items);

Response

Status Code: 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. Query Order Details

GET /api/v1/orders/:orderNo

Retrieve details and status of a single pay-in order by either platform order number (orderNo) or merchant external order number (merchantOrderNo).

Route Parameters

orderNo (string): The platform order number (e.g., ORD20261011000001) or merchant external order number (e.g., MCH_PAYIN_20261011_001).

Response

Status Code: 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"
}

Tenant Isolation

Querying an order belonging to another merchant returns 404 Not Found (ORDER_NOT_FOUND) to prevent order number probing.

5. Lifecycle Status Matrix

Status	Name	Description	Terminal?
`PENDING_MATCH`	Matching Trader	Finding the best available liquidity provider	No
`PENDING_PAYMENT`	Awaiting Payment	Buyer can view recipient bank details on the checkout page	No
`PAYMENT_SUBMITTED`	Paid	Buyer clicked "I Have Paid", awaiting trader verification	No
`PENDING_RELEASE`	Awaiting Release	Trader confirmed fiat receipt, unlocking crypto settlement	No
`SETTLING`	Settling	Ledger split and account transfers executing	No
`COMPLETED`	Completed	Crypto settled to merchant balance; triggers Webhook	Yes
`CANCELLED`	Cancelled	Expired or cancelled before payment	Yes
`DISPUTED`	Disputed	Payment issue reported; escalated to operator review	No
`FAILED`	Failed	Settlement aborted or arbitrated cancel	Yes

Fiat Pay-in (Deposit) ​

1. Sequence Flow ​

2. Create Pay-in Order ​

Headers ​

Body Parameters ​

Request Example ​

Response ​

Key Fields ​

3. List Pay-in Orders ​

Request Headers ​

Query Parameters ​

Request Examples ​

Response ​

4. Query Order Details ​

Route Parameters ​

Response ​

5. Lifecycle Status Matrix ​

Fiat Pay-in (Deposit)

1. Sequence Flow

2. Create Pay-in Order

Headers

Body Parameters

Request Example

Response

Key Fields

3. List Pay-in Orders

Request Headers

Query Parameters

Request Examples

Response

4. Query Order Details

Route Parameters

Response

5. Lifecycle Status Matrix