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

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

Name

Type

Required

Description

tradeId

string

Required

Uniqued id in the XC system

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

Name

Type

Required

Description

event

string

Conditional Required

Enum - payment - balance

sourceCurrency

string

Conditional Required

Subject to the actual sourceAmount by transfer success, only exists if status is completed

targetCurrency

string

Conditional Required

Subject to the actual targetAmount by transfer success, only exists if status is completed

status

string

Conditional Required

Enum - pending - awaiting_transfer - bank_delay - pending_material - completed - failed - rejected - canceled

amount

string

Conditional Required

only exists if event is balance

tradeId

string

Conditional Required

Enum - payment: tradeId - balance: walletId

message

string

Conditional Required

related error messages

Response

Name

Type

Required

Description

code

object

Conditional Required

the value is 200 mean success, if on xCurrency hubs' side not receive the code of 200, will try to callback for 16 times within 2 hours

message

string

Conditional Required

error response message

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

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-all-balance-transaction

Body Params

Body Json Demo

json
{
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-09-10"
  },
  "walletType": "personal",
  "transactionType": ["deposit", "exchange"],
  "status": ["Success", "Ongoing"],
  "pagination": {
    "limit": 10,
    "page": 2
  }
}

Parameter Name	Data Type	Required	Description
dateRange	Object	Optional	An object containing start and end dates to filter transactions within a specific period.
dateRange.startDate	String	Optional	Specifies the start date for the transaction query in "YYYY-MM-DD" format.
dateRange.endDate	String	Optional	Specifies the end date for the transaction query in "YYYY-MM-DD" format.
walletType	String	Optional	Specifies the type of wallet (e.g., "personal", "business") from which the transactions are made. Enum - personal - business
transactionType	String	Optional	An enum specifying types of transactions to filter by (e.g., "deposit", "exchange"). Enum - deposit - exchange
status	String	Optional	An enum of transaction statuses to include in the results (e.g., "sSuccess", "oOngoing"). Enum - Any - Ongoing - Success - Failed - Cancelled.
pagination	Object	Optional	An object containing pagination settings.
pagination.limit	Integer	Optional	Specifies the number of transactions to return per page.
pagination.page	Integer	Optional	Specifies the page number to retrieve.

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[].transactionId	String	Unique identifier for the transaction.
data[].type	String	Type of the transaction, e.g., "exchange", "deposit".
data[].status	String	Current status of the transaction, e.g., "Success", "Ongoing".
data[].sourceCurrency	String	Currency from which the amount is being converted (only in exchange type transactions).
data[].targetCurrency	String	Currency to which the amount is being converted (only in exchange type transactions).
data[].sourceAmount	Float	Amount in the source currency being exchanged (only in exchange type transactions).
data[].convertedAmount	Float	Amount after conversion in the target currency (only in exchange type transactions).
data[].currency	String	Currency involved in the transaction (only in non-exchange type transactions).
data[].amount	Float	Amount involved in the transaction.
data[].walletType	String	Type of wallet involved in the transaction, e.g., "personal", "business".
data[].date	String	Date and time of the transaction in ISO 8601 format.
pagination	Object	Object containing pagination details.
pagination.currentPage	Integer	Current page number of the response data.
pagination.totalPages	Integer	Total number of pages available.
pagination.totalItems	Integer	Total number of items available across all pages.
pagination.itemsPerPage	Integer	Number of items per page.

Response Status: 200, Body Json Demo

json
{
  "status": "1",
  "data": [
    {
      "transactionId": "txn_123456789",
      "type": "exchange",
      "status": "Success",
      "sourceCurrency": "USD",
      "targetCurrency": "EUR",
      "sourceAmount": 100.00,
      "convertedAmount": 90.00,
      "walletType": "personal",
      "date": "2024-09-10T14:48:00Z"
    },
    {
      "transactionId": "txn_987654320",
      "type": "deposit",
      "status": "Ongoing",
      "currency": "USD",
      "amount": 200.00,
      "walletType": "business",
      "date": "2024-09-09T10:15:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 15,
    "totalItems": 150,
    "itemsPerPage": 10
  }
}

Response Status: 400, Body Json Demo

json
{
  "status": "-1",
  "message": "No transactions found or invalid query parameters"
}

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

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"'

Name

Type

Required

Description

tradeId

string

Required

Uniqued id in the XC system

file

Required

File

type

string

Required

File Type， Enum: - bill - offer - identification_front - identification_back - ME - MC - SIGN - HR - NCOM - BC - EC - POIPBE - COI - RSIBF - TC - 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

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

Name

Type

Required

Description

tradeId

string

Required

Uniqued id in the XC system

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

4. Balance

4.1 New FX-Conversion

4.2 Get All balance-transaction

5. Online Validation

5.1 Query Chinese Hanzi Character Information

6. Support Docs

6.1 Docs Upload

6.2 Upload Completed