logo

Service Specification

Document History

Version
Date
Comments
0.9.5
2022-07-15
Update the introduction section for transfer information flow and fund flow.
0.9.0
2022-07-08
First release

Support Contacts

If you have any questions during the API integration process, please contact us through dev@xcurrency.com.

Introduction

xCurrency is a FinTech company that strives to deliver diverse, high-efficient and flexible payment solutions for global businesses.

About xCurrency Hub

xCurrency Hub is xCurrency’s Banking-as-a-service Hub platform building for global businesses, delivering creative and innovative embedded finance solutions to Financial Institutions of All Sizes, providing fast, reliable, and cost-efficient payouts for your business and customers.

Roles and responsibilities of key Participants

Figure1. Key Participant
Figure1. Key Participant
  • Sender:
    • Individual: The person who requests to transfer money or bill payments.
  • Agent:
    • Sender Agent: The paying agent managing the Sender’s account, collects monetary assets from the Sender, processes money transfers on behalf of the Sender, and provides relevant services to the Sender.
    • Paying Agent: A paying agent—also known as a "disbursing agent"—is one who accepts payments from the issuer of a security and then distributes the funds to holders of the security.
  • xCurrency Hub: The platform that forwards transfer requests from the Sender Agent to the Paying Agent, providing services including balance management service, transfer service, and reconciliation service.
  • Recipient:
    • Individual: The individual consumer who receives money remittance services through a licensed financial institution and gets monetary assets.
    • Business: The organization that provides services like E-Commerce, Premium, Health, Education, and so on. eg. School

China Payout

This document focus on the API integration of China Payout running on our xCurrency Hub platform. Based on our strong CNY distribution network, we can help you make an easier cross-border payout to China, whenever you are launching new products, expanding into China, or adding remittance modular into your existing operations.
You can apply our cutting-edge APIs for an enhanced customer experience, our China Payout solution supports [UnionPay Debit Cards] issued by more than 500 mainstream banks in China, whether it is China's four major state-owned banks, city commercial banks, and rural credit cooperatives in various places.

Advantages

We support [UnionPay Debit Cards] issued by more than 500 mainstream banks in China, whether it is China's four major state-owned banks, city commercial banks, and rural credit cooperatives in various places.

Terminologies

Terms
Description
Sender
The person who requests to transfer money.
Beneficiary
The person who receives money.
Source Currency
The currency you are sending, currencies we support are USD, JPY, EUR, HKD, GBP, AUD, KRW, SGD, and CAD.
Target Currency
Currency your recipient will receive, Currencies we support: CNY
Order No
Order ID provided by the partner.
Query No
询价流水号
SFTP

China Payout - Transfer Information Flow

Figure2. China Payout - C2C Main Flow
Figure2. China Payout - C2C Main Flow

China Payout - C2C Main information following steps:

  1. The Sender enters the recipient info and transfer amount and initiates the transfer.
  1. (Optional) The Sender agent requests xCurrency Hub to validate the transfer information.
  1. (Optional) xCurrency Hub forwards the request to the Paying Agent to validate the transfer information.
  1. (Optional) Paying Agent validates the transfer info and returns the result to xCurrency Hub.
  1. (Optional) xCurrency Hub forwards the result to the Sender Agent.
  1. Sender Agent completes internal check of KYC and AML program, and then sends the transfer request to xCurrency Hub.
  1. xCurrency Hub completes an internal check of the KYC and AML program, and then sends the transfer request to Paying Agent.
  1. Paying Agent completes an internal check of the KYC and AML program, and then credits the amount to the recipient through China Payment System.
  1. China Payment System returns transfer results to Paying Agent.
  1. Paying Agent forwards the transfer result to xCurrency Hub.
  1. xCurrency Hub. forwards the transfer result to the Sender Agent.
  1. Sender Agent sends the transfer result notification to Sender.

China Payout - Transfer Fund Flow

Cross-Currency Transaction Mode

Figure3. Cross-Currency Transaction Mode Fund Flow
Figure3. Cross-Currency Transaction Mode Fund Flow
  1. Balance Management Process
      • 1.1. Sender Agent prefunds the settlement currency into the account provided by xCurrency Hub N days before the transaction day.
      • 1.2. xCurrency Hub tops up the Sender Agent’s account balance in the settlement currency after receiving the funds.
2. Transfer Process
  • 2.1. Sender Agent sends the transfer request to xCurrency Hub.
  • 2.2. xCurrency Hub converts the receiving amount into settlement currency and checks that the balance is sufficient, xCurrency Hub will debit the corresponding amount and get the fund ready for the Sender Agent.
    • 🔔
      FX Trade Availability Time: working day: 9:30--15:30 UTC+08:00
      Transfer Availability Time: 7x24hr
  • 2.3. The sender Agent debits the transfer amount from Sender’s account.
  • 2.4 Paying Agent credits the transfer amount to the Recipient’s account.

Same Currency Transaction Mode

Figure4. Same Currency Transaction Mode Fund Flow
Figure4. Same Currency Transaction Mode Fund Flow
  1. Balance Management Process
      • 1.1. Sender Agent prefunds the settlement currency into the account provided by xCurrency Hub N days before the transaction day.
      • 1.2. xCurrency Hub converts the settlement currency into receiving currency and tops up the Sender Agent’s account balance in the receiving currency to be ready for future transfers.
        • 💡
          FX Trade Availability Time: working day: 9:30--14:00 UTC+08:00 (Please contact the operator after 14:00)
2. Transfer Process
  • 2.1 Sender Agent debits the transfer amount from Sender’s account.
  • 2.2 Sender Agent sends the transfer request to xCurrency Hub.
    • 💡
      Transfer Availability Time: 7x24hr
  • 2.3 After checking that the balance is sufficient, xCurrency Hub will debit the corresponding amount and get the fund ready for the Sender Agent.
  • 2.4 Paying Agent credits the transfer amount to the Recipient’s account.

Developer Guide

Welcome to the xCurrency Hub - China Payout API documentation. Before you jump into coding, please review some important information about our API.

Interface Specification

  • Communication Mode:https + JSON
  • Charset: UTF-8
  • Encryption Method: encrypt with RSA, signature with base64
  • Date Format: yyyy-MM-dd.

Sample API Request Flow

sequenceDiagram actor S as Sender participant P as Partner participant X as xCurrency Hub participant B as Paying Agent actor R as Recipent S-->>P:Request FX rate(Cross currency) P-->>X:Get a quote(Cross currency):/payout/payment/query/price X-->>P: Return FX rate(Cross currency) P-->>S: FX rate Confirmation(Cross currency) S-->>S: Decide if accept this FX rate S->>P:Enters Recipient Info and transfer amount #Sender enters the required information and initiates the transfer. P->>X:Request transfer:/payout/payment/create#Sender agent requests xCurrency Hub to validate the transfer information. X->>B:Request transfer validation#xCurrency Hub forwards the request to Paying Agent B->>X:Return validation result #Paying Agent validates the transfer info and returns the result to xCurency Hub X->>X: AML Check X-->>P:Return request result P-->>S: Request Confirmation S->>S:If OK,proceed with transfer.If fail, correct entered info S->>P: Confirm Transfer #Sender P->>P: Generate UTR(Unique Transaction Reference) #P->>X:Create Transfer(UTR) # Sender Agent completes internal checks such as KYC and AML scaning, and then sends the transfer request through xCurrency Hub to Paying Agent. #X-->>P: Transfer Info P->>X: Confirm transfers:/payout/payment/transfer #Sender agent complates internal checks such as KYC and AML screening on the Sender, then sends the transfer request to xCurrency Hub X-->>P: OK X->>P: Status Update X->>X:Check Parnter's Balance X->>B: Payout Instruction #xCurrency Hub forwards the request to the Paying Agent B-->>X: Payout Result # Paying Agent sends the transfer to xCurrency Hub. xCurrency Hub forwards the result to Sender Agent. B-->>R: Notify Result # Paying Agent processes the transfer and then sends to the transfer result to the Beneficiary. # Paying Agent processes the transfer, completes internal checks such as KYC and AML screening on the Recipient, then credit the amount to recipient X->>P:Status Update P-->>S:Notify Result # Sender agent sends the transfer result to sender. #Sender Agent sends the transfer result notification to Sender
Figure 5. Sample API Request Flow

Security

To use our API you will require certain credentials that we will use to identify and authorize the use of Pay Out API.
Please reach out to us at  dev@xcurrency.com to obtain your credentials. You are supposed to get the following credentials from us to start using the API.
Name
Description
App Key
Will be used to identify you on consuming the API and obtain the authorization token which is used to access restricted resources.
Secret Key
Will need this to obtain the authorization token which is used to access restricted resources.
SFTP Account Name
Will be used to login SFTP which transfers the user’s KYC files to xCurrency.
SFTP Account Password
Will be used to login SFTP which transfers the user’s KYC files to xCurrency.

Request Header

To start using the API, the request header should be set attributes below.
Name
Description
appkey
required, send by xCurrency.
token
required, get by authorization API.
sign
required, to encrypt with body content string.

Request Body

Content-Type as application/json

API Hosts

  • sandbox:https://api-sandbox.xcurrency.com
  • production:https://api.xcurrency.com

Generate Private Key

💡
The Computer’s system environment should support OpenJDK 8 or above, and download the file which sends you by email.
downloaded the file and unzip the file, in the folder, click the secret.jar to open GUI, the generate the private key and public key. The public key is sent to xCurrency and the private key you keep safe by yourself.

Encrypt Method

💡
Encrypt: To encrypt with the private key(the request body should convert to JSON string first, then encrypt with the private key, finally get the base64 string and put on request headers. You can see the example of java code which send to you by email.)
Java Code Example

Partners integration checklist

The checklist to assist our new partners with the APIs integration, development, and testing.
Item
Description
IP/s to whitelist in Production
eg. 111.222.333.444
Email address of the POC who receives the encrypted production API_KEY and SFTP account.
eg. dev@xcurrency.com

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 /oauth/token
  • Body Params
    • { "secretKey": "xxxxxxxxxxxxxx","appKey":"xxxxxxxxx" }
      Name
      Description
      appKey
      string,appkey
      secretkey
      string ,secretkey
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "token": "xxxxxxxxxxxxxx" }
    • 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": "验签失败" }

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
      orderNo
      商户订单号
      string
      queryNo
      询价流水号
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": {"tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02"} }
    • 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
      tradeId
      string
  • Response
    • 返回 json 数据
    • 200
      • { "status": "1", "data": "success" }
    • 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 Transfer

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/update
  • 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
      orderNo
      商户订单号
      string
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": {"tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02"} }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Balances

All Balances

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

Query by Currency

The API get balance amount by simple currency.
  • URI
    • POST /payout/wallet/get
  • Body Params
    • { "currency": "xxxxxxx" }
      Name
      Description
      currency
      币种,例如 USD等
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": {"walletId":"钱包id","currency":"币种","amount":"金额"} }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Notification

host: xxxxxxxxx ,xxxxxxxx Represents your callback address, xCurrency Hub will call back notifications through this address xxxxxxxx/xcurrency/webhook
  • URI
    • POST /xcurrency/webhook
  • Headers
    • appkey :used for secondary verification
  • Body Params
    • { "id": "xxxxxxx", "event": "payment", "status": "", "message": ""}
      Name
      Description
      event
      payment: 代付信息 balance: 余额信息
      id
      payment: tradeId balance: 待定
      status
      状态
      message
      非必需,相关错误信息
      amount
      非必需,event 为 balance 才存在

Transfer Validation

The API help you check the bank info of china.
  • URI
    • POST /payout/common/bank/4check
  • Body Params
    • json
      { "name": "谢峰", "phone": "158XXXXX522", "idNumber": "510103XXXXXXX0034", "accountNumber":"622202XXXXXXXX795027" }
      Name
      Description
      type
      name
      姓名
      string
      phone
      银行预留手机号
      string
      idNumber
      身份证号
      string
      accountNumber
      银行卡号
      string
  • Response
    • Return json Data
    • 200
      • { "status": "1", "data": "success" }
    • 400
      • { "status": "-1", "message": "bad request, error message" }

Data API

List all areas of china

List occupations

Appendix

Request & response code description

Transfer status

Status
Description
pending
create payment success, xCurrency on processing
awaiting_transfer
Waiting for remittance, only in this state can remittance be operated
transferring
tranferring
completed
transferred to user success
failed
transfer fail, wait to refund
rejected
the compliance not pass and so on
invalid
The exchange rate is invalid, reconfirm the exchange rate
canceled
payment cancel
refunding
refunding
refunded
refund completed

Error Code

Status
Description
1
请求成功
-1
非法请求,message/errors 体现具体错误信息
10001
验签错误
10002
appkey error
10003
询价已经过期
10004
参数校验失败
10005
订单无法下发,不是待汇款状态,需要检测订单状态
10006
超出规定汇款时间,无法进行汇款
10007
余额不足,无法汇款
10008
付款人信息未审核
10009
代付异常,如果疑问请联系极简货币运营专员
10010
收款账号异常,请检查收款账号
10011
收款账号异常,对方行系统不支持,请尝试换卡
10012
收款账号异常,收款人身份证已过期
10013
收款账号异常,非银联卡,请更换银联卡
10014
收款账号异常,账户超过银行限额
10015
付款人信息异常,如有疑问请联系极简货币运营专员
10016
风控异常
10017
无法取消,请查看当前订单状态

Source of Funds

Enum
Description
Business income
盈利收入
Employment income
雇佣薪酬
Part-time income
兼职收入
Saving deposits
储蓄存款

Purpose Of Transfer

Enum
Description
Family support
赡养家庭
Salary
工资报酬

Beneficiary and Sender Relationship

Enum
Description
Children
子女
Parent
父母
Relative
其他亲戚
Self
自己
Sibling
兄弟姐妹
Spouse
配偶

Postman Collections

为了方便使用我们 API,我们提供了 postman 文件,可以通过以下按钮直接点击打开 postman app。通过与 postman app 交互,可以直接测试我们的接口,方便你快速接入。
postman 使用可以查阅 postman 使用教程
Image without caption

KYC Documents

FAQ

  1. 使用其他语言加密时,如何验证与服务通讯后加密方式是正确的?
    1. 通过验签 API,可以验证加密是否正确。
  1. sftp 该如何同步文件?
    1. 请查看 sftp 操作教程
  1. 下发订单异常后,怎么操作不了订单?
    1. 异常订单是我们运营人员介入操作,也可以直接联系我们相关人员进行沟通处理。
  1. 返回状态码是 400 时,有时 body 里数据有 errors 属性,这块错误信息代表什么意思?
    1. 这种一般是数据校验的错误,具体看返回数据即可,会有具体描述。如下事例:
      防并发的提示:{"status":"-1","errors":["请勿重复请求"]}
  1. 同一订单是否可以多次调用代付接口?
    1. 不允许多次或并发调用代付接口,造成资金损失需要自己承担。

由...提供支持 Notaku