1. Authentication
1.1 Get Token
The API is used to obtain
the token
, which is set on the request header. The token
expires after one hour. You can get a new token
before it
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 Status: 200, Body Json Demo
Response Status: 400, Body Json Demo
1.2 Check
The API is used to verify the sign data, will return
true
when the sign data is correct, and 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
2. Payin Order Manager
2.1 Payin Create
The API is used to create a payin on xCurrency hubs, so orderNo should be unique. The same order number can create a payin once.
When the HTTP status is
400
, and the response data has not traded
, the order failed on xCurrency Hubs' side. Please check the response message or contact xCurrency Hubs' team.- URI
POST /global/payin/transfer/create
- Body Param
Select the payin scenario you need
Name
Type
Description
orderNo
string
256
Merchant Unique Order No
purpose
string
256
Purpose of remittance
Enum:
- Tuition
- Insurance
- Rent
sourceAmount
float
sourceCurrency
string
3
targetAmount
float
targetCurrency
string
3
getway
string
256
Enum:
- wechat
- alipay
- bank
payer
object
payer → fullName
string
256
payer → entityType
string
1
I : Individual
B: Business
payer → idNumber
string
256
Certificate number
payer → idType
string
256
- Enum
- idcard
- passport
- driver
- residence
- workpermit
- other
payer → nationality
string
2
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → phoneNumber
string
256
payer → phoneCode
string
3
payer → email
string
256
payer → emergencyPhone
string
256
payer → gender
string
256
Enum:
- Male
- FeMale
payer → address
object
payer → address → state
string
256
payer → address → city
string
256
payer → address → street
string
256
payer → address → postCode
string
256
payer → address → country
string
2
Country of Address (ISO 3166-1 two-digit code, e.g. CN, US, JP)
payer → idIssueDate
string
256
Certificate Issue Date (format YYYY-MM-DD)
payer → idExpiryDate
string
256
Certificate Deadline (format YYYY-MM-DD)
payer → relationship
string
256
Relationship Between Payer and RealPayer
Enum:
- Self
- Spouse
- Parent
- Children
- Sibling
- Grandparent
- Grandchildren
payer → realPayer
object
When the relationship ≠ Self
payer → realPayer → fullName
string
256
payer → realPayer → idNumber
string
256
Certificate Number
payer → realPayer → idType
string
256
- Enum
- idcard
- passport
- driver
- residence
- workpermit
- other
payer → realPayer → idIssueDate
string
256
Certificate Issue Date (format YYYY-MM-DD)
payer → realPayer → idExpiryDate
string
256
Certificate Deadline (format YYYY-MM-DD)
beneficiary
object
beneficiary → fullName
string
256
beneficiary → entityType
string
1
I : Individual
B: Business
beneficiary → accountInfo
object
beneficiary → accountInfo → name
string
256
beneficiary → accountInfo → number
string
256
beneficiary → nationality
string
2
Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)
fileIds
string[]
256
- Response
Name
Type
Required
Description
status
string
Required
1 : Success
Other status please reference appendix
message
string
Conditional Required
if the status is not 1,the err message is responded
data
object
Conditional Required
data → tradeId
string
256
Required
Uniqued id in the XC system
data → status
string
256
Required
string
data → gateway
object
Required
data → gateway → gateway
string
256
Required
Enum
- alipay
- wechat
- bank
data → gateway → appid
string
256
Conditional Required
When gateway is wechat/alipay
data → gateway → orderId
string
256
Conditional Required
When gateway is wechat/alipay, will jump to wechat/alipay with orderId
date → gateway → accountName
string
Conditional Required
When gateway is bank
data → gateway → accountNumber
string
256
Conditional Required
When gateway is bank
data → gateway → bankName
string
256
Conditional Required
When gateway is bank
data → gateway → reference
string
256
Conditional Required
When gateway is bank, will display the bank transfer reference
Response Status: 200, Body Json Demo
Response Status: 400, Body Json Demo
2.2 Query Order Status
This API is used to query the order status
- URI
POST /global/payin/transfer/query/status
- Body Params
Body Json Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
- Response
Name
Type
Required
Description
status
string
Required
1 : Success
Other status please reference appendix
message
string
Conditional Required
if the status is not 1,the err message is responded
data
object
Conditional Required
data → tradeId
string
256
Required
Uniqued id in the XC system
data → status
string
256
Required
string
data → gateway
object
Required
data → gateway → gateway
string
256
Required
Enum
- alipay
- wechat
- bank
data → gateway → appid
string
256
Conditional Required
When gateway is wechat/alipay
data → gateway → orderId
string
256
Conditional Required
When gateway is wechat/alipay, will jump to wechat/alipay with orderId
date → gateway → accountName
string
Conditional Required
When gateway is bank
data → gateway → accountNumber
string
256
Conditional Required
When gateway is bank
data → gateway → bankName
string
256
Conditional Required
When gateway is bank
data → gateway → reference
string
256
Conditional Required
When gateway is bank, will display the bank transfer reference
Response Status: 200, Body Json Demo
Response Status: 400, Body Json Demo
2.3 Refresh Gateway Information
This API is used to query the order status
- URI
POST /global/payin/transfer/refresh/gateway
- Body Params
Body Json Demo
Name
Type
Required
Description
tradeId
string
Required
Uniqued id in the XC system
- Response
Name
Type
Required
Description
status
string
Required
1 : Success
Other status please reference appendix
message
string
Conditional Required
if the status is not 1,the err message is responded
data
object
Conditional Required
data → tradeId
string
256
Required
Uniqued id in the XC system
data → status
string
256
Required
string
data → gateway
object
Required
data → gateway → gateway
string
256
Required
Enum
- alipay
- wechat
- bank
data → gateway → appid
string
256
Conditional Required
When gateway is wechat/alipay
data → gateway → orderId
string
256
Conditional Required
When gateway is wechat/alipay, will jump to wechat/alipay with orderId
date → gateway → accountName
string
Conditional Required
When gateway is bank
data → gateway → accountNumber
string
256
Conditional Required
When gateway is bank
data → gateway → bankName
string
256
Conditional Required
When gateway is bank
data → gateway → reference
string
256
Conditional Required
When gateway is bank, will display the bank transfer reference
Response Status: 200, Body Json Demo
Response Status: 400, Body Json Demo
2.4 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 /xxxxxxxx
- Headers
appkey
: xCurrency Hubs' appkey is used for secondary verification and is not required.
- Body Params
Body Json Demo
- Response
Return JSON data
Response Status: 200, Body Json Demo
Response Status: 400, Body Json Demo
3. Support Docs
3.1 Docs Upload
Upload supporting material order by Multipart
- URI
POST /global/payin/transfer/upload/multipart
- Form Data Params
Form Data Demo
Name | Type | Required | Description |
file | file | Required | File |
type | string | Required | File Type,
Enum:
- bill
- offer
- identification_front
- identification_back
- ME
- MC
- SIGN
- HR
- NCOM
- BC
- EC
- POIPBE
- COI
- RSIBF
- TC
- proforma_invoice
- purchase_order
- logistics_material
- export_declaration
- communication_record
- beneficiary_id_card
- beneficiary_power_attorney
- historical_transaction_material
- proof_purchase
- other |
fileName | string | Required | bill.png |
- Response
Response Status: 200, Body Json Demo
Response Status: 400, Body Json Demo