TetherU USDT Payment API Documentation

1. API Documentation Introduction

This documentation is intended for: Technical architects, R&D engineers, and system operation engineers using the TetherU merchant self-service system. Through this document, merchants can understand TetherU's integration technology, product business, integration process, integration specifications and other information to facilitate merchants to successfully complete the integration work.

2. Gateway Integration

Gateway URL: /getway.html

3. Unified Order API

3.1 API Description

Submit Method: POST

3.2 Request Parameters

3.3 Response Parameters

3.4 Request Example

POST /getway.html HTTP/1.1
Content-Type: application/x-www-form-urlencoded

merchantid=1&network=1&orderid=TEST20230101000001&create_time=1626373569&cashier=1¬ifyurl=https://yourdomain.com/notify.php&amount=10.0000&productname=Test Product&sign=A1B2C3D4E5F6G7H8I9J0

3.5 Response Example

When request parameter cashier=1, returns JSON and QR code example:

{
    "status": 1,
    "message": "Order created successfully",
    "data": {
        "qrcode": "data:image/png;base64",
        "account_address": "TFpS9NJ4Djm29RTmax3VonXL8HumgrC4zw",
        "amount": "10.69",
        "platform_orderid": "PYS2025032450595",
        "orderid": "202503201546059331",
        "create_time": "2025-03-20 15:46:05",
        "time_out": 1800,
        "pay_code": "2"
    }
}

When request parameter cashier=2, returns cashier URL example:

{
    "status": 1,
    "message": "Order created successfully",
    "data": {
        "cashier_url": "http://loc.weepay.com:8888/index/index/cashier.html?osn=202503201544321601",
        "amount": "10.78",
        "orderid": "202503201544321601",
        "create_time": "2025-03-20 15:44:32",
        "time_out": 1800,
        "pay_code": "2"
    }
}

Response parameter description:

• status: 1 indicates success, 0 indicates failure
• message: Operation result description
• data: Returned data object
  • qrcode: base64 encoded QR code image (returned when cashier=1)
  • account_address: USDT payment wallet address (returned when cashier=1)
  • cashier_url: Cashier URL address (returned when cashier=2)
  • amount: Payment amount
  • orderid: Order ID
  • create_time: Order creation time
  • time_out: Order validity period (seconds)
  • pay_code: Payment type, 2 indicates TRC20

4. Asynchronous Notification

Submit Method: POST

4.1 Notification Parameters

4.2 Notification Example

{
    "code": 1,
    "msg": "success",
    "data": {
        "merchantid": "1",
        "orderid": "PYS2025032450595",
        "out_trade_id": "202503241012158778",
        "amount": "10.7300",
        "poundage": "0.1073",
        "status": 2,
        "sign": "63FB0B1B2340AB0E0801FE0F249012E4"
    }
}

5. Order Query API

5.1 API Description

Submit Method: POST

URL: /query.html

5.2 Request Parameters

5.3 Response Parameters

5.4 Request Example

POST /query.html HTTP/1.1
Content-Type: application/x-www-form-urlencoded

merchantid=1&orderid=TEST20230101000001&query_type=payment&sign=A1B2C3D4E5F6G7H8I9J0

5.5 Response Example

{
    "code": 1,
    "msg": "Payment order query successful",
    "data": {
        "orderid": "PAY202301010001",
        "out_trade_id": "TEST20230101000001",
        "amount": "10.0000",
        "time_end": "2023-01-01 12:05:30",
        "trade_state": "SUCCESS",
        "order_type": "payment",
        "status_text": "Paid",
        "sign": "B2C3D4E5F6G7H8I9J0K1"
    }
}

6. Payout API

6.1 API Description

Submit Method: POST

URL: /payout.html

6.2 Request Parameters

{
    "orderId": "1234567890",
    "amount": "10.0000",
    "address": "TYour_TRC20_Address_Here"
}

{
    "code": 10001,
    "message": "Order has been maliciously modified."
}
or
{
    "code": 10000,
    "message": "Order verification passed."
}

6.3 Response Parameters

6.4 Request Example

POST /payout.html HTTP/1.1
Content-Type: application/x-www-form-urlencoded

merchantid=1&network=1&orderid=202503281035406411&create_time=1626373569&pay_type=1¬ifyurl=https://yourdomain.com/notify.php&pay_code=2&amount=10.0000&address=TYour_TRC20_Address_Here&sign=A1B2C3D4E5F6G7H8I9J0&version=1.0.0

6.5 Response Example

{
    "code": "success",
    "msg": "Payout order submitted successfully",
    "data": {
        "orderid": "202503281035406411",
        "platform_orderid": "DFS2025032885781",
        "amount": "10.0000",
        "poundage": "1.00",
        "address": "TYour_TRC20_Address_Here",
        "create_time": "2025-03-28 10:35:40",
        "network": "1",
        "pay_code": "TRC20",
        "pay_type": "USDT",
        "status": 1,
        "status_desc": "Payout processing"
    }
}

6.6 Payout Asynchronous Notification

Submit Method: POST

6.7 Payout Asynchronous Notification Example

                {
                    "code": 1,
                    "msg": "success",
                    "data": {
                        "merchantid": 1,
                        "orderid": "DFS2025032846917",
                        "out_trade_id": "202503281034025239",
                        "amount": "10.0000",
                        "transaction_id": "",
                        "status": 2,
                        "time": 1743944210,
                        "remark": "Paid",
                        "sign": "DE987378BAC0AC03976A79AD17060310"
                    }
                }

7. Balance Query API

7.1 API Description

Submit Method: POST

URL: /balance.html

7.2 Request Parameters

7.3 Response Parameters

7.4 Request Example

POST /balance.html HTTP/1.1
Content-Type: application/x-www-form-urlencoded

merchantid=1&timestamp=1711603200&sign=A1B2C3D4E5F6G7H8I9J0

7.5 Response Example

{
    "code": 1,
    "msg": "Balance query successful",
    "data": {
        "merchantid": "1",
        "username": "merchant_demo",
        "balance": "1000.0000",
        "currency": "USDT",
        "query_time": "2025-03-28 10:35:40"
    }
}

8. Signature Algorithm

The general steps for signature generation are as follows:

Step 1: Set all sent or received data as array M, sort the non-empty parameter values in array M by parameter name ASCII code from small to large (dictionary order), and concatenate them into a string stringA using URL key-value pair format (i.e., key1+value1+key2+value2...).

Step 2: Append the application private_key to the end of stringA to get stringSignTemp string, perform MD5 operation on stringSignTemp, and convert all characters in the resulting string to uppercase to get the sign value signValue.

Example:

Original parameters:

{
    "amount": "300.0000",
    "callbackurl": "http://www.baidu.com/callbackurl.html",
    "cashier": "2",
    "create_time": "1626376050",
    "default_currency": "cny",
    "merchantid": "2",
    "network": "1",
    "notifyurl": "http://www.baidu.com/notifyurl.html",
    "orderid": "out2021071587481",
    "pay_code": "1",
    "pay_type": "1",
    "productname": "Test Product",
    "version": "1.0.0"
}

Private key:

K0d8F434vUjVc88vxkDxmC0z8cj0UZ

Step 1: Sort by parameter name ASCII code from small to large

amount300.0000callbackurlhttp://www.baidu.com/callbackurl.htmlcashier2create_time1626376050default_currencycnymerchantid2network1notifyurlhttp://www.baidu.com/notifyurl.htmlorderidout2021071587481pay_code1pay_type1productnameTest Productversion1.0.0

Step 2: Append private key

stringSignTemp="amount300.0000callbackurlhttp://www.baidu.com/callbackurl.htmlcashier2create_time1626376050default_currencycnymerchantid2network1notifyurlhttp://www.baidu.com/notifyurl.htmlorderidout2021071587481pay_code1pay_type1productnameTest Productversion1.0.0K0d8F434vUjVc88vxkDxmC0z8cj0UZ"

Step 3: Generate MD5 and convert to uppercase

sign=MD5(stringSignTemp).toUpperCase()

Java Code Example:

import java.security.MessageDigest;
import java.util.*;

public class WeePaySignUtil {
    private static final String CHARSET = "UTF-8";
    
    /**
     * Generate signature
     * @param params Request parameters
     * @param privateKey Merchant private key
     * @return Signature result
     */
    public static String generateSign(Map params, String privateKey) {
        try {
            // 1. Filter empty values and sign parameter
            Map filteredParams = new TreeMap<>();
            for (Map.Entry entry : params.entrySet()) {
                if (entry.getValue() != null && !entry.getValue().isEmpty() 
                    && !"sign".equals(entry.getKey())) {
                    filteredParams.put(entry.getKey(), entry.getValue());
                }
            }
            
            // 2. Sort by parameter name ASCII code from small to large
            StringBuilder stringA = new StringBuilder();
            for (Map.Entry entry : filteredParams.entrySet()) {
                stringA.append(entry.getKey()).append(entry.getValue());
            }
            
            // 3. Append private key
            String stringSignTemp = stringA.toString() + privateKey;
            
            // 4. MD5 encryption and convert to uppercase
            return md5(stringSignTemp).toUpperCase();
        } catch (Exception e) {
            throw new RuntimeException("Signature generation failed", e);
        }
    }
    
    /**
     * MD5 encryption
     * @param text Text to be encrypted
     * @return Encryption result
     */
    private static String md5(String text) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] bytes = md.digest(text.getBytes(CHARSET));
        return bytesToHex(bytes);
    }
    
    /**
     * Convert byte array to hex string
     */
    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
    
    /**
     * Usage example
     */
    public static void main(String[] args) {
        // Configuration
        String merchantId = "1";
        String privateKey = "K0d8F434vUjVc88vxkDxmC0z8cj0UZ";
        
        // Build request parameters
        Map params = new HashMap<>();
        params.put("merchantid", merchantId);
        params.put("network", "1");
        params.put("orderid", "TEST" + System.currentTimeMillis());
        params.put("create_time", String.valueOf(System.currentTimeMillis() / 1000));
        params.put("cashier", "1");
        params.put("notifyurl", "https://yourdomain.com/notify.php");
        params.put("amount", "10.0000");
        params.put("productname", "Test Product");
        
        // Generate signature
        String sign = generateSign(params, privateKey);
        params.put("sign", sign);
        
        // Print request parameters
        System.out.println("Request parameters:");
        for (Map.Entry entry : params.entrySet()) {
            System.out.println(entry.getKey() + " = " + entry.getValue());
        }
        
        // Send HTTP request example
        try {
            String response = sendHttpRequest(params);
            System.out.println("Response result: " + response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    /**
     * Send HTTP request example
     */
    private static String sendHttpRequest(Map params) throws Exception {
        // Here use HttpClient to send request, need to add related dependencies
        // It is recommended to use OkHttp or Apache HttpClient for actual projects
        StringBuilder urlParams = new StringBuilder();
        for (Map.Entry entry : params.entrySet()) {
            if (urlParams.length() > 0) {
                urlParams.append("&");
            }
            urlParams.append(entry.getKey()).append("=")
                    .append(java.net.URLEncoder.encode(entry.getValue(), CHARSET));
        }
        
        // This is just an example, actual projects need to implement according to specific circumstances
        return "HTTP request implementation code";
    }
}

9.1 PHP Code Example

/**
 * Generate signature
 * 
 * @param array $data Request parameters
 * @param string $privateKey Merchant private key
 * @return array Contains signature and signature string
 */
function makeSign($data, $privateKey)
{
    // Remove empty values and signature parameters from array
    $para_filter = array();
    foreach ($data as $key => $val) {
        if ($key == "sign" || $val === "" || $val === null) {
            continue;
        }
        $para_filter[$key] = $val;
    }

    // Sort by key name in dictionary order
    ksort($para_filter);
    reset($para_filter);

    // Concatenate string
    $str_sign = "";
    foreach ($para_filter as $key => $val) {
        $str_sign .= $key . $val;
    }

    // Add private key
    $str_sign .= $privateKey;

    // MD5 encryption and convert to uppercase
    $sign = strtoupper(md5($str_sign));

    return [
        'sign'     => $sign,
        'str_sign' => $str_sign
    ];
}

9.2 Order Request Example

// Configuration information
$config = [
    'merchant_id' => 1,
    'private_key' => 'your_private_key',
    'notify_url'  => 'https://yourdomain.com/notify.php',
    'gateway_url' => 'https://payment-domain/getway.html',
];

// Assemble order parameters
$timestamp = time();
$orderid   = date('YmdHis') . mt_rand(1000, 9999);

$params = [
    'merchantid'  => $config['merchant_id'],
    'network'     => 1,
    'orderid'     => $orderid,
    'create_time' => $timestamp,
    'cashier'     => 1,
    'notifyurl'   => $config['notify_url'],
    'amount'      => '10.0000',
    'productname' => 'Test Product',
];

// Generate signature
$sign_data = makeSign($params, $config['private_key']);
$params['sign'] = $sign_data['sign'];

// Send HTTP request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $config['gateway_url']);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Handle response
$result = json_decode($response, true);
print_r($result);

9.3 Asynchronous Notification Processing Example

// Get all request parameters
$data = $_POST;

// Get merchant information (should be retrieved from database in actual application)
$private_key = 'your_private_key';

// Verify signature
$sign = $data['sign'];
unset($data['sign']);

// Signature verification
$sign_data = makeSign($data, $private_key);
if ($sign_data['sign'] === $sign) {
    // Verification successful, process order logic
    // ...
    
    // Return success identifier
    echo 'success';
} else {
    // Signature verification failed
    echo 'fail';
}

9.4 Balance Query Example

// Configuration information
$config = [
    'merchant_id' => 1,
    'private_key' => 'your_private_key',
    'balance_url' => 'https://payment-domain/balance.html',
];

// Assemble parameters
$timestamp = time();

$params = [
    'merchantid'  => $config['merchant_id'],
    'timestamp'   => $timestamp,
];

// Generate signature
$sign_data = makeSign($params, $config['private_key']);
$params['sign'] = $sign_data['sign'];

// Send HTTP request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $config['balance_url']);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Handle response
$result = json_decode($response, true);
if ($result['code'] == 1) {
    echo "Balance query successful: " . $result['data']['balance'] . " " . $result['data']['currency'] . "\n";
} else {
    echo "Query failed: " . $result['msg'] . "\n";
}

print_r($result);