代付

API 说明

使用代付 API 向用户转账

接口信息

• 接口 URL: POST /v2/payout
• Content-Type: application/json
• 认证: 需要在 Header 中传递 app-id 和签名验证

请求头参数

参数	类型	是否必需	描述
app-id	string	是	商户应用 ID
Content-Type	string	是	application/json

请求参数

参数	类型	是否必需	描述
sign	string	是	请求签名
amount	string	是	代付金额
currency	string	是	货币类型（如 USD、USDT）
outTradeNo	string	是	商户订单号，必须唯一
payChannel	string	是	支付渠道名称（如 xpay）
currencyId	string	是	特定代币的货币 ID
receiver	string	是	接收方地址（settlement 通道：钱包地址格式如 0x...，其他通道：手机号格式如 +86-43483243）
extra	object	否	扩展参数

扩展参数说明

参数	类型	是否必需	默认值	描述
description	string	否	"payout transaction"	交易描述
memo	string	否	""	交易备注

响应参数

成功响应

{
    "code": 0,
    "data": {
        "order_no": "1754377439308531400",
        "status": "success",
        "extra": {
        }
    },
    "msg": "success"
}

错误响应

{
    "code": 7,
    "data": {},
    "msg": "insufficient token balance"
}

请求示例

cURL 示例

curl -X POST "/v2/payout" \
  -H "Content-Type: application/json" \
  -H "app-id: your-app-id" \
  -d '{
    "sign": "c2lnbmF0dXJlX3Rlc3Q=",
    "amount": "1",
    "currency": "USD",
    "outTradeNo": "wendjfdsj",
    "payChannel": "xpay",
    "currencyId": "P575ItNeMxM6fy6zhbnrlezYlvQnHMLZ",
    "receiver": "0xB0c5852ff023291D0de6333c9155b2f884368559",
    "extra": {}
  }'

响应字段说明

成功响应字段

字段	类型	描述
code	integer	响应代码，0 表示成功
data	object	响应数据
data.order_no	string	系统生成的订单号
data.status	string	交易状态（pending、confirmed、failed）
data.extra	object	额外的交易信息
msg	string	响应消息

错误响应字段

字段	类型	描述
code	integer	错误代码
data	object	错误响应的空对象
msg	string	错误消息描述

错误代码

代码	描述
0	成功
7	代币余额不足

重要说明

1. 签名验证：所有请求必须在 sign 参数中包含有效签名
2. 唯一订单号：每个代付请求的 outTradeNo 必须唯一
3. 地址验证：确保 receiver 地址对指定货币有效
4. 余额检查：在发起代付前验证余额是否充足
5. 交易监控：使用返回的 txHash 在区块链上监控交易状态

有关支持的渠道和货币的完整列表，请参阅渠道和货币 API。

---

代付订单查询

API 说明

使用此 API 查询代付订单的状态和详细信息。

接口信息

• 接口 URL: POST /v2/queryPayOutOrder
• Content-Type: application/json
• 认证: 需要在 Header 中传递 app-id 和签名验证

请求头参数

参数	类型	是否必需	描述
app-id	string	是	商户应用 ID
Content-Type	string	是	application/json

请求参数

参数	类型	是否必需	描述
sign	string	是	请求签名
outTradeNo	string	是	商户订单号

响应参数

成功响应

{
    "code": 0,
    "data": {
        "merchantId": 2,
        "appId": "app-caf118dc-4e23-4ced-ab23-8a3f65d5071a",
        "merchantOrderNo": "wendjfdsj",
        "orderNo": "1752664386848723000",
        "channelName": "xpay",
        "tokenSymbol": "USD",
        "tokenCount": "1",
        "tokenFeeCount": "",
        "currencyId": "P575ItNeMxM6fy6zhbnrlezYlvQnHMLZ",
        "payHash": "",
        "transactionID": "",
        "receiver": "0xB0c5852ff023291D0de6333c9155b2f884368559",
        "state": "DONE_PAYMENT",
        "extra": "{\"channel_pay_type\":\"cards\",\"description\":\"xxxx\"}",
        "payTime": 0
    },
    "msg": "success"
}

错误响应

{
    "code": 7,
    "data": {},
    "msg": "invalid order"
}

请求示例

cURL 示例

curl -X POST "/v2/queryPayOutOrder" \
  -H "Content-Type: application/json" \
  -H "app-id: your-app-id" \
  -d '{
    "sign": "cxxnbmF0dXJlX3Rlc3Q=",
    "outTradeNo": "12344545"
  }'

响应字段说明

成功响应字段

字段	类型	描述
code	integer	响应代码，0 表示成功
data	object	响应数据
data.merchantId	integer	商户 ID
data.appId	string	应用 ID
data.merchantOrderNo	string	商户订单号
data.orderNo	string	系统生成的订单号
data.channelName	string	支付渠道名称
data.tokenSymbol	string	代币符号（如 USD、USDT）
data.tokenCount	string	代币数量
data.tokenFeeCount	string	手续费金额
data.currencyId	string	货币 ID
data.payHash	string	支付交易哈希
data.transactionID	string	交易 ID
data.receiver	string	接收方钱包地址
data.state	string	订单状态（PENDING、DONE_PAYMENT、FAILED）
data.extra	string	附加信息，JSON 字符串格式
data.payTime	integer	支付时间戳
msg	string	响应消息

错误响应字段

字段	类型	描述
code	integer	错误代码
data	object	错误响应的空对象
msg	string	错误消息描述

订单状态值

状态	描述
PENDING	订单待处理
DONE_PAYMENT	支付完成
FAILED	支付失败

错误代码

代码	描述
0	成功
7	无效订单或订单未找到

重要说明

1. 签名验证：所有请求必须在 sign 参数中包含有效签名
2. 订单查询：使用创建代付订单时相同的 outTradeNo 进行查询
3. 状态监控：检查 state 字段以确定代付的当前状态
4. 交易哈希：payHash 字段包含区块链交易哈希（如果可用）