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
- 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
China Payout - C2C Main information following steps:
- The Sender enters the recipient info and transfer amount and initiates the transfer.
- (Optional) The Sender agent requests xCurrency Hub to validate the transfer information.
- (Optional) xCurrency Hub forwards the request to the Paying Agent to validate the transfer information.
- (Optional) Paying Agent validates the transfer info and returns the result to xCurrency Hub.
- (Optional) xCurrency Hub forwards the result to the Sender Agent.
- Sender Agent completes internal check of KYC and AML program, and then sends the transfer request to xCurrency Hub.
- xCurrency Hub completes an internal check of the KYC and AML program, and then sends the transfer request to Paying Agent.
- Paying Agent completes an internal check of the KYC and AML program, and then credits the amount to the recipient through China Payment System.
- China Payment System returns transfer results to Paying Agent.
- Paying Agent forwards the transfer result to xCurrency Hub.
- xCurrency Hub. forwards the transfer result to the Sender Agent.
- Sender Agent sends the transfer result notification to Sender.
China Payout - Transfer Fund Flow
Cross-Currency Transaction Mode
- 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
- 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 withbase64
- 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
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
200
400
返回 json 数据
{ "status": "1", "token": "xxxxxxxxxxxxxx" }
{ "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
200
400
Return json Data
{ "status": "1", "data": {} }
{ "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
200
400
返回 json 数据
{ "status": "1", "data": {"queryNo":"3052feb9a5924f7d8fe463c48a353dff", "rate": 6.3366} }
{ "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
200
400
返回 json 数据
{ "status": "1", "data": {"tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02"} }
{ "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
200
400
返回 json 数据
{ "status": "1", "data": "success" }
{ "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
200
400
Return json Data
{ "status": "1", "data": "success" }
{ "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
200
400
Return json Data
{ "status": "1", "data": "pending" }
{ "status": "-1", "message": "bad request, error message" }
Update Info
The API is used to update payment data, just for
payer
, beneficiary
, purpose
, fundsSource
relationship
.- 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
200
400
Return json Data
{ "status": "1", "data": {"tradeId": "bcd6eab0d8bb4ceab440aab5a0f3bf02"} }
{ "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 bodyName | Description |
ㅤ | ㅤ |
ㅤ | ㅤ |
- Response
200
400
Return json Data
{ "status": "1", "data": [{"walletId":"钱包id","currency":"币种","amount":"金额"}] }
{ "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
200
400
Return json Data
{ "status": "1", "data": {"walletId":"钱包id","currency":"币种","amount":"金额"} }
{ "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
200
400
Return json Data
{ "status": "1", "data": "success" }
{ "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 |
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 使用教程
KYC Documents
FAQ
- 使用其他语言加密时,如何验证与服务通讯后加密方式是正确的?
通过验签 API,可以验证加密是否正确。
- sftp 该如何同步文件?
请查看 sftp 操作教程。
- 下发订单异常后,怎么操作不了订单?
异常订单是我们运营人员介入操作,也可以直接联系我们相关人员进行沟通处理。
- 返回状态码是 400 时,有时
body
里数据有errors
属性,这块错误信息代表什么意思?
这种一般是数据校验的错误,具体看返回数据即可,会有具体描述。如下事例:
防并发的提示:
{"status":"-1","errors":["请勿重复请求"]}
。- 同一订单是否可以多次调用代付接口?
不允许多次或并发调用代付接口,造成资金损失需要自己承担。