Request & response code description
Transfer status
Status | Description |
pending | create payment success, xCurrency on processing |
pending_material | Pending for the merchant to complete the upload certification materials |
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 |
canceled | payment cancel |
refunding | refunding |
refunded | refund completed |
Error Code
Status | Description |
1 | Request successful |
-1 | Illegal request. 'message' contains detailed error message |
10001 | Signature check error |
10002 | Appkey error |
10003 | Quote price is expired |
10004 | Params validation failed |
10005 | The payment cannot be transfered, the payment status is not awaiting_transfer |
10006 | Remittance cannot be made outside the time limit |
10007 | Insufficient balance |
10008 | Sender information is not passed by KYC reviewed, the payment will not be created on xCurrency Hubs' side. |
10009 | Transfer fail, if you have any questions, please contact xCurrency Hubs by email |
10010 | Beneficiary's account is abnormal. Please verify the beneficiary account |
10011 | Beneficiary's account is abnormal. The beneficiary's bank system does not support, please try to use other card |
10012 | Beneficiary's account is abnormal. The beneficiary's ID card has expired |
10013 | Beneficiary's account is abnormal. A non-UnionPay card is detected. Please use UnionPay card |
10014 | Beneficiary's account is abnormal. Exceeding bank limits |
10015 | The sender information is abnormal. If you have any questions, please contact xCurrency Hubs by email |
10016 | Risk control |
10017 | Cancel failed, please check the payment status. |
10018 | Invalid Sender ID Expiry Date. |
10019 | Invalid Sender Birthdate. |
10020 | Blacklisted Sender. |
10021 | Invalid Beneficiary ID Expiry Date. |
10022 | Blacklisted Beneficiary. |
10023 | Invalid Beneficiary Birthdate. |
10100 | The order number is duplicated. Ensure that each order number is unique. |
10101 | There was an error with number validation. Ensure that all numeric fields are correctly formatted. |
10102 | The specified transaction mode is incorrect. Verify the transaction mode. |
10103 | The currency used for this transaction mode is incorrect. Ensure that the currency matches the transaction mode requirements. |
10104 | The payment type is invalid. Ensure that the payment type is correct. |
10105 | For full or final payments, the logistics company must be provided. Ensure that the logistics company is specified. |
10106 | For full or final payments, the logistics number must be provided. Ensure that the logistics number is specified. |
10107 | The beneficiary account name must be in all Chinese characters. Verify the account name. |
10108 | The bank account number is invalid. Ensure that the bank account number is correct. |
10109 | The beneficiary ID number is invalid. Verify the ID number. If the ID number is correct, contact support. |
10110 | For company account payments, the beneficiary bank must be specified. Ensure that the beneficiary bank is provided. |
ㅤ | ㅤ |
Source of Funds
Enum | Description |
Business income | Business income |
Employment income | Employment income |
Part-time income | Part-time income |
Saving deposits | Savings & Deposits |
Purpose Of Transfer
Enum | Description |
Family support | Family Support |
Salary | Wages and Compensation |
Beneficiary and Sender Relationship
Enum | Description |
Children | Children |
Parent | Parents |
Self | Self |
Sibling | Siblings |
Spouse | Spouse |
Grandparent | Grandparents |
Grandchildren | Grandchildrens |
Postman Collections
To facilitate the use of our API, we provide a Postman collection file. You can directly open the Postman app by clicking the button below. By interacting with the Postman app, you can directly test our endpoints, making it easy for you to quickly integrate.
For instructions on how to use Postman, please refer to the Postman usage guide.
Send your first API request | Postman Learning Center
Postman is a collaboration platform for API development. Postman's features simplify each step of building an API and streamline collaboration so you can create better APIs—faster.
https://learning.postman.com/docs/getting-started/sending-the-first-request/
KYC Documents
FAQ
- When using encryption in other languages, how do I verify that the encryption is correct after communicating with the service?
You can check the entryption is ok by the verify API 。
- How to synchronize files when using sftp?
Please check sftp Guide.
- What can I operate the payment with transfer exception?
Abnormal payments are handled by our staff. You can contact us for further information.
- When the response http status code is 400,
bodycontains theerrorsormessageattribute, what does it mean?
This is usually error message, just look at the message or errors, you will see the relevant description. For example,
Code | Message | Detail/Action |
-1 | Signature verification failed | Please check sign method and private key |
-1 | the payment get by tradeId does not exist | please check the tradeId, the tradeId must get by create payment response |
-1 | rate not found | the sourceCurrency or targetCurrency is error |
-1 | Required request is missing | miss request body, please check the api docs and set the body content |
-1 | Wallet in this currency was not found | the request body of currency not exist or not support currency |
-1 | Do not repeat the request | Concurrent requests are not supported for create or confirm the same payment |
-1 | StringIndexOutOfBoundsException | the beneficiary’s idNumber is error |
-1 | order already exists | have created the payment on xCurrency Hubs side, can not create the same orderNo payment |
-1 | Error in file operation processing | Beneficiary's accountName should be Simplified Chinese, such as "张三", "李四" etc. |
-1 | Unsupported binding card | please check the Beneficiary's info, some data is wrong, not the actual data, when change right can resubmit again |
-1 | Payee account name is wrong | please check the Beneficiary's info, some data is wrong, not the actual data, when change right can resubmit again |
-1 | wrong database operation | please check the Beneficiary's expireDate, the format should be yyyy-MM-dd |
-1 | The order is being processed, please do not repeat the operation. | don't request same transfer API twice |
-1 | Risk control | Do not use the payer to create payment, or can contact xCurrency Hubs to get help |
-1 | Verification failed, identity information or mobile phone number input was incorrect. | should check the Beneficiary's idNumber or accountName or bank card no is right, when change right can resubmit again |
-1 | The ID number is incorrectly entered, and the ID number is not standard. | the Beneficiary's idNumber is not right, when change right can resubmit again |
-1 | Address structuring failed (xxxxxx,xxxx,xxxx) | please try resubmit the payment, will fix this issue, if not contact xCurrency Hubs to get help |
- Can the same order be called concurrently with the transfer payment api?
No.
- Can the beneficiary's accountName be Chinese PinYin?
No, this should be Simplified Chinese, such as "张三", "李四" etc.
- When get webhook notify callback, what can do next?
Webhook data | Action |
{"event":"payment","id":"{tradeId}","status":"awaiting_transfer"} | can call anync confirm API |
{"event":"payment","id":"{tradeId}","status":"transferring","message":"The order is being processed, please do not repeat the operation."} | no action |
{"event":"payment","id":"{tradeId}","status":"completed", "sourceAmount": 100, "targetAmount": 100} | transfer success and completed |
{"event":"payment","id":"{tradeId}","status":"awaiting_transfer","message":"The order is being processed, please do not repeat the operation."} | same status of awaiting_transfer, but with error message, no action |
{"event":"payment","id":"{tradeId}","status":"failed","message":"The payment cannot be transferred, the payment status is not awaiting_transfer"} | no action, this happen by you call anync confirm API on wrong payment status, this may be happen few |
{"event":"payment","id":"{tradeId}","status":"failed","message":"{error message}"} | no action, will auto cancel the fail payments |
{"event":"payment","id":"{tradeId}","status":"rejected","message":"idNumber had exist or other error message"} | can contact xCurrency Hubs to get to solve it or cancel the payment |