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. Payin Order Manager

2.1 Payin Create

➡️
The API is used to create a payin on xCurrency hubs, so orderNo should be unique. The same order number can create a payin once. When the HTTP status is 400, and the response data has not traded, the order failed on xCurrency Hubs' side. Please check the response message or contact xCurrency Hubs' team.
  • URI
    • POST /global/payin/transfer/create
  • Body Param
    • Select the payin scenario you need
      Name
      Type
      Description
      orderNo
      string
      256
      Merchant Unique Order No
      purpose
      string
      256
      Purpose of remittance Enum: - Tuition - Insurance - Rent
      sourceAmount
      float
      sourceCurrency
      string
      3
      targetAmount
      float
      targetCurrency
      string
      3
      getway
      string
      256
      Enum: - wechat - alipay - bank
      payer
      object
      payer → fullName
      string
      256
      payer → entityType
      string
      1
      I : Individual B: Business
      payer → idNumber
      string
      256
      Certificate number
      payer → idType
      string
      256
      - Enum - idcard - passport - driver - residence - workpermit - other
      payer → nationality
      string
      2
      Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      payer → phoneNumber
      string
      256
      payer → phoneCode
      string
      3
      payer → email
      string
      256
      payer → emergencyPhone
      string
      256
      payer → gender
      string
      256
      Enum: - Male - FeMale
      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 → country
      string
      2
      Country of Address (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 → relationship
      string
      256
      Relationship Between Payer and RealPayer Enum: - Self - Spouse - Parent - Children - Sibling - Grandparent - Grandchildren
      payer → realPayer
      object
      When the relationship ≠ Self
      payer → realPayer → fullName
      string
      256
      payer → realPayer → idNumber
      string
      256
      Certificate Number
      payer → realPayer → idType
      string
      256
      - Enum - idcard - passport - driver - residence - workpermit - other
      payer → realPayer → idIssueDate
      string
      256
      Certificate Issue Date (format YYYY-MM-DD)
      payer → realPayer → idExpiryDate
      string
      256
      Certificate Deadline (format YYYY-MM-DD)
      beneficiary
      object
      beneficiary → fullName
      string
      256
      beneficiary → entityType
      string
      1
      I : Individual B: Business
      beneficiary → accountInfo
      object
      beneficiary → accountInfo → name
      string
      256
      beneficiary → accountInfo → number
      string
      256
      beneficiary → nationality
      string
      2
      Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      fileIds
      string[]
      256
  • 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
      data → gateway
      object
      Required
      data → gateway → gateway
      string
      256
      Required
      Enum - alipay - wechat - bank
      data → gateway → appid
      string
      256
      Conditional Required
      When gateway is wechat/alipay
      data → gateway → orderId
      string
      256
      Conditional Required
      When gateway is wechat/alipay, will jump to wechat/alipay with orderId
      date → gateway → accountName
      string
      Conditional Required
      When gateway is bank
      data → gateway → accountNumber
      string
      256
      Conditional Required
      When gateway is bank
      data → gateway → bankName
      string
      256
      Conditional Required
      When gateway is bank
      data → gateway → reference
      string
      256
      Conditional Required
      When gateway is bank, will display the bank transfer reference
      Response Status: 200, Body Json Demo
      Response Status: 400, Body Json Demo

2.2 Query Order Status

➡️
This API is used to query the order status
  • URI
    • POST /global/payin/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
      data → gateway
      object
      Required
      data → gateway → gateway
      string
      256
      Required
      Enum - alipay - wechat - bank
      data → gateway → appid
      string
      256
      Conditional Required
      When gateway is wechat/alipay
      data → gateway → orderId
      string
      256
      Conditional Required
      When gateway is wechat/alipay, will jump to wechat/alipay with orderId
      date → gateway → accountName
      string
      Conditional Required
      When gateway is bank
      data → gateway → accountNumber
      string
      256
      Conditional Required
      When gateway is bank
      data → gateway → bankName
      string
      256
      Conditional Required
      When gateway is bank
      data → gateway → reference
      string
      256
      Conditional Required
      When gateway is bank, will display the bank transfer reference
      Response Status: 200, Body Json Demo
      Response Status: 400, Body Json Demo

2.3 Refresh Gateway Information

➡️
This API is used to query the order status
  • URI
    • POST /global/payin/transfer/refresh/gateway
  • 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
      data → gateway
      object
      Required
      data → gateway → gateway
      string
      256
      Required
      Enum - alipay - wechat - bank
      data → gateway → appid
      string
      256
      Conditional Required
      When gateway is wechat/alipay
      data → gateway → orderId
      string
      256
      Conditional Required
      When gateway is wechat/alipay, will jump to wechat/alipay with orderId
      date → gateway → accountName
      string
      Conditional Required
      When gateway is bank
      data → gateway → accountNumber
      string
      256
      Conditional Required
      When gateway is bank
      data → gateway → bankName
      string
      256
      Conditional Required
      When gateway is bank
      data → gateway → reference
      string
      256
      Conditional Required
      When gateway is bank, will display the bank transfer reference
      Response Status: 200, Body Json Demo
      Response Status: 400, Body Json Demo

2.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
  • Response
    • Return JSON data
      Response Status: 200, Body Json Demo
      Response Status: 400, Body Json Demo

3. Support Docs

3.1 Docs Upload

➡️
Upload supporting material order by Multipart
  • URI
    • POST /global/payin/transfer/upload/multipart
  • Form Data Params
    • Form Data Demo
      Name
      Type
      Required
      Description
      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
      fileName
      string
      Required
      bill.png
  • Response
    • Response Status: 200, Body Json Demo
      Response Status: 400, Body Json Demo