logo

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

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
  • 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

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
      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
      Response Status: 400, Body Json Demo

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.
  • URI
      • POST /global/payout/transfer/create
  • Body Param
      • Body Json Demo
Global Payout Create Order Table
Name
Type
Required
Description
index
orderNo
string
256
Required
Merchant Unique Order No
100
lockRate
boolean
Required
200
queryNo
string
256
Required
300
purpose
string
256
Required
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.
400
subpurpose
string
256
Conditional Required
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
401
relationship
string
256
Optional
The relationship with payer and beneficiary
500
sourceAmount
float
256
Required
600
sourceCurrency
string
3
Required
700
targetAmount
float
256
Required
800
targetCurrency
string
3
Required
900
beneficiary
object
Conditional Required
Details for the beneficiary . If beneficiaryId provided then beneficiary should be empty
2000
beneficiary → accountInfo
object
Required
Beneficiary Account Info
2100
beneficiary → accountType
string
32
Required
- bank - alipay - wechat
2101
beneficiary → accountInfo → name
string
256
Required
Account Name
2110
beneficiary → accountInfo → bankName
string
256
Required
Account Bank Name
2120
beneficiary → accountInfo → currency
string
3
Required
Account Currency
2130
beneficiary → accountInfo → number
string
256
Required
Account Number
2140
beneficiary → accountInfo → address
string
256
Optional
Account Address
2150
beneficiary → accountInfo → routingType
string
256
Conditional Required
- Enum - bsb - swift - sort - ifsc - aba
2160
beneficiary → accountInfo → routingValue
string
256
Conditional Required
When the routingType is not empty
2170
beneficiary → entityType
string
1
Required
I : Individual B: Business
2180
beneficiary → idNumber
string
256
Optional
Certificate number
2200
beneficiary → idType
string
256
Optional
- Enum - idcard - passport - driver - residence - workpermit - other
2210
beneficiary → nationality
string
2
Required
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
2220
beneficiary → phoneCode
string
10
Optional
2230
beneficiary → phoneNumber
string
256
Optional
2240
beneficiary → email
string
256
Optional
2250
beneficiay → gender
string
10
Conditional Required
required once the entityType is Individual - Enum - Male - FeMale
2260
beneficiary → address
object
2300
beneficiary → address → state
string
256
Optional
2310
beneficiary → address →city
string
256
Required
2320
beneficiary → address → address
string
256
Required
2330
beneficiary → address → street
string
256
Optional
2340
beneficiary → address → postCode
string
256
Optional
2350
beneficiary → address → country
string
2
Required
Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)
2360
beneficiaryId
string
256
Conditional Required
If you know the id of your beneficiary in advance, then you can submit all the information instead
2900
payer
object
Conditional Required
Details for the payer . If payerId provided then payer should be empty
3000
payer→ firstName
string
256
Required
3100
payer → lastName
string
256
Required
3120
payer → nationality
string
2
Required
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
3130
payer → phoneNumber
string
256
Optional
3140
payer → phoneCode
string
10
Optional
3150
payer → email
string
256
Optional
3160
payer → idNumber
string
256
Required
Certificate number
3170
payer → idType
string
256
Required
- Enum - idcard - passport - driver - residence - workpermit - other
3180
payer → idCountry
string
2
Required
Country of Certificate (ISO 3166-1 two-digit code, e.g. CN, US, JP)
3181
payer → idIssueDate
string
256
Optional
Certificate Issue Date (format YYYY-MM-DD)
3190
payer → idExpiryDate
string
256
Optional
Certificate Deadline (Format YYYY-MM-DD)
3200
payer → gender
string
10
Conditional Required
- Enum - Male - FeMale
3210
payer → entityType
string
1
Required
I : Individual B: Business
3220
payer → dob
string
10
Required
Date of Birth (Format YYYY-MM-DD)
3230
payer → reference
string
32
Optional
Reference from payer to beneficiary
3240
payer → address
object
Required
3300
payer → address → state
string
256
Optional
3310
payer → address → city
string
256
Optional
3320
payer → address → street
string
256
Optional
3330
payer → address → postCode
string
256
Optional
3340
payer → address → address
string
256
Required
Full residential address
3350
payer → address → country
string
2
Required
Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)
3360
payerId
string
256
Conditional Required
If you know the id of your payer in advance, then you can submit all the information instead
3900
  • 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

3.2 Transfer Update

➡️
The API is used to update the order info when the order information is wrong
  • URI
      • POST /global/payout/transfer/update
  • Body Param
      • Body Json Demo
Global Payout Create Order Table
Name
Type
Required
Description
orderNo
string
256
Required
Merchant Unique Order No
lockRate
boolean
Required
queryNo
string
256
Required
purpose
string
256
Required
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
Conditional Required
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
relationship
string
256
Optional
The relationship with payer and beneficiary
sourceAmount
float
256
Required
sourceCurrency
string
3
Required
targetAmount
float
256
Required
targetCurrency
string
3
Required
beneficiary
object
Conditional Required
Details for the beneficiary . If beneficiaryId provided then beneficiary should be empty
beneficiary → accountInfo
object
Required
Beneficiary Account Info
beneficiary → accountType
string
32
Required
- bank - alipay - wechat
beneficiary → accountInfo → name
string
256
Required
Account Name
beneficiary → accountInfo → bankName
string
256
Required
Account Bank Name
beneficiary → accountInfo → currency
string
3
Required
Account Currency
beneficiary → accountInfo → number
string
256
Required
Account Number
beneficiary → accountInfo → address
string
256
Optional
Account Address
beneficiary → accountInfo → routingType
string
256
Conditional Required
- Enum - bsb - swift - sort - ifsc - aba
beneficiary → accountInfo → routingValue
string
256
Conditional Required
When the routingType is not empty
beneficiary → entityType
string
1
Required
I : Individual B: Business
beneficiary → idNumber
string
256
Optional
Certificate number
beneficiary → idType
string
256
Optional
- Enum - idcard - passport - driver - residence - workpermit - other
beneficiary → nationality
string
2
Required
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
beneficiary → phoneCode
string
10
Optional
beneficiary → phoneNumber
string
256
Optional
beneficiary → email
string
256
Optional
beneficiay → gender
string
10
Conditional Required
required once the entityType is Individual - Enum - Male - FeMale
beneficiary → address
object
beneficiary → address → state
string
256
Optional
beneficiary → address →city
string
256
Required
beneficiary → address → address
string
256
Required
beneficiary → address → street
string
256
Optional
beneficiary → address → postCode
string
256
Optional
beneficiary → address → country
string
2
Required
Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)
beneficiaryId
string
256
Conditional Required
If you know the id of your beneficiary in advance, then you can submit all the information instead
payer
object
Conditional Required
Details for the payer . If payerId provided then payer should be empty
payer→ firstName
string
256
Required
payer → lastName
string
256
Required
payer → nationality
string
2
Required
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → phoneNumber
string
256
Optional
payer → phoneCode
string
10
Optional
payer → email
string
256
Optional
payer → idNumber
string
256
Required
Certificate number
payer → idType
string
256
Required
- Enum - idcard - passport - driver - residence - workpermit - other
payer → idCountry
string
2
Required
Country of Certificate (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → idIssueDate
string
256
Optional
Certificate Issue Date (format YYYY-MM-DD)
payer → idExpiryDate
string
256
Optional
Certificate Deadline (Format YYYY-MM-DD)
payer → gender
string
10
Conditional Required
- Enum - Male - FeMale
payer → entityType
string
1
Required
I : Individual B: Business
payer → dob
string
10
Required
Date of Birth (Format YYYY-MM-DD)
payer → reference
string
32
Optional
Reference from payer to beneficiary
payer → address
object
Required
payer → address → state
string
256
Optional
payer → address → city
string
256
Optional
payer → address → street
string
256
Optional
payer → address → postCode
string
256
Optional
payer → address → address
string
256
Required
Full residential address
payer → address → country
string
2
Required
Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payerId
string
256
Conditional Required
If you know the id of your payer in advance, then you can submit all the information instead
  • 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

3.3 Docs Upload

➡️
Upload supporting material order by Multipart
  • URI
      • POST /global/payout/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
      type
      string
      Required
      File Type， Enum: - bill - offer - identification_front - identification_back
  • Response
      • Response Status: 200, Body Json Demo
      Response Status: 400, Body Json Demo

3.4 Upload Completed

➡️
Completed uploading supporting material for business order
  • URI
      • POST /global/payout//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

3.5 Query Order Status

➡️
This API is used to query the order status
  • URI
      • POST /global/payout/transfer/query/status
  • Body Params
      • Body Json Demo
      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
      Response Status: 400, Body Json Demo

3.6 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
      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
      Response Status: 400, Body Json Demo

4. Balance

4.1 New FX-Conversion

  • URI
      • GET /global/payout/wallet/new-fx-conversion
  • Body Params
      • Body Json Demo
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
Response Status: 400, Body Json Demo

4.2 Get All balance-transaction

  • URI
      • GET /global/payout/wallet/list-all-balance-transaction
  • Body Params
      • Body Json Demo
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., "Success", "Ongoing"). 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
Response Status: 400, Body Json Demo

5. Online Validation

5.1 Query Chinese Hanzi Character Information

  • URI
      • GET /global/payout/validation/query-chinese-characters
  • Body Params
      • Body Json Demo
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
Response Status: 400, Body Json Demo
Developer Guide
Appendix
Powered by Notaku
Share
Content
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 Docs Upload
3.4 Upload Completed
3.5 Query Order Status
3.6 Notification
4. Balance
4.1 New FX-Conversion
4.2 Get All balance-transaction
5. Online Validation
5.1 Query Chinese Hanzi Character Information