logo

Developer Guide

Welcome to the xCurrency Hubs - 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 Hubs 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 Hubs to validate the transfer information. X->>B:Request transfer validation#xCurrency Hubs forwards the request to Paying Agent B->>X:Return validation result #Paying Agent validates the transfer info and returns the result to xCurency Hubs 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 Hubs to Paying Agent. #X-->>P: Transfer Info P->>X: Confirm transfers:/payout/payment/transfer/async #Sender agent complates internal checks such as KYC and AML screening on the Sender, then sends the transfer request to xCurrency Hubs X-->>P: OK X->>P: Status Update X->>X:Check Parnter's Balance X->>B: Payout Instruction #xCurrency Hubs forwards the request to the Paying Agent B-->>X: Payout Result # Paying Agent sends the transfer to xCurrency Hubs. xCurrency Hubs 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

KYC Documents

Transfer related KYC files through the SFTP service, Please see refer to SFTP Use Tutorial (Client)

Postman Collections

In order to facilitate the use of our APIs, we provide the Postman file, you can click the following button to open the Postman app. By interacting with Postman App, you can directly test our APIs, which is convenient for you to access quickly.

Java SDK

This Java SDK is supported the APIs.

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 /xcurrency/webhook
  • Headers
    • appkey: xCurrency Hubs' appkey which is used for secondary verification, not required.
  • Body Params { "event": "payment", "id": "xxxxxxx", "status": "", "message": ""}
    • Name
      Description
      event
      - payment: payment information- balance: balance information
      id
      - payment: tradeId- balance: walletId
      status
      status
      amount
      only exists if event is balance
      targetAmount
      Subject to the actual targetAmount by transfer success, only exists if status is completed
      sourceAmount
      Subject to the actual sourceAmount by transfer success, only exists if status is completed
      message
      related error messages
  • Response Body {"code":"200","Message":""}
    • Name
      Description
      code
      the value is 200 mean success, if on xCurrency hubs' side not receive the code of 200, will try to callback for 16 times within 2 hours
      Message
      error response message

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