Digital Pay Api
- Digital currency transactions support currencies: (USDT/BTC/ETH/TRX). If you want to use digital currency transactions, please set orderType=1.
- Our digital currency collection orders are divided into two modes: with order mode and without order mode.
- The cashier versions v1.0 and v3.0 belong to the order-only mode; v2.0 and v4.0 belong to the order-free mode.
- v1.0 and v2.0 only display payment addresses, v3.0 and v4.0 display both QR codes and payment addresses.
- When using digital currency for transactions, if the digital currency type is specified, the currency and chain network are required. You need to tell us which digital currency and chain network you want to use (TRC20/BEP20/OMNI/ERC20 /TRX) to trade.
# Code example
- The code example is for reference only, please refer to request parameter description for specific parameter description
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.security.spec.InvalidKeySpecException;
import java.util.Map;
import java.util.TreeMap;
public class TopPayDemo {
private static final String MCH_ID = "S820211021094748000001";
private static final String PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2JoMfFqLsSJjAiCahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB"; // platform public key
private static final String MCH_PRIVATE_KEY = "MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAJU8gKFKD0luIYx7X8+JRdCIE0UDBctS6LjXxWLEv/EO7jDBTid6zYP1KmNgpd2DAWWtBFBSQ+gcNwVZZSBHJiSDqVvvJVs2FEbeBvfdv4X93+IYRAXksBasSW5Tpdshbo82pVL4V7wuKCuFLk9UxBHbpQjWAbfyF66RmwIbZD71AgMBAAECgYBjPe7UU2nDDSfmQg0++CyjNjqKRC5QPfxhH6w1uF1kMueXKJWOj42n2RutJpJmsj31nY8m0u4xpsG4HvCu/GGSFhhKZCHLvzp41oY2ubYj9nuFNU//81LycQjulWo2y0UUBY0k2piEt+SwPaiUNbT6nMxNMjlnjRe2okp/3rw+KQJBANG3YlZWoVbCEqzy64bJJLxiPsCA5ErGB0NzRGitq44xkhqGtR8ZZQyVz40pruNa58d73O2xyJSy5+fmZGn4E+sCQQC2LBnguj0CSCKub0mPDcunTTz9V79VXBBZdlB1/YGmRUx2s4sQrJNZS7rL4EqBQ3maIRnG+s+AXCSTfsYrV6CfAkEAxugnVfpelhoGepEAgNuggyivmgfl/2Gpm/jk5l/qOjib+ZrQiQmeBPzGWX4yiSM8eMDrP2sC8r5pJFMp5DRONwJBAJ4n4XuSFJ9jgwCPy3vvzSv9SYLk6E6yM9uHdUlKgoGYzk6Lh6M9QFuY/J49plFdBDiEnj16yCU3WeXXfTJpzB8CQQDMNMR/rIOTE9xGybS3mlQbt22AUnO6XhupWcckEKW4nPGxATwYBQzCY3i/9FTGN0vA+9ZPC2cwHtNxI2kXf3Vp"; // merchant private key
private static final String payUrl = "https://id-openapi.toppay.asia/gateway/prepaidOrder";
private static final String cashUrl = "https://id-openapi.toppay.asia/gateway/cash";
private static final String payNotify = "your notify url";
private static final String cashNotify = "your notify url";
public static void main(String[] args) throws Exception {
pay();
}
private static void pay() throws Exception {
Map<String, String> requestParams = new TreeMap<>();
requestParams.put("merchantCode", MCH_ID);
requestParams.put("orderType", "1");
requestParams.put("mchUserId", "100001");
requestParams.put("method", "USDT");
requestParams.put("orderNum", "T1642592278863");
requestParams.put("payMoney", "150");
requestParams.put("name", "JackMa");
requestParams.put("phone", "082122965511");
requestParams.put("email", "[email protected]");
requestParams.put("notifyUrl", payNotify);
requestParams.put("dateTime", "20220101235959");
requestParams.put("expiryPeriod", "1440");
requestParams.put("currency", "USDT");
requestParams.put("netWork", "TRC20");
requestParams.put("orderVersion", "v1.0");
StringBuilder stringBuilder = new StringBuilder();
for (String key : requestParams.keySet()) {
stringBuilder.append(requestParams.get(key));
}
String keyStr = stringBuilder.toString();
System.out.println("keyStr:" + keyStr);
String signedStr = TopPayRequestUtil.privateEncrypt(keyStr, TopPayRequestUtil.getPrivateKey(MCH_PRIVATE_KEY));
requestParams.put("sign", signedStr);
String postJson = new Gson().toJson(requestParams);
System.out.println("Post Json Params:" + postJson);
String responseJson = TopPayRequestUtil.doPost(payUrl, postJson);
System.out.println("Response Msg:" + responseJson);
}
}
# Request Address
- Cashier mode(mode 1): Use the payment information shown in the checkout link
- Request method: POST
- Request address: https://id-openapi.toppay.asia/gateway/prepaidOrder
- Direct connection mode (Mode 2): Obtain payment information directly (applicable to merchants with their own checkout page)
- Request method: POST
- Request address: https://id-openapi.toppay.asia/gateway/pay
# Request parameters
Note: Do not fill in Chinese in all parameters! ! !
- Cashier mode(mode 1):
Param | Type | Required | Description | Example |
---|---|---|---|---|
merchantCode | string(32) | Y | merchant ID,Get it in merchant background | S820211021094748000001 |
orderType | string(10) | Y | order type | 1-Digital currency transaction |
mchUserId | string(32) | Y | Merchant user ID (your unique user ID, please do not pass special characters, spaces, etc.) | 100001 |
method | string(10) | N | method 1.If you need to specify a payment method, you can choose one of the example payment method lists on the right. 2.If you don’t specify a payment method, you don’t need to pass this parameter, and you can choose a certain payment method on our cashier page payment method. | USDT BTC ETH TRX |
currency | string(14) | N | currency (If the payment method is specified, it must be passed) | USDT |
netWork | string(30) | N | chain network (If the payment method is specified, it must be passed) | TRC20 |
orderNum | string(32) | N | Merchant order number(If there is an order mode, it must be transmitted, and if there is no order mode, it will not be transmitted) | TEST123456789 |
payMoney | int(10) | Y | Payment money (Maximum allowed 6 decimal places) | 1.000001 |
notifyUrl | string(100) | Y | notify url for call back | https://host:port/notifyUrl |
dateTime | string(32) | Y | timestamp (format: yyyyMMddHHmmss) | 20190101235959 |
expiryPeriod | int(5) | Y | expired time (unit: minute) | 720 |
name | string(16) | Y | merchant name | Jack |
string(64) | Y | [email protected] | ||
phone | string(14) | Y | phone | 081234567890 |
orderVersion | string(10) | Y | Cashier version (v1.0 and v3.0 belong to the single mode version; v2.0 and v4.0 belong to the single mode version) | v1.0 |
sign | string(255) | Y | sign | fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+XxO2jo92dyjKHFU9/4hNECilMooOcH |
- Direct connection mode (Mode 2):
Param | Type | Required | Description | Example |
---|---|---|---|---|
merchantCode | string(32) | Y | merchant ID,Get it in merchant background | S820211021094748000001 |
orderType | string(10) | Y | order type | 1-Digital currency transaction |
mchUserId | string(32) | Y | Merchant user ID (your unique user ID, please do not pass special characters, spaces, etc.) | 100001 |
method | string(10) | Y | method | USDT BTC ETH TRX |
currency | string(14) | Y | currency | USDT |
netWork | string(30) | Y | chain network | TRC20 |
orderNum | string(32) | N | Merchant order number(If there is an order mode, it must be transmitted, and if there is no order mode, it will not be transmitted) | TEST123456789 |
payMoney | int(10) | Y | Payment money (Maximum allowed 6 decimal places) | 1.000001 |
notifyUrl | string(100) | Y | notify url for call back | https://host:port/notifyUrl |
dateTime | string(32) | Y | timestamp (format: yyyyMMddHHmmss) | 20190101235959 |
expiryPeriod | int(5) | Y | expired time (unit: minute) | 720 |
name | string(16) | Y | merchant name | Jack |
string(64) | Y | [email protected] | ||
phone | string(14) | Y | phone | 081234567890 |
sign | string(255) | Y | sign | fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+XxO2jo92dyjKHFU9/4hNECilMooOcH |
# Request example
- Cashier mode(mode 1):(The method parameter does not need to be passed.)
{
"merchantCode": "S820211021094748000001",
"orderType": "1",
"mchUserId": "10001",
"method": "USDT",
"currency": "USDT",
"netWork": "TRC20",
"orderNum": "T1642593166888",
"payMoney": "1.00000001",
"notifyUrl": "your notify url",
"dateTime": "2022-01-01 10:55:00",
"expiryPeriod": "1440",
"name": "JackMa",
"email": "[email protected]",
"phone": "08123456789",
"sign": "fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+Xxd1yc9fpkpTx5UQEDTgmhwdCKBkhHVsx2AiQbYDxZ5WBuU1GZeiJ"
}
- Direct connection mode (Mode 2):(The method parameter must be passed)
{
"merchantCode": "S820211021094748000001",
"orderType": "1",
"mchUserId": "10001",
"method": "USDT",
"currency": "USDT",
"netWork": "TRC20",
"orderNum": "T1642593166888",
"payMoney": "1.00000001",
"notifyUrl": "your notify url",
"dateTime": "2022-01-01 10:55:00",
"expiryPeriod": "1440",
"name": "JackMa",
"email": "[email protected]",
"phone": "08123456789",
"sign": "fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+Xxd1yc9fpkpTx5UQEDTgmhwdCKBkhHVsx2AiQbYDxZ5WBuU1GZeiJ"
}
# Response parameters
Parameters | Type | Required | Description | Example |
---|---|---|---|---|
platRespCode | String | Y | Whether the requested business was successful | FAIL\SUCCESS |
platRespMessage | String | Y | Interface response information prompt | Request Transaction Success |
mchUserId | String | Y | merchant user id | 10001 |
platOrderNum | String | Y | platform order number | PI1453242857400963072 |
orderNum | String | Y | merchant order number | 23645782 |
currency | String | Y | currency | USDT |
netWork | String | Y | net work | TRC20 |
payMoney | String | Y | amount | 1.000001 |
url | String | Y | In mode 1, return to the cashier link | Returned when 'platRespCode' is SUCCESS |
inAddress | String | Y | In mode 2, return wallet address | Returned when 'platRespCode' is SUCCESS |
# Response message example
- Mode 1 response message example (url is the checkout link)
{
"platRespCode": "SUCCESS",
"url": "https://id-openapi.toppay.asia/cashier?orderNum=PRE1626161123977859130123",
"mchUserId": "10001",
"platOrderNum": "PRE1626161123977859130",
"payMoney": "1.00000000",
"currency": "USDT",
"netWork": "TRC20",
"platSign": "U79dat+VITTQ8xAI1wsxtFlK2DwcVvZ6ypC+QFIDaEy4oNxZECRy+INAcqIWZHL1m6/pge1SOEbVss8ZZPsZbtRZiefhtH+6qyu99MU+1rGdu+oSXSNhP4+2aDucg/SylS3+TkjKJf+IowTX7d2TJEbDh011JLOc9zglkhqVEc0FVIbBmKInZ/+TaLhDfFt6Sqmf85GCP7V5JwW1arIUwUjlGkCs3TtvHfpDVaMi2fl+cfNGYSrCOZfursVwjiwJmka+44FyaGrrEOE9tKwODiZo/jg9FLZnp2eRZwIIwef8CFg7eqx13uo/y61g0D9pzH17IVcr7Mc8BrweO7X4Pw==",
"platRespMessage": "Request Transaction Success"
}
- Mode 2 response message example
{
"platRespCode": "SUCCESS",
"inaddress": "T34YVS9GJ53OTJWIUFVOI",
"mchUserId": "10001",
"platOrderNum": "PRE1626161123977859130",
"payMoney": "1.00000000",
"currency": "USDT",
"netWork": "TRC20",
"platSign": "U79dat+VITTQ8xAI1wsxtFlK2DwcVvZ6ypC+QFIDaEy4oNxZECRy+INAcqIWZHL1m6/pge1SOEbVss8ZZPsZbtRZiefhtH+6qyu99MU+1rGdu+oSXSNhP4+2aDucg/SylS3+TkjKJf+IowTX7d2TJEbDh011JLOc9zglkhqVEc0FVIbBmKInZ/+TaLhDfFt6Sqmf85GCP7V5JwW1arIUwUjlGkCs3TtvHfpDVaMi2fl+cfNGYSrCOZfursVwjiwJmka+44FyaGrrEOE9tKwODiZo/jg9FLZnp2eRZwIIwef8CFg7eqx13uo/y61g0D9pzH17IVcr7Mc8BrweO7X4Pw==",
"platRespMessage": "Request Transaction Success"
}
- Example of a failure response message
{
"platRespCode": "FAIL",
"platRespMessage": "the orderNum already exists"
}
# Collect asynchronous notification
- Please note: The current business will only receive callback notifications when the order payment is successful.
- When performing signature verification, you must use the platform public key provided in Merchant Backstage-Receipt and Payment Configuration-API Configuration to decrypt! ! !
- Digital currency has two special situations: no order mode and the payment amount does not match the order amount. For this reason, we have adjusted the asynchronous notification as follows:
- 1. If it is the above special situation, we will generate a new successful order for notification. You need to verify based on the notification information and generate a new order.
- 2. Check whether the order exists in your system based on the notified merchant order number (orderNum). It is recommended that you also store our platform order number (platOrderNum) when the order is successfully placed and perform a two-step verification.
- 3. Judge based on the parameter specialStatus of the notification (0-default, 1-special status). If it is 1, it is judged to be the above special situation.
- After TopPay results are notified asynchronously, the SUCCESS string must be responded to, without quotation marks, and not in Json format. Otherwise TopPay will continue to initiate 5 notifications to the downstream.
import com.google.gson.JsonObject;
public class TopPayNotify {
private static final String MCH_ID = "S820211021094748000001"; // merchant code
private static final String PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2JoMfFqLsSJjAiCahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB"; // platform public key
public static void main(String[] args) throws Exception {
JsonObject notifyBody = new jsonObject();
boolean verifyResult = TopPayRequestUtil.verifySign(notifyBody,PLAT_PUBLIC_KEY);
if (verifyResult) {
// ... do something
} else {
// ... do something
}
}
}
# Notify Params
Parameters | Description | Example |
---|---|---|
code | response code | 00 |
msg | response message | SUCCESS |
mchUserId | merchant user id | 10001 |
platOrderNum | platform order number | BK_1563278763273 |
orderNum | merchant order number | T1231511321515 |
method | payment method | USDT |
currency | currency | USDT |
netWork | chain network | TRC20 |
status | payment status | View order status description |
payMoney | amount | 100000 |
payFee | fee | 500 |
hashCode | hashCode | 5e5c356af0ewrhgnf3d757h8a6a5506cc66354620 |
sendAddress | send address | TDBbbeAB32WE576DVGE82GEC5BhsZs4 |
specialStatus | specialStatus 0-default 1-special status | 0 |
platSign | sign | ja6R8eukQY9jc8zrhtf34654ungj7u8sdgdfjfs |
# Pay api callback notify example
{
"code": "00",
"msg": "SUCCESS",
"mchUserId": "10001",
"platOrderNum": "BCA1483771634191044608",
"orderNum": "T1642593166888",
"method": "USDT",
"currency": "USDT",
"netWork": "TRC20",
"status": "SUCCESS",
"payMoney": "1.0000001",
"payFee": "0.000016",
"hashCode": "5e5c356af0ewrhgnf3d757h8a6a5506cc66354620",
"sendAddress": "TDBbbeAB32WE576DVGE82GEC5BhsZs4",
"specialStatus": "0",
"platSign": "ja6R8eukQY9jc8zrhtf34654ungj7u8sdgdfjfs"
}