PayOut

API description

use payout api to transfer currency to user

Interface Information

• Interface URL: POST /v2/payout
• Content-Type: application/json
• Authentication: Need to pass app-id and signature verification in Header

Request Header Parameters

Parameter	Type	Required	Description
app-id	string	Yes	Merchant Application ID
Content-Type	string	Yes	application/json

Request Parameters

Parameter	Type	Required	Description
sign	string	Yes	Request signature
amount	string	Yes	Payout amount
currency	string	Yes	Currency type (e.g., USD, USDT)
outTradeNo	string	Yes	Merchant order number, must be unique
payChannel	string	Yes	Payment channel name (e.g., xpay)
currencyId	string	Yes	Currency ID for the specific token
receiver	string	Yes	Recipient address (Settlement channel: wallet address format like 0x..., Other channels: phone number format like +86-43483243)
extra	object	No	Extended parameters

Extra Parameter Description

Parameter	Type	Required	Default Value	Description
description	string	No	"payout transaction"	Transaction description
memo	string	No	""	Transaction memo or note

Response Parameters

Success Response

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

Error Response

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

Request Examples

cURL Example

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": {}
  }'

Response Field Description

Success Response Fields

Field	Type	Description
code	integer	Response code, 0 indicates success
data	object	Response data
data.order_no	string	System generated order number
data.status	string	Transaction status (pending, confirmed, failed)
data.extra	object	Additional transaction information
msg	string	Response message

Error Response Fields

Field	Type	Description
code	integer	Error code
data	object	Empty object for error responses
msg	string	Error message description

Error Codes

Code	Description
0	Success
7	Insufficient token balance

Important Notes

1. Signature Verification: All requests must include a valid signature in the sign parameter
2. Unique Order Numbers: The outTradeNo must be unique for each payout request
3. Address Validation: Ensure the receiver address is valid for the specified currency
4. Balance Check: Verify sufficient balance before initiating payout
5. Transaction Monitoring: Use the returned txHash to monitor transaction status on blockchain

For the complete list of supported channels and currencies, please refer to the Channel and Currency API.

---

Query PayOut Order

API Description

Use this API to query the status and details of a payout order.

Interface Information

• Interface URL: POST /v2/queryPayOutOrder
• Content-Type: application/json
• Authentication: Need to pass app-id and signature verification in Header

Request Header Parameters

Parameter	Type	Required	Description
app-id	string	Yes	Merchant Application ID
Content-Type	string	Yes	application/json

Request Parameters

Parameter	Type	Required	Description
sign	string	Yes	Request signature
outTradeNo	string	Yes	Merchant order number

Response Parameters

Success Response

{
    "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"
}

Error Response

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

Request Examples

cURL Example

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

Response Field Description

Success Response Fields

Field	Type	Description
code	integer	Response code, 0 indicates success
data	object	Response data
data.merchantId	integer	Merchant ID
data.appId	string	Application ID
data.merchantOrderNo	string	Merchant order number
data.orderNo	string	System generated order number
data.channelName	string	Payment channel name
data.tokenSymbol	string	Token symbol (e.g., USD, USDT)
data.tokenCount	string	Token amount
data.tokenFeeCount	string	Fee amount
data.currencyId	string	Currency ID
data.payHash	string	Payment transaction hash
data.transactionID	string	Transaction ID
data.receiver	string	Recipient wallet address
data.state	string	Order status (PENDING, DONE_PAYMENT, FAILED)
data.extra	string	Additional information in JSON string format
data.payTime	integer	Payment timestamp
msg	string	Response message

Error Response Fields

Field	Type	Description
code	integer	Error code
data	object	Empty object for error responses
msg	string	Error message description

Order Status Values

Status	Description
PENDING	Order is pending processing
DONE_PAYMENT	Payment completed successfully
FAILED	Payment failed

Error Codes

Code	Description
0	Success
7	Invalid order or order not found

Important Notes

1. Signature Verification: All requests must include a valid signature in the sign parameter
2. Order Lookup: Use the same outTradeNo that was used when creating the payout order
3. Status Monitoring: Check the state field to determine the current status of the payout
4. Transaction Hash: The payHash field contains the blockchain transaction hash when available