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
      { "secretKey": "xxxxxxxxxxxxxx","appKey":"xxxxxxxxx" }
      Name
      Description
      appKey
      string,appkey
      secretkey
      string ,secretkey
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "token": "xxxxxxxxxxxxxx" }
        Name
        Description
        data
        string,such as 'success' that mean cancel payment success.
        message
        string
        status
        string
    • 400
      • { "status": "-1", "message": "bad request, appkey not exist, please contact sales@xcurrency.com" }

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
      { "xxx": "xxxxxxxxxxxxxx" }
      Name
      Description
      xxxx
      string
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": {} }
    • 400
      • { "status": "10001", "message": "验签失败" }

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
      { "xxx": "xxxxxxxxxxxxxx" }
      Name
      Description
      xxxx
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": [{"areaLevel":"1","areaKey":"xxxxxxxxxxxxxxxx","code":"xxxx","list":[],"name":"北京","pinyin":"beijing"}]}
        Name
        Description
        data
        Array of objects (ChinaAreaInfoVo)
        message
        string
        status
        string
        data
        Name
        Description
        areaLevel
        string, the value 1 is state, value 2 is city, value 3 is district
        areaKey
        string, the key of area
        code
        string, postal code
        list
        Array of objects (ChinaAreaInfoVo)
        name
        string Simple Chinese of area name
        pinyin
        string Chinese PINYIN of area name
    • 400
      • { "status": "-1", "message": "bad request, error message" }

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/area/list
  • Body Params
    • Encrypted object, not necessarily dictionary type
      { "xxx": "xxxxxxxxxxxxxx" }
      Name
      Description
      xxxx
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": [{"nameCn":"程序员","nameEn":"programmer","nameTw":"程序員"]}
        Name
        Description
        data
        Array of objects (OccupationEntity)
        message
        string
        status
        string
        data(Array of objects (OccupationEntity))
        Name
        Description
        nameCn
        string, Simple Chinese of occupation
        nameEn
        string, english of occupation
        nameTw
        string, Traditional Chinese of occupation
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Quotes

Get a quote

The API is used to get currency rate.
  • URI
    • POST /payout/payment/query/price
  • Body Params
    • json
      { "sourceCurrency": "USD", "targetCurrency": "CNY" }
      Name
      Description
      type
      sourceCurrency
      Currency you are sending
      string
      targetCurrency
      目标币种
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": {"queryNo":"3052feb9a5924f7d8fe463c48a353dff", "rate": 6.3366} }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Currencies

Transfer

Create Transfer

The API is used to create a 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
    • json
      { "orderNo":"MMS20220328100002", "sourceAmount": 100.0, "sourceCurrency": "USD", "targetAmount": 655.67, "targetCurrency": "CNY", "purpose": "FamilySupport", "fundsSource": "Employment income", "relationship": "Parent", "beneficiary": { "idNumber": "51010xxxxxxxxxxx", "accountNumber": "6222xxxxxxxxxxxxxxx", "country": "CN", "firstName": "峰", "lastName": "谢", "iddCode": "86", "phone": "138xxxxxxxxxx", "sex":"male", "occupation":"IT", "idIssueDate":"2020-04-05", "idExpiryDate":"2040-04-05", "address": { "country": "CN", "state": "广东省", "city": "珠海市", "district": "香洲区", "address": "address line1" } }, "payer": { "sex": "male", "firstName": "Darren", "lastName": "Lim", "accountName": "Darren Lim", "accountNumber": "50xxxxxxxxxx", "bankAddress": "address line2", "bankCode": "53xxx", "bankName": "DBS BANK", "bankType": "bank", "dob": "1984-03-12", "idCountry": "AU", "idType": "Passport", "idNumber": "SGxxxxxxxxx", "idExpiryDate": "2025-01-12", "nationality": "AU", "occupation": "IT", "iddCode": "65", "phone": "886422525", "address": { "country": "AU", "state": "NSW", "city": "Sydney", "postCode": "35789", "address": "address line1" } } }
      Name
      Description
      type
      Enum
      orderNo(required)
      商户订单号
      string
      queryNo
      询价流水号
      string
      payer
      付款方信息
      object
      benficiary
      object
      fundsSource(required)
      string
      "Business income" "Employment income" "Part-time income" "Saving deposits”
      transactionMode
      string
      relationship(required)
      Relationship with beneficiary
      "Children" "Parent" "Self" "Sibling" "Spouse" "Grandparent" "Grandchildren”
      purpose(required)
      Purpose of remittance
      string
      "Family support" "Salary”
      sourceAmount(required)
      Source Amount, if in same currency transfaction mode, sourceAmount = targetAmount
      number <double>
      sourceCurrency(required)
      Source Currency, if in the same currency transaction mode pass CNY here.
      string
      targetAmount(required)
      Target Amount
      number <double>
      targetCurrency(required)
      Target Currency
      string

      benficiary Object
      Name
      Description
      type
      Enum
      accountName(required)
      Beneficiary's name, just support Simplified Chinese.
      string [ 2 .. 12 ] characters
      accountNumber(required)
      For the receive method of the bank, the account number is the bank card no. For the receive method of digital Wallets, the account number here is the account id of the digital wallet.
      string [ 10 .. 19 ] characters
      accountType
      Account type
      string
      "bank" "alipay”
      address(required)
      object
      bankAddress
      Address of bank
      string
      bankBranchName
      Branch name of bank
      string
      bankCode
      Bank's code, such as BOC, ICBC etc.
      string
      bankCountry
      Country of bank. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      bankName
      Bank name
      string
      bankType
      Bank type
      string
      country(required)
      Country of beneficiary. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      dob
      Date of birth, format by YYYY-MM-DD
      string
      email
      Email
      string
      firstName
      First name
      string
      firstNameEn
      First name in Pinyin
      string
      fullName
      Full name
      string
      idCountry
      Country of ID. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      idExpiryDate
      ID valid date end, format by YYYY-MM-DD (2099-12-31 indicates that ID has not expiry date) .If you are in classic mode, this will be required
      string
      idIssueDate
      ID valid date start, format by YYYY-MM-DD.If you are in classic mode, this will be required
      string
      idNumber(required)
      ID number
      string
      idType
      ID type
      string
      "idcard" "passport" "driver" "residence" "workpermit" "other”
      iddCode(required)
      Phone area code, such as 86
      string
      lastName
      Last name
      string
      lastNameEn
      Last name in Pinyin
      string
      nationality
      Nationality. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      occupation
      Occupation, get by Beneficiary's Occupation.If you are in classic mode, this will be required
      string
      phone(required)
      Phone number, just for chinese phone.
      string = 11 characters
      sex
      Sex
      string
      "male" "female”
      address Object
      Name
      Description
      type
      Enum
      address(required)
      Address of residence
      string [ 10 .. 300 ] characters
      city(required)
      City
      string [ 2 .. 26 ] characters
      country
      Country of Residence. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string = 2 characters
      district(required)
      District
      string [ 2 .. 36 ] characters
      postCode
      Zip code
      string
      state(required)
      State
      string [ 2 .. 26 ] characters

      payer Object
      Name
      Description
      type
      Enum
      accountName
      Sender's native bank account name
      string [ 2 .. 12 ] characters
      accountNumber(required)
      Sender's native bank card no.
      string [ 10 .. 19 ] characters
      accountType
      Account Type
      string
      "bank" "alipay”
      address
      support local language.
      object (PayerAddressDto)
      bankAddress
      Bank address
      string
      bankBranchName
      Branch name of bank
      string
      bankCode
      Bank code
      string
      bankCountry
      Country of bank. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      bankName
      Bank name
      string
      bankType
      Bank type
      string
      dob(required)
      Date of birth in YYYY-MM-DD format
      string
      email
      Email address
      string
      firstName(required)
      First name
      string [ 2 .. 12 ] characters
      firstNameEn
      First name in Pinyin
      string
      fullName
      Full name
      string
      idCountry(required)
      Country of ID. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      idExpiryDate
      ID expiration date in YYYY-MM-DD format (2099-12-31 indicates that ID is valid for a long time)
      string
      idNumber(required)
      ID number
      string [ 6 .. 20 ] characters
      idType(required)
      ID type
      string
      "idcard" "passport" "driver" "residence" "workpermit" "other”
      iddCode
      Phone area code
      string
      lastName(required)
      Last name
      string [ 1 .. 10 ] characters
      lastNameEn
      Last name in Pinyin
      string
      nationality(required)
      Nationality. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      occupation
      Occupation
      string
      phone
      Phone number
      string
      sex(required)
      Sex
      string
      "male" "female”
      address object (PayerAddressDto)
      Name
      Description
      type
      Enum
      address(required)
      Address of residence, support local language.
      string [ 10 .. 300 ] characters
      city(required)
      City
      string [ 2 .. 26 ] characters
      country(required)
      Country of Residence. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string = 2 characters
      postCode(required)
      Zip code
      string = 6 characters
      state
      State
      string

  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": {"tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02"} } data Object
        Name
        Description
        Type
        tradeId
        string
        status
        string
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Confirm Transfer

This API is used to send CNY to the beneficiary's bank account.
  • URI
    • POST /payout/payment/transfer
  • Body Params
    • { "tradeId": "xxxxxxxxxxxxxx" }
      Name
      Description
      Type
      tradeId
      Transaction number
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": "success" }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Async confirm transfer

This API is used to send CNY to the beneficiary's bank account, support concurrency.
  • Body Params
    • { "key": "xxxxxxxxxxxxxx" }
      Name
      Description
      Type
      tradeId
      Transaction number
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": {} }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Cancel transfer

The API can cancel payment, but the payment’s should be pending.
  • URI
    • POST /payout/payment/cancel
  • Body Params
    • json
      { "tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02" }
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": "success" }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Get a transfer status

The API can get payment status, the status can see below.
  • URI
    • POST /payout/payment/status
  • Body Params
    • json
      { "tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02" }
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": "pending" }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Update Info

The API is used to update payment data, just for payer, beneficiary, purpose , fundsSourcerelationship .
  • URI
    • POST /payout/payment/updat
  • Body Params
    • json
      { "orderNo":"MMS20220328100002", "purpose": "FamilySupport", "fundsSource": "Employment income", "relationship": "Parent", "beneficiary": { "idNumber": "51010xxxxxxxxxxx", "accountNumber": "6222xxxxxxxxxxxxxxx", "country": "CN", "firstName": "峰", "lastName": "谢", "iddCode": "86", "phone": "138xxxxxxxxxx", "sex":"male", "occupation":"IT", "idIssueDate":"2020-04-05", "idExpiryDate":"2040-04-05", "address": { "country": "CN", "state": "广东省", "city": "珠海市", "district": "香洲区", "address": "address line1" } }, "payer": { "sex": "male", "firstName": "Darren", "lastName": "Lim", "accountName": "Darren Lim", "accountNumber": "50xxxxxxxxxx", "bankAddress": "address line2", "bankCode": "53xxx", "bankName": "DBS BANK", "bankType": "bank", // 可空 "dob": "1984-03-12", "idCountry": "AU", "idType": "Passport", "idNumber": "SGxxxxxxxxx", "idExpiryDate": "2025-01-12", "nationality": "AU", "occupation": "IT", "iddCode": "65", "phone": "886422525", "address": { "country": "AU", "state": "NSW", "city": "Sydney", "postCode": "35789", "address": "address line1" } } }
      Name
      Description
      type
      Enum
      orderNo(required)
      商户订单号
      string
      benficiary
      Object
      fundsSource(required)
      Sources of funding
      string
      "Business income" "Employment income" "Part-time income" "Saving deposits”
      payer
      Object
      purpose(required)
      Purpose of remittance
      string
      "Family support" "Salary”
      relationship(required)
      Relationship with beneficiary
      string
      "Children" "Parent" "Self" "Sibling" "Spouse" "Grandparent" "Grandchildren”

      benficiary Object
      Name
      Description
      type
      Enum
      accountName(required)
      Beneficiary's name, just support Simplified Chinese.
      string [ 2 .. 12 ] characters
      accountNumber(required)
      For the receive method of the bank, the account number is the bank card no. For the receive method of digital Wallets, the account number here is the account id of the digital wallet.
      string [ 10 .. 19 ] characters
      accountType
      Account type
      string
      "bank" "alipay”
      address(required)
      object
      bankAddress
      Address of bank
      string
      bankBranchName
      Branch name of bank
      string
      bankCode
      Bank's code, such as BOC, ICBC etc.
      string
      bankCountry
      Country of bank. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      bankName
      Bank name
      string
      bankType
      Bank type
      string
      country(required)
      Country of beneficiary. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      dob
      Date of birth, format by YYYY-MM-DD
      string
      email
      Email
      string
      firstName
      First name
      string
      firstNameEn
      First name in Pinyin
      string
      fullName
      Full name
      string
      idCountry
      Country of ID. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      idExpiryDate
      ID valid date end, format by YYYY-MM-DD (2099-12-31 indicates that ID has not expiry date) .If you are in classic mode, this will be required
      string
      idIssueDate
      ID valid date start, format by YYYY-MM-DD.If you are in classic mode, this will be required
      string
      idNumber(required)
      ID number
      string
      idType
      ID type
      string
      "idcard" "passport" "driver" "residence" "workpermit" "other”
      iddCode(required)
      Phone area code, such as 86
      string
      lastName
      Last name
      string
      lastNameEn
      Last name in Pinyin
      string
      nationality
      Nationality. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      occupation
      Occupation, get by Beneficiary's Occupation.If you are in classic mode, this will be required
      string
      phone(required)
      Phone number, just for chinese phone.
      string = 11 characters
      sex
      Sex
      string
      "male" "female”
      address Object
      Name
      Description
      type
      Enum
      address(required)
      Address of residence
      string [ 10 .. 300 ] characters
      city(required)
      City
      string [ 2 .. 26 ] characters
      country
      Country of Residence. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string = 2 characters
      district(required)
      District
      string [ 2 .. 36 ] characters
      postCode
      Zip code
      string
      state(required)
      State
      string [ 2 .. 26 ] characters

      payer Object
      Name
      Description
      type
      Enum
      accountName
      Sender's native bank account name
      string [ 2 .. 12 ] characters
      accountNumber(required)
      Sender's native bank card no.
      string [ 10 .. 19 ] characters
      accountType
      Account Type
      string
      "bank" "alipay”
      address
      support local language.
      object (PayerAddressDto)
      bankAddress
      Bank address
      string
      bankBranchName
      Branch name of bank
      string
      bankCode
      Bank code
      string
      bankCountry
      Country of bank. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      bankName
      Bank name
      string
      bankType
      Bank type
      string
      dob(required)
      Date of birth in YYYY-MM-DD format
      string
      email
      Email address
      string
      firstName(required)
      First name
      string [ 2 .. 12 ] characters
      firstNameEn
      First name in Pinyin
      string
      fullName
      Full name
      string
      idCountry(required)
      Country of ID. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      idExpiryDate
      ID expiration date in YYYY-MM-DD format (2099-12-31 indicates that ID is valid for a long time)
      string
      idNumber(required)
      ID number
      string [ 6 .. 20 ] characters
      idType(required)
      ID type
      string
      "idcard" "passport" "driver" "residence" "workpermit" "other”
      iddCode
      Phone area code
      string
      lastName(required)
      Last name
      string [ 1 .. 10 ] characters
      lastNameEn
      Last name in Pinyin
      string
      nationality(required)
      Nationality. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string
      occupation
      Occupation
      string
      phone
      Phone number
      string
      sex(required)
      Sex
      string
      "male" "female”
      address object (PayerAddressDto)
      Name
      Description
      type
      Enum
      address(required)
      Address of residence, support local language.
      string [ 10 .. 300 ] characters
      city(required)
      City
      string [ 2 .. 26 ] characters
      country(required)
      Country of Residence. ISO 3166-1, 2-letter code, such as CN, US and JP.
      string = 2 characters
      postCode(required)
      Zip code
      string = 6 characters
      state
      State
      string

  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": {"tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02"} }
        Name
        Description
        Type
        tradeId
        string
        status
        string
    • 400
      • { "status": "-1", "message": "bad request, error message" }

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
    • { } Note that the empty dictionary still needs to be encrypted without the body
      Name
      Description
      Type
      Enum
      currency(required)
      Currency
      string
      transactionMode
      Different transaction modes correspond to different transfer channels (default:classic)
      string
      "classic" "xpress”
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": [{"walletId":"钱包id","currency":"币种","amount":"金额"}] }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Balance list

Get balance of all currencies
  • URI
    • POST /payout/wallet/list
  • Body Params
    • { } Note that the empty dictionary still needs to be encrypted without the body
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": [{"walletId":"钱包id","currency":"币种","amount":"金额"}] }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Risk Control

Risk Control Api Controller

Upload Supporting Docs

Upload Supporting Docs for tradeId
  • URI
    • POST /payment/risk/upload
  • Body Params
    • json
      { "tradeId": "string", "fileBase64": "string", "fileName": "string" }
  • Response
    • Return json Data
    • 200
      • { "status": "1","message":"xxx"}
    • 400
      • { "status": "-1", "message": "bad request, error message" }

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
    • json
      { "tradeId": "string", }
  • Response
    • Return json Data
    • 200
      • { "status": "1","message":"xxx"}
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Data API

List all areas of china

List occupations

string Enum: "Business income" "Employment income" "Part-time income" "Saving deposits" Sources of funding
address