logo

API Reference

1⃣️ Authentication

1.1 Get Token

➡️
The API is used to obtain token, which is set on the request header. The token is expired after one hour, you can get the new token before the token expires or get a new token for requests.
  • URI
    • POST /payout/oauth/token
  • Body Param
    • REQUEST BODY SCHEMA: application/json
      Body Json Demo
      Name
      Type
      Required
      Description
      appKey
      string
      Required
      appkey; From xCurrency Hubs
      secretKey
      string
      Required
      secretKey; From xCurrency Hubs
  • Response
    • Name
      Type
      Required
      Description
      data
      string
      Conditional Required
      if the status is 1,the token is responded
      status
      string
      Required
      1 : Success -1: Error
      message
      string
      Conditional Required
      if the status is -1,the err message is responded
      Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo

1.2 Check

➡️
The API is used to verify the sign data, will return true when the sign data is correct, will return 10001 when the sign method error.
  • URI
    • POST /payout/encrypt/check
  • Body Params
    • Encrypted object, not necessarily dictionary type
      Body Json Demo
  • Response
    • Name
      Type
      Required
      Description
      status
      string
      Required
      1 : Success 10001: Failed to verify the signature
      message
      string
      Conditional Required
      if the status is 10001,the err message is responded
      Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo

2⃣️ Rate Manager

2.1 Get a rate

💡
The API is used to get 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 better manage orders to you, including Create, Query, Update……

3.1 Transfer Create

➡️
The API is used to create a payment on xCurrency hubs, then orderNo should be unique, the same order number can create a payment once. When the http status is 400 and the response data has not tradeId mean that the payment is created failure on xCurrency Hubs' side, please check the response message or contact with xCurrency Hubs' team.
  • URI
    • POST /global/payout/transfer/create
  • 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 - Tuition - Insurance - Travel - Rent - Living - Salary - Family Support
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 → 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.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 - Tuition - Insurance - Travel - Rent - Living - Salary - Family Support
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 → 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 to upload 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 which is used for secondary verification, 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
      返回 json 数据
      Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo