跳转到主要内容

​
概述

换汇服务支持以下场景：
  • 收款后换汇：将收到的款项转换为结算币种
  • 统一结算币种：以单一币种维护账户余额
  • 余额再平衡：优化各账户之间的币种分布
For 请求头, 签名规则, and 回调 verification, refer to 认证与安全.

​
接入流程

标准换汇流程如下： 
Query tradable scope → Get quote → Create swap order → Query result
下文将对每一步进行详细说明。

​
第一步：查询可交易币种范围（可选）

接口: GET /v1/pay/convert/currency Retrieves the list of currencies available for conversion. This step is optional but recommended for user interface initialization and validation.

​
Query 参数

参数类型必填说明
sidestringNoFilter by buy or sell direction

​
响应 字段

The response includes available currencies with precision and amount constraints:
  • minBuyAmount: Minimum buy amount (field precision rules apply)
  • maxBuyAmount: Maximum buy amount (field precision rules apply)
  • minSellAmount: Minimum sell amount (field precision rules apply)
  • maxSellAmount: Maximum sell amount (field precision rules apply)

​
步骤 2: Query Available 币种 Pairs (Optional)

接口: GET /v1/pay/convert/pair Retrieves supported trading pairs and exchange rate information.

​
Query 参数

参数类型必填说明
currencystringNoFilter pairs by base currency
sidestringNoFilter by buy or sell direction

​
步骤 3: Get Quote

接口: POST /v1/pay/convert/preview Generates a 报价 for currency conversion. The 报价 includes an expiration timestamp; expired 报价s cannot be used for 订单 creation.

​
请求 参数

字段类型必填说明
buyCurrencystringYesTarget currency to buy
sellCurrencystringYesSource currency to sell
buyAmountstringConditionalAmount to buy (mutually exclusive with sellAmount)
sellAmountstringConditionalAmount to sell (mutually exclusive with buyAmount)
Note: Provide either buyAmount or sellAmount, but not both.

​
响应 字段

字段类型说明
quoteIdstringUnique 报价 identifier; required for 订单 creation
exchangeRatestringCurrent exchange rate
buyAmountstringAmount in target currency
sellAmountstringAmount in source currency
expirationTimetimestampQuote expiration timestamp

​
步骤 4: Create Swap Order

接口: POST /v1/pay/convert Creates a currency conversion 订单 using a valid 报价. This endpoint is idempotent: submitting the same clientReqId multiple times will return the same business result.

​
请求 参数

字段类型必填说明
quoteIdstringYesQuote ID from 步骤 3
buyCurrencystringYesTarget currency
sellCurrencystringYesSource currency
buyAmountstringYesAmount to buy
sellAmountstringYesAmount to sell
clientReqIdstringYes商户-generated unique request ID for 幂等性

​
响应 字段

字段类型说明
orderIdstringPlatform 订单 number for queries
clientReqIdstringEchoed from request
statusstringInitial 订单 status (typically processing)
buyAmountstringFinal buy amount
sellAmountstringFinal sell amount

​
Example 请求

{
  "quoteId": "QUOTE_abc123",
  "buyCurrency": "BTC",
  "sellCurrency": "USDT",
  "buyAmount": "0.5",
  "sellAmount": "21500",
  "clientReqId": "SWAP_20240101_001"
}

​
步骤 5: Query Swap Order

接口: GET /v1/pay/convert/order Queries the status and details of a swap 订单. Supports multiple query keys for flexibility.

​
Query 参数

参数类型必填说明
orderIdstringConditionalPlatform 订单 number
clientReqIdstringConditional商户-generated request ID
Note: Provide either orderId or clientReqId (not both required, but at least one).

​
响应 字段

字段类型说明
orderIdstringPlatform 订单 number
clientReqIdstring商户 request ID
statusstringOrder status (see enumeration below)
buyCurrencystringTarget currency
sellCurrencystringSource currency
buyAmountstringFinal buy amount
sellAmountstringFinal sell amount
completionTimetimestampOrder completion timestamp

​
Swap Order 状态 Enumeration

状态说明
processingOrder is being processed; check back later
successConversion completed successfully; 资金 are now in the account
failureConversion failed; 资金 returned to original account

​
Retry and Error 处理方式

​
处理方式 Uncertain 响应

If a network timeout or uncertain response occurs:
  1. Query first: Use GET /v1/pay/convert/order with clientReqId or orderId to determine final status
  2. Only 重试 if necessary: Only reuse the same clientReqId for 订单 creation if the query result remains uncertain
  3. Preserve 幂等性: Keep clientReqId unchanged to ensure the same business result

​
Common Failure Scenarios

Failure Reason说明Resolution
Insufficient balanceAccount does not have enough 资金 in sell currencyFund the account or reduce sell amount
Unsupported trading pair币种 pair is not availableUse a different currency pair
Expired 报价Quote lifetime has elapsedGenerate a new 报价 using POST /v1/pay/convert/preview
Invalid quantity precisionAmount does not match currency precision rulesAdjust amount to match precision requirements
Amount limit exceededAmount exceeds currency limitsReview limits via GET /v1/pay/convert/currency

​
回调 Behavior

The swap capability does not provide 异步 回调s. Final 订单 confirmation must be obtained through the query API (GET /v1/pay/convert/order). For information on 回调s for other products, see 通知 & 回调.

​
机构 API Integration

For institutional use cases, swap endpoints are available under the institution namespace:
CapabilityStandard 接口Institution 接口
Create swap 订单POST /v1/pay/convertPOST /transfer/open/institution/v1/pay/convert
Query swap 订单GET /v1/pay/convert/orderGET /transfer/open/institution/v1/pay/convert/order
For complete institution API details, see 机构 API.

​
Error 处理方式

For comprehensive error codes and resolution steps, refer to 错误码 & 最佳实践.

​
Integration Checklist

  • Retrieve available currency pairs from GET /v1/pay/convert/pair
  • Implement 报价 retrieval with expiration handling
  • Generate unique clientReqId for each swap request
  • Create swap 订单s with valid 报价s
  • Implement query fallback for 订单 confirmation
  • Handle all failure scenarios gracefully
  • Store 订单 IDs for 对账
  • Monitor conversion rates and limits