📢Welcome to the xCurrency Hubs - Global 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 |
Network Limit | IPs |
Sample API Request Flow API
sequenceDiagram
actor S as Payer
participant P as Partner
participant X as xCurrency Hubs
actor R as Beneficiary
S->>P:Enters Recipient Info and transfer amount
P->>X: 1.Fetch Fx Rate:/global/payout/rate/query/price
P->>X: 2.Request transfer with rate queryNo:/global/payout/transfer/create
S-->>P: Upload Docs for transaction
P-->>X: 3.Request upload:/global/payout/transfer/upload/multipart(Multiple)
P-->>X: 4.Request upload:/global/payout/transfer/upload/completed
X->>X: AML Check
X->>P: 5.Status Update
X-->>P:Return request result
P-->>S: Request Confirmation
S->>S:If OK,proceed with transfer.If fail, correct entered info
X->>X:Check Parnter's Balance
X->>R: Payout
# 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:6.Status Update
P-->>S:Notify Result # Sender agent sends the transfer result to sender. #Sender Agent sends the transfer result notification to Sender
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/jsonAPI 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.)
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";
public String sign(String data,String privateKeyStr){
try{
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);
}
}
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);
}
}
}
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
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 |
