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

Flow

sequenceDiagram actor S as Sender participant P as Partner participant X as xCurrency Hubs participant B as Paying Agent actor R as Recipent P-->>X:Get a quote:/payout/payment/query/price X-->>P: Return 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.

OpenSecretToolForWin.zip

54331.7KB

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

java
import com.tratao.jcommon.common.BaseServiceException;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.io.IOUtils;
import org.springframework.stereotype.Component;

import javax.crypto.Cipher;
import java.io.ByteArrayOutputStream;
import java.security.*;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;

public class RsaUtil {

	public static final String CHARSET = "UTF-8";
	public static final String RSA_ALGORITHM = "RSA";
	public static final String RSA_ALGORITHM_SIGN = "SHA256WithRSA";
	
	/**
	* sign data
	* @param data the string value
	* @param privateKeyStr private key 
	* @return
	*/
	public String sign(String data,String privateKeyStr){
	  try{
	      //sign
	      KeyFactory keyFactory = KeyFactory.getInstance(RSA_ALGORITHM);
	      PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.decodeBase64(privateKeyStr));
	      privateKey = (RSAPrivateKey) keyFactory.generatePrivate(pkcs8KeySpec);
	      Signature signature = Signature.getInstance(RSA_ALGORITHM_SIGN);
	      signature.initSign(privateKey);
	      signature.update(data.getBytes(CHARSET));
	      return Base64.encodeBase64URLSafeString(signature.sign());
	  }catch(Exception e){
	      throw new RuntimeException("sign data: [" + data + "] throw exception", e);
	  }
	}
	
	/**
	 * decrypt data
	 * @param data sign data
	 * @param privateKeyStr private key
	 * @return
	 */
	public String privateDecrypt(String data,String privateKeyStr){
	    try{
	        KeyFactory keyFactory = KeyFactory.getInstance(RSA_ALGORITHM);
	        PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.decodeBase64(privateKeyStr));
	        privateKey = (RSAPrivateKey) keyFactory.generatePrivate(pkcs8KeySpec);
	        Cipher cipher = Cipher.getInstance(RSA_ALGORITHM);
	        cipher.init(Cipher.DECRYPT_MODE, privateKey);
	        return new String(rsaSplitCodec(cipher, Cipher.DECRYPT_MODE, Base64.decodeBase64(data), privateKey.getModulus().bitLength()), CHARSET);
	    } catch(Exception e){
	        throw new RuntimeException("decrypt sign data: [" + data + "] throw exception", e);
	    }
	}
}

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.

User guide for postman

▶️ Run in Postman

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