Authentication
Get Token
The API is used to obtain
token, which is set on the request header. The token is expired after one hour, you can get the new token before the token expires or get a new token for requests.- URI
POST /payout/oauth/token
- Body Param
REQUEST BODY SCHEMA: application/json
Body Json Demo
Name
Type
Required
Description
appKey
string
Required
appkey; From xCurrency Hubs
secretKey
string
Required
secretKey; From xCurrency Hubs
- Response
Name
Type
Required
Description
data
string
Conditional Required
if the status is 1，the token is responded
status
string
Required
1 : Success
-1: Error
message
string
Conditional Required
if the status is -1，the err message is responded
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Check
The API is used to verify the sign data, will return
true when the sign data is correct, will return 10001 when the sign method error.- URI
POST /payout/encrypt/check
- Body Params
Encrypted object, not necessarily dictionary type
Body Json Demo
- Response
Name
Type
Required
Description
status
string
Required
1 : Success
10001: Failed to verify the signature
message
string
Conditional Required
if the status is 10001，the err message is responded
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Transfer
Create Transfer
The API is used to create a payment on xCurrency hubs, then orderNo should be unique, the same order number can create a payment once.
When the http status is
400 and the response data has not tradeId mean that the payment is created failure on xCurrency Hubs' side, please check the response message or contact with xCurrency Hubs' team.- URI
POST /payout/payment/business/transfer/create
- Body Param
Body Json Demo
Name
Type
Required
Description
orderNo
string
256
Required
Merchant Order No
transactionMode
string
32
Required
The transactionMode
Enum
- originalMode ; default
- cnyMode
- crossMode
sourceAmount
float
32
Required
Source Amount
sourceCurrency
string
3
Required
Source Currency
targetAmount
float
32
Required
Target Amount
targetCurrency
string
3
Required
Target Currency
paymentType
string
32
Conditional Required
Payment Type ; When the targetCurrency is CNY, the field is required.
Enum
- DepositPayment
- FullPayment
- FinalPayment
- Other
logisticsCompany
string
256
Conditional Required
Logistics company ;
When the targetCurrency is CNY and paymentType is fullPayment and FinalPayment, the field is required.
logisticsNumber
string
256
Conditional Required
Logistics Number ;
When the targetCurrency is CNY and paymentType is fullPayment and FinalPayment, the field is required.
payer
object
Required
The Payer
payer → fullName
string
256
Required
Full Name, Must be a business
payer → accountNumber
string
256
Optional
Bank Account Number, Must be a business account
payer → swiftCode
string
256
Optional
Bank Swift Code;
payer → address
object
Required
Address
payer → address → country
string
2
Optional
The country where the payer is located.Country code of the user (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → address → state
string
256
Optional
The state where the payer is located
payer → address → postCode
string
256
Optional
The postCode where the payer is located
payer → address → address
string
256
Conditional Required
The address where the payer is located;
When the targetCurrenncy is not CNY, the field is required.
beneficiary
object
Required
beneficiary → fullName
string
256
Required
Full Name, Must be a business
beneficiary → accountName
string
256
Required
Bank Account Number, It can be a business account or a personal account
beneficiary → accountNumber
string
256
Required
Bank Account Number
beneficiary → bankName
string
256
Conditional Required
Account bank, need to be specific to the branch；
When accountName is a business account, the field is required.
beneficiary → idNumber
string
256
Conditional Required
Chinese mainland resident ID card；
When the targetCurrency is CNY and accountName is a personal account, the field is required.
beneficiary → address
object
Required
beneficiary → address → country
string
2
Optional
The country where the beneficiary is located.Country code of the user (ISO 3166-1 two-digit code, e.g. CN, US, JP)
beneficiary → address → state
string
256
Optional
The state where the beneficiary is located
beneficiary → address → postCode
string
256
Optional
The postCode where the beneficiary is located
beneficiary → address → address
string
256
Conditional Required
When the targetCurrenncy is not CNY, the field is required.
beneficiary → swiftCode
string
Conditional Required
Bank Swift Code;
When the targetCurrenncy is not CNY, the field is required.
beneficiary → companyNumber
string
256
Conditional Required
Company incorporation number, Unified Social Credit Identifier;
When accountName is a business account, the field is required.
- Response
Name
Type
Required
Description
status
string
Required
1 : Success
Other status please reference appendix
message
string
Conditional Required
if the status is not 1，the err message is responded
data
object
Conditional Required
data - tradeId
string
256
Required
Uniqued id in the XC system
data - status
string
256
Required
string
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Async confirm transfer
This API is used to send CNY to the beneficiary's bank account, support concurrency.
- URI
POST /payout/payment/business/transfer/async
- Body Params
Body Json Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
queryNo
string
Conditional Required
When the sourceCurrency ≠ targetCurrency, field is required.
- Response
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Docs Upload
Upload File
Upload supporting material for business order
- URI
POST /payout/payment/business/transfer/upload
- Body Params
Body Json Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
fileBase64
string
Required
File base64 str
fileName
string
Required
File name
typestring
Required
File Type， proforma_invoice or purchase_order mush be provided
Enum:
- proforma_invoice
- purchase_order
- logistics_material
- export_declaration
- communication_record
- beneficiary_id_card
- beneficiary_power_attorney
- historical_transaction_material
- proof_purchase
- other
- Response
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Upload File By Multipart
Upload supporting material for business order by Multipart
- URI
POST /payout/payment/business/transfer/upload/multipart
- Form Data Params
Form Data Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
file
file
Required
File
fileName
string
Required
File name
typestring
Required
File Type， proforma_invoice or purchase_order mush be provided
Enum:
- proforma_invoice
- purchase_order
- logistics_material
- export_declaration
- communication_record
- beneficiary_id_card
- beneficiary_power_attorney
- historical_transaction_material
- proof_purchase
- other
- Response
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Upload Completed
Completed to upload supporting material for business order
- URI
POST /payout/payment/business/transfer/upload/completed
- Body Params
Body Json Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
- Response
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Query
Query a transfer status
This API is used to query the order status
- URI
GET /payout/payment/business/transfer/status
- Body Params
Body Json Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
- Response
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Name
Type
Required
Description
status
string
Required
1 : Success
-1: Error for System
message
string
Conditional Required
The tradeId is not existed
data
object
data → message
string
Required
if status is
failed rejected overrule , the message is the reason for the transfer failuredata → status
string
Required
Query a FX
This API is used to query the fx real time
- URI
GET /payout/payment/business/query/rate
- Body Params
Body Json Demo
Name
Type
Required
Description
sourceCurrency
string
Required
Currency you are sending; ex: USD、HKD、SGD
targetCurrency
string
Required
Target currency; ex: CNY
- Response
Response Status : 200, Body Json Demo
Response Status : 400, Body Json Demo
Name
Type
Required
Description
status
string
Required
1 : Success
-1: Error for System
message
string
Conditional Required
The tradeId is not existed
data
object
data → queryNo
string
Required
Uniqued query fx id in the XC system，expired for 15s
date → rate
float
Required
Real rate