logo

API Reference

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

Commons

Beneficiary's PBC area list.

💡
The areaLevel value of 1 is state, 2 is city, 3 is district, for beneficiary's address data can be filled by pinyin fields.Request headers just need appkey and token.
  • URI
      • GET /payout/common/area/list
  • Body Params
      • Encrypted object, not necessarily dictionary type
      Body Json Demo
      Name
      Type
      Required
      Description
      xxxx
      string
      Conditional Required
  • Response
      • Name
      Type
      Required
      Description
      data
      array
      Conditional Required
      of objects (ChinaAreaInfoVo)
      data → ChinaAreaInfoVo
      object
      Conditional Required
      data → ChinaAreaInfoVo → areaLevel
      string
      Conditional Required
      the value 1 is state, value 2 is city, value 3 is district
      data → ChinaAreaInfoVo → areaKey
      string
      Conditional Required
      the key of area
      data → ChinaAreaInfoVo → code
      string
      Conditional Required
      postal code
      data → ChinaAreaInfoVo → list
      array
      Conditional Required
      of objects (ChinaAreaInfoVo)
      data → ChinaAreaInfoVo → name
      string
      Conditional Required
      Simple Chinese of area name
      data → ChinaAreaInfoVo → pinyin
      string
      Conditional Required
      Chinese PINYIN of area name
      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

Beneficiary's occupation list

💡
For beneficiary's occupation can be filled by nameEn fields. Request headers just need appkey and token.
  • URI
      • GET /payout/common/occupation/list
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      xxxx
      string
      Conditional Required
  • Response
      • 返回 json 数据
      Name
      Type
      Required
      Description
      data
      array
      Conditional Required
      of objects (OccupationEntity)
      data → OccupationEntity
      object
      Conditional Required
      data → OccupationEntity → nameCn
      string
      Conditional Required
      Simple Chinese of occupation
      data → ChinaAreaInfoVo → nameEn
      string
      Conditional Required
      english of occupation
      data → ChinaAreaInfoVo → nameTw
      string
      Conditional Required
      Traditional Chinese of occupation
      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

Quotes

Get a quote

💡
The API is used to get currency rate.
  • URI
      • POST /payout/payment/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

Currencies

Transfer

Create Transfer

💡
The API is used to create a personal payment on xCurrency, then orderNo should be unique, the same order number can create a payment one time.
  • URI
      • POST /payout/payment/create
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      orderNo
      string
      Required
      OrderNo
      sourceAmount
      float
      Required
      Source Amount
      sourceCurrency
      string
      Required
      Source Currency
      targetAmount
      float
      Required
      Target Amount
      targetCurrency
      string
      Required
      Target Currency
      transactionMode
      string
      Required
      Enum - classic - xpress default: classic, if u want to succinct beneficiary info, pls fill the xpress
      purpose
      string
      Required
      Purpose of remittance Enum - Family support - Salary
      fundsSource
      string
      Required
      Source of funds Enum - Business income - Employment income - Part-time income - Saving deposits
      relationship
      string
      Required
      Affiliation with the payee Enum - Children - Parent - Relative - Self - Sibling - Spouse - Grandparent - MaternalGrandparent - Grandchildren - MaternalGrandchildren
      beneficiary
      object
      beneficiary → idNumber
      string
      Required
      Certificate number
      beneficiary → accountName
      string
      Required
      Beneficiary full name
      beneficiary → accountNumber
      string
      Required
      Bank account number
      beneficiary → country
      string
      Conditional Required
      Country code of the user (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      beneficiary → firstName
      string
      Optional
      Beneficiary First Name
      beneficiary → lastName
      string
      Optional
      Beneficiary Last name
      beneficiary → iddCode
      string
      Required
      Mobile phone area code
      beneficiary → phone
      string
      Conditional Required
      Mobile phone number
      beneficiary → sex
      string
      Conditional Required
      Gender
      beneficiary → occupation
      string
      Required
      Occupation
      beneficiary → idIssueDate
      string
      Conditional Required
      Certificate Issue Date (format YYYY-MM-DD)
      beneficiary → idExpiryDate
      string
      Conditional Required
      Certificate Deadline (Format YYYY-MM-DD)
      beneficiary → address
      object
      Optional
      beneficiary → address → country
      string
      Optional
      Country of residence (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      beneficiary → address → address
      string
      Required
      Residential address
      beneficiary → address → city
      string
      Required
      city
      beneficiary → address → district
      string
      Required
      District and county
      beneficiary → address → postCode
      string
      Optional
      postCode
      beneficiary → address → state
      string
      Required
      Province/State
      beneficiary → address →street
      string
      Required
      Street
      payer
      object
      payer → sex
      string
      Required
      Gender
      payer → firstName
      string
      Required
      payer First Name
      payer → lastName
      string
      Required
      payer Last name
      payer → accountName
      string
      Optional
      Bank account name
      payer → bankAddress
      string
      Optional
      Bank address
      payer → bankCode
      string
      Optional
      Bank code
      payer → bankName
      string
      Optional
      Bank Name
      payer → bankType
      string
      Optional
      Bank Type
      payer → dob
      string
      Required
      Date of birth (format YYYY-MM-DD)
      payer → idCountry
      string
      Required
      Country of the document (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      payer → idType
      string
      Required
      Enum - idcard - passport - driver - residence - workpermit - other
      payer → idNumber
      string
      Required
      Certificate number
      payer → idExpiryDate
      string
      Conditional Required
      Certificate Deadline (Format YYYY-MM-DD)
      payer → idIssueDate
      string
      Conditional Required
      Certificate Issue Date (format YYYY-MM-DD)
      payer → nationality
      string
      Required
      Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      payer → occupation
      string
      Optional
      payer → iddCode
      string
      Required
      Mobile phone area code
      payer → phone
      string
      Required
      Mobile phone number
      payer → address
      object
      payer → address → address
      string
      Required
      Residential address
      payer → address → city
      string
      Required
      city
      payer → address → country
      string
      Required
      payer → address → postCode
      string
      Required
      payer → address → state
      string
      Optional
      payer → address → street
      string
      Optional
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      Conditional Required
      data → tradeId
      string
      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

Confirm Transfer ( Have been abandoned，pls use Async confirm transfer)

💡
This API is used to send CNY to the beneficiary's bank account.
  • URI
      • POST /payout/payment/transfer
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Transaction serial number
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      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

Async confirm transfer

💡
This API is used to send CNY to the beneficiary's bank account, we will async to work it, and callback the result for partner.
  • URI
      • POST /payout/payment/transfer/async
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Transaction serial number
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      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

Cancel transfer

💡
The API can cancel payment, but the payment’s should be pending.
  • URI
      • POST /payout/payment/cancel
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Transaction serial number
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      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

Get a transfer status

💡
The API can get payment status, the status can see below.
  • URI
      • POST /payout/payment/status
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Transaction serial number
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      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

Update Info

💡
The API is used to update payment data, just for payer, beneficiary, purpose , fundsSourcerelationship .
  • URI
      • POST /payout/payment/update
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      orderNo
      string
      Required
      Currency you are sending
      sourceAmount
      float
      Required
      Source Amount
      sourceCurrency
      string
      Required
      Source Currency
      targetAmount
      float
      Required
      Target Amount
      targetCurrency
      string
      Required
      Target Currency
      purpose
      string
      Required
      Purpose of remittance Enum - Family support - Salary
      fundsSource
      string
      Required
      Source of funds Enum - Business income - Employment income - Part-time income - Saving deposits
      relationship
      string
      Required
      Affiliation with the payee Enum - Children - Parent - Relative - Self - Sibling - Spouse - Grandparent - MaternalGrandparent - Grandchildren - MaternalGrandchildren
      beneficiary
      object
      beneficiary → idNumber
      string
      Required
      Certificate number
      beneficiary → accountNumber
      string
      Required
      Bank account number
      beneficiary → country
      string
      Conditional Required
      Country code of the user (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      beneficiary → firstName
      string
      Required
      beneficiary First Name
      beneficiary → lastName
      string
      Required
      beneficiary Last name
      beneficiary → iddCode
      string
      Required
      Mobile phone area code
      beneficiary → phone
      string
      Conditional Required
      Mobile phone number
      beneficiary → sex
      string
      Conditional Required
      Gender
      beneficiary → occupation
      string
      Required
      Occupation
      beneficiary → idIssueDate
      string
      Conditional Required
      Certificate Issue Date (format YYYY-MM-DD)
      beneficiary → idExpiryDate
      string
      Conditional Required
      Certificate Deadline (Format YYYY-MM-DD)
      beneficiary → address
      object
      Optional
      beneficiary → address → country
      string
      Optional
      Country of residence (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      beneficiary → address → address
      string
      Required
      Residential address
      beneficiary → address → city
      string
      Required
      city
      beneficiary → address → district
      string
      Required
      District and county
      beneficiary → address → postCode
      string
      Optional
      postCode
      beneficiary → address → state
      string
      Required
      Province/State
      beneficiary → address →street
      string
      Required
      Street
      payer
      object
      payer → sex
      string
      Required
      Gender
      payer → firstName
      string
      Required
      payer First Name
      payer → lastName
      string
      Required
      payer Last name
      payer → accountName
      string
      Optional
      Bank account name
      payer → bankAddress
      string
      Optional
      Bank address
      payer → bankCode
      string
      Optional
      Bank code
      payer → bankName
      string
      Optional
      Bank Name
      payer → bankType
      string
      Optional
      Bank Type
      payer → dob
      string
      Required
      Date of birth (format YYYY-MM-DD)
      payer → idCountry
      string
      Required
      Country of the document (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      payer → idType
      string
      Required
      Enum - idcard - passport - driver - residence - workpermit - other
      payer → idNumber
      string
      Required
      Certificate number
      payer → idExpiryDate
      string
      Conditional Required
      Certificate Deadline (Format YYYY-MM-DD)
      payer → idIssueDate
      string
      Conditional Required
      Certificate Issue Date (format YYYY-MM-DD)
      payer → nationality
      string
      Required
      Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
      payer → occupation
      string
      Optional
      payer → iddCode
      string
      Required
      Mobile phone area code
      payer → phone
      string
      Required
      Mobile phone number
      payer → address
      object
      payer → address → address
      string
      Required
      Residential address
      payer → address → city
      string
      Required
      city
      payer → address → country
      string
      Required
      payer → address → postCode
      string
      Required
      payer → address → state
      string
      Optional
      payer → address → street
      string
      Optional
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      Conditional Required
      data → tradeId
      string
      Conditional Required
      data → status
      string
      Conditional Required
      status
      string
      Required
      1 : Success -1: Error
      message
      string
      Conditional Required
      if the status is -1，the err message is responded
      返回 json 数据
      Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo

Balance

Balance for single currency

💡
Get balance information by currency
The API can get all currencies balance amount.
  • URI
      • POST /payout/wallet/get
  • Body Params
      • Body Json Demo { } Note that the empty dictionary still needs to be encrypted without the body
      Name
      Type
      Required
      Description
      currency
      string
      Required
      Currency
      transactionMode
      string
      Conditional Required
      Enum - classic - xpress
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      Conditional Required
      data → amount
      string
      Conditional Required
      Available balance
      data → currency
      string
      Conditional Required
      data → totalAmount
      float
      Conditional Required
      Total balance = available + in transit
      data → walletId
      string
      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

Balance list

💡
Get balance of all currencies
  • URI
      • POST /payout/wallet/list
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
  • Response
      • Name
      Type
      Required
      Description
      data
      array
      Conditional Required
      data → dataObj
      object
      Conditional Required
      data → dataObj → amount
      float
      Conditional Required
      Available balance
      data → dataObj → currency
      string
      Conditional Required
      data → dataObj → totalAmount
      float
      Conditional Required
      Total balance = available + in transit
      data → dataObj → walletId
      string
      Conditional Required
      status
      string
      Required
      1 : Success -1: Error
      message
      string
      Conditional Required
      if the status is -1，the err message is responded
      返回 json 数据
      Response Status : 200, Body Json Demo
      Response Status : 400, Body Json Demo

Upload Supporting Docs

💡
Upload Supporting Docs for tradeId
  • URI
      • POST /payment/risk/upload
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Transaction id
      fileBase64
      string
      Required
      fileName
      string
      Required
      Filename (with suffix)
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      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

Upload Supporting Docs Completed

💡
Completed to upload Supporting Docs for tradeId, It will change the transfer status to awaiting_transfe
  • URI
      • POST /payment/risk/completed
  • Body Params
      • Body Json Demo
      Name
      Type
      Required
      Description
      tradeId
      string
      Required
      Transaction id
  • Response
      • Name
      Type
      Required
      Description
      data
      object
      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

Notification

Order status 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 /xcurrency/webhook
  • 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
      id
      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

Data API

List all areas of china

List occupations

string Enum: "Business income" "Employment income" "Part-time income" "Saving deposits" Sources of funding
address
Powered by Notaku
Share
Content
API Reference
Authentication
Get Token
Check
Commons
Beneficiary's PBC area list.
Beneficiary's occupation list
Quotes
Get a quote
Currencies
Transfer
Create Transfer
Confirm Transfer ( Have been abandoned，pls use Async confirm transfer)
Async confirm transfer
Cancel transfer
Get a transfer status
Update Info
Balance
Balance for single currency
Balance list
Upload Supporting Docs
Upload Supporting Docs Completed
Notification
Order status notification
Data API
List all areas of china
List occupations