logo

Authentication

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

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

Transfer

Create Transfer

➡️
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 /payout/payment/business/transfer/create
  • Body Param
    • Body Json Demo
Name
Type
Required
Description
orderNo
string
256
Required
Merchant Order No
transactionMode
string
32
Required
The transactionMode Enum - originalMode ; default - cnyMode - crossMode
sourceAmount
float
32
Required
Source Amount
sourceCurrency
string
3
Required
Source Currency
targetAmount
float
32
Required
Target Amount
targetCurrency
string
3
Required
Target Currency
paymentType
string
32
Conditional Required
Payment Type ; When the targetCurrency is CNY, the field is required. Enum - DepositPayment - FullPayment - FinalPayment - Other
logisticsCompany
string
256
Conditional Required
Logistics company ; When the targetCurrency is CNY and paymentType is fullPayment and FinalPayment, the field is required.
logisticsNumber
string
256
Conditional Required
Logistics Number ; When the targetCurrency is CNY and paymentType is fullPayment and FinalPayment, the field is required.
payer
object
Required
The Payer
payer → fullName
string
256
Required
Full Name, Must be a business
payer → accountNumber
string
256
Optional
Bank Account Number, Must be a business account
payer → swiftCode
string
256
Optional
Bank Swift Code;
payer → address
object
Required
Address
payer → address → country
string
2
Optional
The country where the payer is located.Country code of the user (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → address → state
string
256
Optional
The state where the payer is located
payer → address → postCode
string
256
Optional
The postCode where the payer is located
payer → address → address
string
256
Conditional Required
The address where the payer is located; When the targetCurrenncy is not CNY, the field is required.
beneficiary
object
Required
beneficiary → fullName
string
256
Required
Full Name, Must be a business
beneficiary → accountName
string
256
Required
Bank Account Number, It can be a business account or a personal account
beneficiary → accountNumber
string
256
Required
Bank Account Number
beneficiary → bankName
string
256
Conditional Required
Account bank, need to be specific to the branch; When accountName is a business account, the field is required.
beneficiary → idNumber
string
256
Conditional Required
Chinese mainland resident ID card; When the targetCurrency is CNY and accountName is a personal account, the field is required.
beneficiary → address
object
Required
beneficiary → address → country
string
2
Optional
The country where the beneficiary is located.Country code of the user (ISO 3166-1 two-digit code, e.g. CN, US, JP)
beneficiary → address → state
string
256
Optional
The state where the beneficiary is located
beneficiary → address → postCode
string
256
Optional
The postCode where the beneficiary is located
beneficiary → address → address
string
256
Conditional Required
When the targetCurrenncy is not CNY, the field is required.
beneficiary → swiftCode
string
Conditional Required
Bank Swift Code; When the targetCurrenncy is not CNY, the field is required.
beneficiary → companyNumber
string
256
Conditional Required
Company incorporation number, Unified Social Credit Identifier; When accountName is a business account, the field is required.
  • 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

Async confirm transfer

➡️
This API is used to send CNY to the beneficiary's bank account, support concurrency.
  • URI
    • POST /payout/payment/business/transfer/async
  • Body Params
    • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Uniqued id in the XC system
      queryNo
      string
      Conditional Required
      When the sourceCurrency ≠ targetCurrency, field is required.
  • Response
    • Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo

Docs Upload

Upload File

➡️
Upload supporting material for business order
  • URI
    • POST /payout/payment/business/transfer/upload
  • Body Params
    • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Uniqued id in the XC system
      fileBase64
      string
      Required
      File base64 str
      fileName
      string
      Required
      File name
      type
      string
      Required
      File Type, proforma_invoice or purchase_order mush be provided Enum: - 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

Upload File By Multipart

➡️
Upload supporting material for business order by Multipart
  • URI
    • POST /payout/payment/business/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
      fileName
      string
      Required
      File name
      type
      string
      Required
      File Type, proforma_invoice or purchase_order mush be provided Enum: - 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

Upload Completed

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

Query

Query a transfer status

➡️
This API is used to query the order status
  • URI
    • GET /payout/payment/business/transfer/status
  • 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
      Name
      Type
      Required
      Description
      status
      string
      Required
      1 : Success -1: Error for System
      message
      string
      Conditional Required
      The tradeId is not existed
      data
      object
      data → message
      string
      Required
      if status is failed rejected overrule , the message is the reason for the transfer failure
      data → status
      string
      Required

Query a FX

➡️
This API is used to query the fx real time
  • URI
    • GET /payout/payment/business/query/rate
  • Body Params
    • Body Json Demo
      Name
      Type
      Required
      Description
      sourceCurrency
      string
      Required
      Currency you are sending; ex: USD、HKD、SGD
      targetCurrency
      string
      Required
      Target currency; ex: CNY
  • Response
    • Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo
      Name
      Type
      Required
      Description
      status
      string
      Required
      1 : Success -1: Error for System
      message
      string
      Conditional Required
      The tradeId is not existed
      data
      object
      data → queryNo
      string
      Required
      Uniqued query fx id in the XC system,expired for 15s
      date → rate
      float
      Required
      Real rate