1. Authentication

1.1 Get Token

➡️

The API is used to obtain the token, which is set on the request header. The token expires after one hour. You can get a new token before it expires or get a new token for requests.

URI

POST /payout/oauth/token

Body Param

REQUEST BODY SCHEMA: application/JSON

Body Json Demo

json
{ "secretKey": "xxxxxxxxxxxxxx","appKey":"xxxxxxxxx" }

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

json
{ "status": "1", "data": "xxxxxxxxxxxxxx" }

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "bad request, appkey not exist, please contact sales@xcurrency.com" }

1.2 Check

➡️

The API is used to verify the sign data, will return true when the sign data is correct, and will return 10001 when the sign method error.

URI

POST /payout/encrypt/check

Body Params

Encrypted object, not necessarily dictionary type

Body Json Demo

json
{ "a": "xxxxxxxxxxxxxx" , "b":"xxxxxx","c":{"d":"xxxxxx"}}

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

json
{ "status": "1", "data": true }

Response Status: 400, Body Json Demo

json
{ "status": "10001", "message": "Failed to verify the signature" }

2. Rate Manager

2.1 Get a rate

💡

The API is used to get the currency rate.

URI

POST /global/payout/rate/query/price

Body Params

Body Json Demo

json
{
  "sourceCurrency": "USD",
  "targetCurrency": "CNY"
}

Name

Type

Required

Description

sourceCurrency

string

Required

Currency you are sending

targetCurrency

string

Required

Target currency

Response

Name

Type

Required

Description

data

object

Conditional Required

data → queryNo

string

Conditional Required

data → rate

number

Conditional Required

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

javascript
{ "status": "1", "data": {"queryNo":"3052feb9a5924f7d8fe463c48a353dff", "rate": 6.3366} }

Response Status: 400, Body Json Demo

javascript
{ "status": "-1", "message": "bad request, error message" }

3. Order Manager

➡️

This part of the API is designed to improve your order management, including Creating, Querying, and Updating……

3.1 Transfer Create

➡️

The API is used to create a payment on xCurrency hubs, so 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 traded, the payment failed on xCurrency Hubs' side. Please check the response message or contact xCurrency Hubs' team.

POST /global/payout/transfer/create

Body Param

Body Json Demo

Global Payout Create Order Table

Name

Type

Description

orderNo

string

256

Merchant Unique Order No

lockRate

boolean

queryNo

string

256

purpose

string

256

Purpose of remittance Enum: - Salary - Family Support - Payroll - Goods - Service - Tuition - Insurance - Travel - Rent - Living Go here to see the detailed description of the purpose code.

subpurpose

string

256

Sub Purpose of remittance 1. when the purpose is Goods: - CLOTHES_BAGS_SHOES_CLOTHES - DAILY_SUPPLIES_AND_COSMETICS - ELECTRONICS_AND_HOME_APPLIANCES - TOYS_KIDS_BABIES 2. when the purpose is Service: - INTERPRETATION_SERVICE - TRANSLATION_SERVICE - HUMAN_RESOURCE_SERVICE - ESTATE_AGENCY_SERVICE - SOFTWARE_DEVELOPMENT_SERVICE - WEB_DESIGN_OR_DEVELOPMENT_SERVICE - DRAFTING_LEGAL_SERVICE - LEGAL_RELATED_CERTIFICATION_SERVICE - ACCOUNTING_SERVICE TAX_SERVICE - ARCHITECTURAL_DECORATION_DESIGN_SERVICE - ADVERTISING_SERVICE MARKET_RESEARCH_SERVICE - EXHIBITION_BOOTH_SERVICE - OTHER_SERVICE

fundsSource

string

256

Source of funds Enum - Business income - Employment income - Part-time income - Saving deposits

relationship

string

256

The relationship with payer and beneficiary

sourceAmount

float

256

sourceCurrency

string

targetAmount

float

256

targetCurrency

string

beneficiary

object

Details for the beneficiary . If beneficiaryId provided then beneficiary should be empty

beneficiary → fullName

string

256

beneficiary → firstName

string

256

beneficiary → lastName

string

256

beneficiary → accountInfo

object

Beneficiary Account Info

beneficiary → accountType

string

- bank - alipay - wechat

beneficiary → accountInfo → name

string

256

Account Name

beneficiary → accountInfo → bankName

string

256

Account Bank Name

beneficiary → accountInfo → currency

string

Account Currency

beneficiary → accountInfo → number

string

256

Account Number

beneficiary → accountInfo → address

string

256

Account Address

beneficiary → accountInfo → routingType

string

256

- Enum - bsb - swift - sort - ifsc - aba - alipay - wechat

beneficiary → accountInfo → routingValue

string

256

When the routingType is not empty

beneficiary → entityType

string

I : Individual B: Business

beneficiary → idNumber

string

256

Certificate number

beneficiary → idType

string

256

- Enum - idcard - passport - driver - residence - workpermit - other

beneficiary → nationality

string

Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)

beneficiary → phoneCode

string

beneficiary → phoneNumber

string

256

beneficiary → email

string

256

beneficiay → gender

string

required once the entityType is Individual - Enum - Male - FeMale

beneficiary → address

object

beneficiary → address → state

string

256

beneficiary → address →city

string

256

beneficiary → address → address

string

256

beneficiary → address → street

string

256

beneficiary → address → postCode

string

256

beneficiary → address → country

string

Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)

beneficiary → address → district

string

256

beneficiary → occupation

string

256

beneficiary → idIssueDate

string

256

Certificate Issue Date (format YYYY-MM-DD)

beneficiary → idExpiryDate

string

256

Certificate Deadline (Format YYYY-MM-DD)

beneficiaryId

string

256

If you know the id of your beneficiary in advance, then you can submit all the information instead

payer

object

Details for the payer . If payerId provided then payer should be empty

payer→ firstName

string

256

payer → lastName

string

256

payer → fullName

string

256

payer → nationality

string

Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → phoneNumber

string

256

payer → phoneCode

string

payer → email

string

256

payer → idNumber

string

256

Certificate number

payer → idType

string

256

- Enum - idcard - passport - driver - residence - workpermit - other

payer → idCountry

string

Country of Certificate (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → idIssueDate

string

256

Certificate Issue Date (format YYYY-MM-DD)

payer → idExpiryDate

string

256

Certificate Deadline (Format YYYY-MM-DD)

payer → gender

string

- Enum - Male - FeMale

payer → entityType

string

I : Individual B: Business

payer → dob

string

Date of Birth (Format YYYY-MM-DD)

payer → reference

string

Reference from payer to beneficiary

payer → address

object

payer → address → state

string

256

payer → address → city

string

256

payer → address → street

string

256

payer → address → postCode

string

256

payer → address → address

string

256

Full residential address

payer → address → country

string

Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → accountInfo

object

payer → accountInfo → number

string

256

payer → accountInfo → bankName

string

256

payer → occupation

string

256

payerId

string

256

If you know the id of your payer in advance, then you can submit all the information instead

logisticsCompany

string

256

logisticsNumber

string

256

paymentType

string

Enum - DepositPayment - FullPayment - FinalPayment

transactionMode

string

256

Enum - cnyMode - originalMode - crossMode

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

json
{ "status": "1", "data": {"tradeId":"xxxxxxx","status":"pending_material"} }

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "Risk Control" }

3.2 Transfer Update

➡️

The API is used to update the order info when the order information is wrong

POST /global/payout/transfer/update

Body Param

Body Json Demo

Global Payout Create Order Table (1)

Name

Type

Description

orderNo

string

256

Merchant Unique Order No

lockRate

boolean

queryNo

string

256

purpose

string

256

Purpose of remittance Enum: - Salary - Family Support - Payroll - Goods - Service - Tuition - Insurance - Travel - Rent - Living Go here to see the detailed description of the purpose code.

subpurpose

string

256

Sub Purpose of remittance (Only required when accountType is alipay) 1. when the purpose is Goods: - CLOTHES_BAGS_SHOES_CLOTHES - DAILY_SUPPLIES_AND_COSMETICS - ELECTRONICS_AND_HOME_APPLIANCES - TOYS_KIDS_BABIES 2. when the purpose is Service: - INTERPRETATION_SERVICE - TRANSLATION_SERVICE - HUMAN_RESOURCE_SERVICE - ESTATE_AGENCY_SERVICE - SOFTWARE_DEVELOPMENT_SERVICE - WEB_DESIGN_OR_DEVELOPMENT_SERVICE - DRAFTING_LEGAL_SERVICE - LEGAL_RELATED_CERTIFICATION_SERVICE - ACCOUNTING_SERVICE TAX_SERVICE - ARCHITECTURAL_DECORATION_DESIGN_SERVICE - ADVERTISING_SERVICE MARKET_RESEARCH_SERVICE - EXHIBITION_BOOTH_SERVICE - OTHER_SERVICE

fundsSource

string

256

Source of funds Enum - Business income - Employment income - Part-time income - Saving deposits

relationship

string

256

The relationship with payer and beneficiary

sourceAmount

float

256

sourceCurrency

string

targetAmount

float

256

targetCurrency

string

beneficiary

object

Details for the beneficiary . If beneficiaryId provided then beneficiary should be empty

beneficiary → fullName

string

256

beneficiary → firstName

string

256

beneficiary → lastName

string

256

beneficiary → accountInfo

object

Beneficiary Account Info

beneficiary → accountType

string

- bank - alipay - wechat

beneficiary → accountInfo → name

string

256

Account Name

beneficiary → accountInfo → bankName

string

256

Account Bank Name

beneficiary → accountInfo → currency

string

Account Currency

beneficiary → accountInfo → number

string

256

Account Number

beneficiary → accountInfo → address

string

256

Account Address

beneficiary → accountInfo → routingType

string

256

- Enum - bsb - swift - sort - ifsc - aba - alipay - wechat

beneficiary → accountInfo → routingValue

string

256

When the routingType is not empty

beneficiary → entityType

string

I : Individual B: Business

beneficiary → idNumber

string

256

Certificate number

beneficiary → idType

string

256

- Enum - idcard - passport - driver - residence - workpermit - other

beneficiary → nationality

string

Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)

beneficiary → phoneCode

string

beneficiary → phoneNumber

string

256

beneficiary → email

string

256

beneficiay → gender

string

required once the entityType is Individual - Enum - Male - FeMale

beneficiary → address

object

beneficiary → address → state

string

256

beneficiary → address →city

string

256

beneficiary → address → address

string

256

beneficiary → address → street

string

256

beneficiary → address → postCode

string

256

beneficiary → address → country

string

Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)

beneficiary → address → district

string

256

beneficiary → occupation

string

256

beneficiary → idIssueDate

string

256

Certificate Issue Date (format YYYY-MM-DD)

beneficiary → idExpiryDate

string

256

Certificate Deadline (Format YYYY-MM-DD)

beneficiaryId

string

256

If you know the id of your beneficiary in advance, then you can submit all the information instead

payer

object

Details for the payer . If payerId provided then payer should be empty

payer→ firstName

string

256

payer → lastName

string

256

payer → fullName

string

256

payer → nationality

string

Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → phoneNumber

string

256

payer → phoneCode

string

payer → email

string

256

payer → idNumber

string

256

Certificate number

payer → idType

string

256

- Enum - idcard - passport - driver - residence - workpermit - other

payer → idCountry

string

Country of Certificate (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → idIssueDate

string

256

Certificate Issue Date (format YYYY-MM-DD)

payer → idExpiryDate

string

256

Certificate Deadline (Format YYYY-MM-DD)

payer → gender

string

- Enum - Male - FeMale

payer → entityType

string

I : Individual B: Business

payer → dob

string

Date of Birth (Format YYYY-MM-DD)

payer → reference

string

Reference from payer to beneficiary

payer → address

object

payer → address → state

string

256

payer → address → city

string

256

payer → address → street

string

256

payer → address → postCode

string

256

payer → address → address

string

256

Full residential address

payer → address → country

string

Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → accountInfo

object

payer → accountInfo → number

string

256

payer → accountInfo → bankName

string

256

payer → occupation

string

256

payerId

string

256

If you know the id of your payer in advance, then you can submit all the information instead

logisticsCompany

string

256

logisticsNumber

string

256

paymentType

string

Enum - DepositPayment - FullPayment - FinalPayment

transactionMode

string

256

Enum - cnyMode - originalMode - crossMode

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

json
{ "status": "1", "data": {"tradeId":"xxxxxxx","status":"pending_material"} }

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "Risk Control" }

3.3 Query Order Status

➡️

This API is used to query the order status

URI

POST /global/payout/transfer/query/status

Body Params

Body Json Demo

json
{
  "tradeId": "string",
  "fileBase64": "string",
  "fileName": "string"
}

Response

Response Status: 200, Body Json Demo

json
{ "status": "1" , "data":{"status":"pending","tradeId":"xxxxxxxx"}}

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

3.4 Notification

➡️

host: xxxxxxxxx , xxxxxxxx is your callback URL; the xCurrency Hubs will be notified back at xxxxxxxx/xcurrency/webhook. Need to IP allowlist if you have a limit.

URI

POST /xxxxxxxx

Headers

appkey: xCurrency Hubs' appkey is used for secondary verification and is not required.

Body Params

Body Json Demo

json
{
  "event": "payment",
  "id": "*****",
  "status":"pending",
  "amount":"100",
  "targetAmount":"100",
  "sourceAmount":,"100",
  "message":"related error messages"
}

Response

Return JSON data

Response Status: 200, Body Json Demo

javascript
{ "code": "200", "message": ""}

Response Status: 400, Body Json Demo

javascript
{ "status": "-1", "message": "bad request, error message" }

3.5 Async confirm transfer

➡️

This API is used to send CNY to the beneficiary's bank account, support concurrency.

URI

POST /global/payout/transfer/async

Body Params

Body Json Demo

json
{
  "tradeId": "string",
  "fileBase64": "string",
  "fileName": "string"
}

Response

Response Status : 200, Body Json Demo

json
{ "status": "1" }

Response Status : 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

4. Balance

4.1 New FX-Conversion

URI

GET /global/payout/wallet/new-fx-conversion

Body Params

Body Json Demo

json
{
  "sourceCurrency": "USD",
  "targetCurrency": "EUR",
  "sourceAmount": 100.00,  // Conditionally required if targetAmount is not provided
  // "targetAmount": 120.00, // Conditionally required if sourceAmount is not provided
  "queryNo": "Q123456789",
  "walletType": "personal" // Can be 'personal' or 'business'
}

Parameter Name	Data Type	Required	Description
sourceCurrency	string	Required	The currency code from which the amount is to be converted.
targetCurrency	string	Required	The currency code to which the amount is to be converted.
sourceAmount	float	Conditional
targetAmount	float	Conditional
queryNo	string	Required	A unique identifier for the exchange rate, obtained from /global/payout/rate/query/price.
walletType	string	Required	Enumerated type specifying the wallet type where the converted funds should be placed. Valid values are `personal` or `business`.

Responses

Field Name	Data Type	Description
status	string	Indicates the success or failure of the request.
data.convertedAmount	float
data.transactionId	string
data.walletType	string	Enumerated type specifying the wallet type where the converted funds should be placed. Valid values are personal or business.

Response Status: 200, Body Json Demo

json
{"status": "1",
	"data": {
  "success": true,
  "convertedAmount": 90.00,
  "transactionId": "txn_123456789",
  "walletType": "personal"
}}

Response Status: 400, Body Json Demo

json
{
  "status": "-1",
  "message": "Insufficient balance, invalid query number, or unsupported wallet type"
}

4.2 Get All balance-transaction

URI

GET /global/payout/wallet/list

Responses

Field Name	Data Type	Description
status	String	Indicates the success or failure of the request. 1 : Success -1: Error
data	Array	An array of objects, each representing a transaction.
data[].walletId	String	Unique identifier for the wallet.
data[].currency	String
data[].amount	String	Available balance
data[].totalAmount	String	Total balance = available + in transit
data[].type	String	Wallet type: personal/business

Response Status: 200, Body Json Demo

json
{
    "status": "1",
    "data": [
        {
            "walletId": "88a964fd844145ba9b75b41a379338a2",
            "currency": "CNY",
            "amount": 999999984354.33,
            "totalAmount": 999999984354.33,
            "type": "personal"
        },
        {
            "walletId": "18e27e788b424ffc8a8ad6545fceef1f",
            "currency": "CNY",
            "amount": 235912.57,
            "totalAmount": 236543.14,
            "type": "business"
        }
    ]
}

Response Status: 400, Body Json Demo

json
{
  "status": "-1",
  "message": "No wallet found in this currency"
}

4.3 Balance for single wallet type

💡

Get balance information by wallet type

URI

GET /global/payout/wallet/get

Query Params

Response

Response Status : 200, Body Json Demo

javascript
{
    "status": "1",
    "data": {
        "walletId": "e721012551af4859a2bc41a74554ade2",
        "currency": "CNY",
        "amount": 235912.57,
        "totalAmount": 236543.14,
        "type": "business"
    }
}

Response Status : 400, Body Json Demo

javascript
{
    "status": "-1",
    "message": "Unsupported wallet type"
}

5. Online Validation

5.1 Query Chinese Hanzi Character Information

URI

GET /global/payout/validation/query-chinese-characters

Body Params

Body Json Demo

json
{
  "pinyinName": "Zhang San",
  "idNumber": "123456789012345678"
}

Parameter Name	Data Type	Required	Description
pinyinName	string	Yes	The pinyin transcription of the Chinese name.
idNumber	string	Conditional	Personal ID number (required for individuals).
uionSocialCreditCode	string	Conditional	Busiess entity union social credit code (required for business entity). The Unified Social Credit Code (USCC) is a unique, 18-digit national business registration number issued to all businesses and other entities in China.

Responses

Field Name	Data Type	Description
status	string	Indicates the success or failure of the request. 1 : Success -1: Error
data.pinyinName	string	The Pinyin name used in the query.
data.idNumber	string	The ID number used in the query.
data.hasChineseCharacters	boolean	True if Chinese characters exist for the query; otherwise, false.
data.chineseCharacters	string	The Chinese characters corresponding to the input Pinyin name, if available.

Response Status: 200, Body Json Demo

json
{
  "status": "1",
  "data": {
    "hasChineseCharacters": true,
    "chineseCharacters": "张三",
    "entityType": "individual", // or "business"
    "additionalInfo": {
      "lastUpdated": "2024-08-15T12:34:56Z"
    }
  }
}

Response Status: 400, Body Json Demo

json
{
  "status": "-1",
  "message": "Invalid parameters provided or no data found for the given identifiers."
}

5.2 User Information Validation for 3/4 Key Elements

URI

POST /payout/common/bank/check

Body Params

Body Json Demo

json
{
    "type": "check4",
    "name": "李明",
    "idNumber": "320311199912123574",
    "account": "621529383736101111",
    "phone": "1234567890"
}

Parameter Name	Data Type	Required	Description
type	string	Yes	The type you want to check. Example: Three elements "check3", four elements "check4”.
idNumber	string	Yes	Personal ID number.
name	string	Yes	Personal names.
account	string	Yes	Personal collection bank account number.
phone	string	Conditional	Personal phone number. If type is check3, it is not required

Responses

Field Name	Data Type	Description
status	string	Indicates the success or failure of the request. 1 : verify successfully -1 : There are required fields left unfilled 10028 ：verify failed
data	string	The details of the verify result.

Response Status: 200, Body Json Demo

json
{
    "status": "1",
    "data": "验证通过"
}

Response Status: 400, Body Json Demo

json
{
    "status": "10028",
    "message": "验证不通过，身份信息或手机号输入不正确"
}

6. Support Docs

6.1 Docs Upload

➡️

Upload supporting material order by Multipart

URI

POST /global/payout/transfer/upload/multipart

Form Data Params

Form Data Demo

shell
--form 'file=@"filepath"' \
--form 'fileName="filename.png"' \
--form 'type="proforma_invoice"' \
--form 'tradeId="ba9f9c00b4cb4655a912c3d7cfdd3afc"'

Response

Response Status: 200, Body Json Demo

json
{ "status": "1" }

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

6.2 Upload Completed

➡️

Completed uploading supporting material for business order

URI

POST /global/payout/transfer/upload/completed

Body Params

Body Json Demo

json
{
  "tradeId": "string"
}

Response

Response Status: 200, Body Json Demo

json
{ "status": "1" , "data":{"status":"pending","tradeId":"xxxxxxxx"}}

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

API Reference

1. Authentication

1.1 Get Token

1.2 Check

2. Rate Manager

2.1 Get a rate

3. Order Manager

3.1 Transfer Create

3.2 Transfer Update

3.3 Query Order Status

3.4 Notification

3.5 Async confirm transfer

4. Balance

4.1 New FX-Conversion

4.2 Get All balance-transaction

4.3 Balance for single wallet type

5. Online Validation

5.1 Query Chinese Hanzi Character Information

5.2 User Information Validation for 3/4 Key Elements

6. Support Docs

6.1 Docs Upload

6.2 Upload Completed