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
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
3
targetAmount
float
256
targetCurrency
string
3
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
32
- bank - alipay - wechat
beneficiary → accountInfo → name
string
256
Account Name
beneficiary → accountInfo → bankName
string
256
Account Bank Name
beneficiary → accountInfo → currency
string
3
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
1
I : Individual B: Business
beneficiary → idNumber
string
256
Certificate number
beneficiary → idType
string
256
- Enum - idcard - passport - driver - residence - workpermit - other
beneficiary → nationality
string
2
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
beneficiary → phoneCode
string
10
beneficiary → phoneNumber
string
256
beneficiary → email
string
256
beneficiay → gender
string
10
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
2
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
2
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → phoneNumber
string
256
payer → phoneCode
string
10
payer → email
string
256
payer → idNumber
string
256
Certificate number
payer → idType
string
256
- Enum - idcard - passport - driver - residence - workpermit - other
payer → idCountry
string
2
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
10
- Enum - Male - FeMale
payer → entityType
string
1
I : Individual B: Business
payer → dob
string
10
Date of Birth (Format YYYY-MM-DD)
payer → reference
string
32
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
2
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
32
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
      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 (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 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
3
targetAmount
float
256
targetCurrency
string
3
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
32
- bank - alipay - wechat
beneficiary → accountInfo → name
string
256
Account Name
beneficiary → accountInfo → bankName
string
256
Account Bank Name
beneficiary → accountInfo → currency
string
3
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
1
I : Individual B: Business
beneficiary → idNumber
string
256
Certificate number
beneficiary → idType
string
256
- Enum - idcard - passport - driver - residence - workpermit - other
beneficiary → nationality
string
2
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
beneficiary → phoneCode
string
10
beneficiary → phoneNumber
string
256
beneficiary → email
string
256
beneficiay → gender
string
10
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
2
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
2
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → phoneNumber
string
256
payer → phoneCode
string
10
payer → email
string
256
payer → idNumber
string
256
Certificate number
payer → idType
string
256
- Enum - idcard - passport - driver - residence - workpermit - other
payer → idCountry
string
2
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
10
- Enum - Male - FeMale
payer → entityType
string
1
I : Individual B: Business
payer → dob
string
10
Date of Birth (Format YYYY-MM-DD)
payer → reference
string
32
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
2
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
32
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
      Response Status: 400, Body Json Demo

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

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

6.2 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