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

json
{ "secretKey": "xxxxxxxxxxxxxx","appKey":"xxxxxxxxx" }

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

json
{ "status": "1", "data": "xxxxxxxxxxxxxx" }

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "bad request, appkey not exist, please contact sales@xcurrency.com" }

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

json
{ "a": "xxxxxxxxxxxxxx" , "b":"xxxxxx","c":{"d":"xxxxxx"}}

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

json
{ "status": "1", "data": true }

Response Status: 400, Body Json Demo

json
{ "status": "10001", "message": "Failed to verify the signature" }

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.

POST /global/payin/transfer/create

Body Param

Select the payin scenario you need

Global Payin For Tuition

Name

Type

Description

orderNo

string

256

Merchant Unique Order No

purpose

string

256

Purpose of remittance Enum: - Tuition - Insurance - Rent

sourceAmount

float

sourceCurrency

string

targetAmount

float

targetCurrency

string

getway

string

256

Enum: - wechat - alipay - bank

payer

object

payer → fullName

string

256

payer → entityType

string

I : Individual B: Business

payer → idNumber

string

256

Certificate number

payer → idType

string

256

- Enum - idcard - passport - driver - residence - workpermit - other

payer → nationality

string

Nationality (ISO 3166-1 two-digit code, e.g. CN, US, JP)

payer → phoneNumber

string

256

payer → phoneCode

string

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

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

I : Individual B: Business

beneficiary → accountInfo

object

beneficiary → accountInfo → name

string

256

beneficiary → accountInfo → number

string

256

beneficiary → nationality

string

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 → orderNo

string

Required

Merchant Unique Order No

data -> message

string

Conditional Required

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

data → gateway → originalId

string

256

Conditional Required

When gateway is wechat, will jump to wechat with originalId

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

json
{ "status": "1", "data": {"tradeId":"xxxxxxx","status":"pending_material"} }

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "Risk Control" }

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

json
{
  "tradeId": "string"
}

Name

Type

Required

Description

tradeId

string

Conditional Required

Uniqued id in the XC system

orderNo

string

Conditional Required

Merchant Unique Order No

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 → orderNo

string

Required

Merchant Unique Order No

data -> message

string

Conditional Required

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

data → gateway → originalId

string

256

Conditional Required

When gateway is wechat, will jump to wechat with originalId

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

json
{ "status": "1" , "data":{"status":"pending","tradeId":"xxxxxxxx"}}

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

2.3 Refresh Gateway Information

➡️

This API is used to refresh gateway information

URI

POST /global/payin/transfer/refresh/gateway

Body Params

Body Json Demo

json
{
  "tradeId": "string"
}

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 → orderNo

string

Required

Merchant Unique Order No

data -> message

string

Conditional Required

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

data → gateway → originalId

string

256

Conditional Required

When gateway is wechat, will jump to wechat with originalId

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

json
{ "status": "1" , "data":{"status":"pending","tradeId":"xxxxxxxx"}}

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

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

json
{
  "event": "payment",
  "id": "*****",
  "status":"pending",
  "amount":"100",
  "targetAmount":"100",
  "sourceAmount":,"100",
  "message":"related error messages"
}

Response

Return JSON data

Response Status: 200, Body Json Demo

javascript
{ "code": "200", "message": ""}

Response Status: 400, Body Json Demo

javascript
{ "status": "-1", "message": "bad request, error message" }

2.5 Query Order Transacation History

➡️

This API is used to query the order transaction records within a certain time period.

URI

GET /global/payin/order/page

Query Params

Name

Type

Required

Description

pages

int

Conditional Required

pageSize

int

Conditional Required

search

string

Conditional Required

can search by order number.

start

string

Conditional Required

Create time start date

end

string

Conditional Required

Create time end date

status

string

Conditional Required

pending, pending_material, awaiting_transfer, transferring, completed, transferred, failed, rejected, overrule, canceled

Response

Return JSON data

Response Status: 200, Body Json Demo

javascript
{
    "status": "1",
    "total": 2,
    "data": [
        {
            "tradeId": "795c357a8a974ffd9f0b1c822c34bece",
            "beneficiaryName": "AAI LIMITED T/A AAMI",
            "orderNo": "R01000000001112",
            "currencyPair": "CNY/CNY",
            "purpose": "Tuition"
        },
        {
            "tradeId": "5c1cd89a0e2e452089837a8e39fffba6",
            "beneficiaryName": "AAI LIMITED T/A AAMI",
            "orderNo": "R01000000001111",
            "currencyPair": "CNY/CNY",
            "purpose": "Tuition"
        }
    ]
}

Response Status: 400, Body Json Demo

Name

Type

Description

status

string

total

int

The total number of orders retrieved

data

array

data → tradeId

string

Uniqued id in the XC system

data → status

string

data → gateway

data → gateway → gateway

data → gateway → appid

data → gateway → orderId

data → gateway → originalId

data → gateway → accountName

data → gateway → accountNumber

data → gateway → payerAccountNumber

data → gateway → bankName

data → gateway → reference

data → createTime

data → completedTime

data → targetAmount

data → sourceAmount

data → payerName

data → beneficiaryName

data → orderNo

The orderNo from merchant system

data → currencyPair

targetCurrency/sourceCurrency

data → purpose

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

shell
--form 'file=@"filepath"' \
--form 'fileName="filename.png"' \
--form 'type="proforma_invoice"'

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

json
{ "status": "1" , "data":{"fileId":"1fnik18921312ndda1091dnad"}}

Response Status: 400, Body Json Demo

json
{ "status": "-1", "message": "The tradeId is not existed" }

API Reference

1. Authentication

1.1 Get Token

1.2 Check

2. Payin Order Manager

2.1 Payin Create

2.2 Query Order Status

2.3 Refresh Gateway Information

2.4 Notification

2.5 Query Order Transacation History

3. Support Docs

3.1 Docs Upload