泰达U选 API接口开发文档

1. API开发文档简介

本文阅读对象：使用 泰达U选 商户自服务系统的技术架构师、研发工程师、系统运维工程师。通过本文档，商户可了解 泰达U选 接入的技术、接入的产品业务、接入的流程、接入规范等信息，以便于商户顺利完成接入工作。

2. 接入网关

网关地址：/getway.html

3. 统一下单接口

3.1 接口说明

提交方式：POST

3.2 请求参数

3.3 返回参数

3.4 请求示例

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://您的域名/notify.php&amount=10.0000&productname=测试商品&sign=A1B2C3D4E5F6G7H8I9J0

3.5 返回示例

当请求参数cashier=1时，返回JSON和二维码示例：

{
    "status": 1,
    "message": "订单创建成功",
    "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"
    }
}

当请求参数cashier=2时，返回收银台URL示例：

{
    "status": 1,
    "message": "订单创建成功",
    "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"
    }
}

返回参数说明：

• status: 1表示成功，0表示失败
• message: 返回操作结果说明
• data: 返回的数据对象
  • qrcode: base64编码的二维码图片(cashier=1时返回)
  • account_address: USDT收款钱包地址(cashier=1时返回)
  • cashier_url: 收银台URL地址(cashier=2时返回)
  • amount: 支付金额
  • orderid: 订单号
  • create_time: 订单创建时间
  • time_out: 订单有效期(秒)
  • pay_code: 支付类型，2表示TRC20

4. 异步通知

提交方式：POST

4.1 通知参数

4.2 通知示例

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

5. 订单查询接口

5.1 接口说明

提交方式：POST

地址：/query.html

5.2 请求参数

5.3 返回参数

5.4 请求示例

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

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

5.5 返回示例

{
    "code": 1,
    "msg": "查询支付订单成功",
    "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": "已支付",
        "sign": "B2C3D4E5F6G7H8I9J0K1"
    }
}

6. 代付接口

6.1 接口说明

提交方式：POST

地址：/payout.html

6.2 请求参数

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

{
    "code": 10001,
    "message": "订单被恶意修改。"
}
或者
{
    "code": 10000,
    "message": "订单验证通过。"
}

6.3 返回参数

6.4 请求示例

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://您的域名/notify.php&pay_code=2&amount=10.0000&address=TYour_TRC20_Address_Here&sign=A1B2C3D4E5F6G7H8I9J0&version=1.0.0

6.5 返回示例

{
    "code": "success",
    "msg": "代付订单提交成功",
    "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": "代付处理中"
    }
}

6.6 代付异步通知

提交方式：POST

6.7 代付异步通知示例

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

7. 余额查询接口

7.1 接口说明

提交方式：POST

地址：/balance.html

7.2 请求参数

7.3 返回参数

7.4 请求示例

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

merchantid=1&timestamp=1711603200&sign=A1B2C3D4E5F6G7H8I9J0

7.5 返回示例

{
    "code": 1,
    "msg": "查询余额成功",
    "data": {
        "merchantid": "1",
        "username": "merchant_demo",
        "balance": "1000.0000",
        "currency": "USDT",
        "query_time": "2025-03-28 10:35:40"
    }
}

8. 签名算法

签名生成的通用步骤如下：

第一步，设所有发送或者接收到的数据为数组M，将数组M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1+value1+key2+value2…）拼接成字符串stringA。

第二步，在stringA最后拼接上应用private_key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

示例：

原始参数：

{
    "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": "测试商品",
    "version": "1.0.0"
}

私钥：

K0d8F434vUjVc88vxkDxmC0z8cj0UZ

第一步：按照参数名ASCII码从小到大排序

amount300.0000callbackurlhttp://www.baidu.com/callbackurl.htmlcashier2create_time1626376050default_currencycnymerchantid2network1notifyurlhttp://www.baidu.com/notifyurl.htmlorderidout2021071587481pay_code1pay_type1productname测试商品version1.0.0

第二步：拼接私钥

stringSignTemp="amount300.0000callbackurlhttp://www.baidu.com/callbackurl.htmlcashier2create_time1626376050default_currencycnymerchantid2network1notifyurlhttp://www.baidu.com/notifyurl.htmlorderidout2021071587481pay_code1pay_type1productname测试商品version1.0.0K0d8F434vUjVc88vxkDxmC0z8cj0UZ"

第三步：生成MD5并转大写

sign=MD5(stringSignTemp).toUpperCase()

Java代码示例：

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

public class WeePaySignUtil {
    private static final String CHARSET = "UTF-8";
    
    /**
     * 生成签名
     * @param params 请求参数
     * @param privateKey 商户私钥
     * @return 签名结果
     */
    public static String generateSign(Map params, String privateKey) {
        try {
            // 1. 过滤空值和sign参数
            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. 按照参数名ASCII码从小到大排序
            StringBuilder stringA = new StringBuilder();
            for (Map.Entry entry : filteredParams.entrySet()) {
                stringA.append(entry.getKey()).append(entry.getValue());
            }
            
            // 3. 拼接私钥
            String stringSignTemp = stringA.toString() + privateKey;
            
            // 4. MD5加密并转大写
            return md5(stringSignTemp).toUpperCase();
        } catch (Exception e) {
            throw new RuntimeException("生成签名失败", e);
        }
    }
    
    /**
     * MD5加密
     * @param text 待加密文本
     * @return 加密结果
     */
    private static String md5(String text) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] bytes = md.digest(text.getBytes(CHARSET));
        return bytesToHex(bytes);
    }
    
    /**
     * 字节数组转16进制字符串
     */
    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
    
    /**
     * 使用示例
     */
    public static void main(String[] args) {
        // 配置信息
        String merchantId = "1";
        String privateKey = "K0d8F434vUjVc88vxkDxmC0z8cj0UZ";
        
        // 构建请求参数
        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://您的域名/notify.php");
        params.put("amount", "10.0000");
        params.put("productname", "测试商品");
        
        // 生成签名
        String sign = generateSign(params, privateKey);
        params.put("sign", sign);
        
        // 打印请求参数
        System.out.println("请求参数：");
        for (Map.Entry entry : params.entrySet()) {
            System.out.println(entry.getKey() + " = " + entry.getValue());
        }
        
        // 发送HTTP请求示例
        try {
            String response = sendHttpRequest(params);
            System.out.println("响应结果：" + response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    /**
     * 发送HTTP请求示例
     */
    private static String sendHttpRequest(Map params) throws Exception {
        // 这里使用HttpClient发送请求，需要添加相关依赖
        // 实际项目中建议使用OkHttp或Apache HttpClient等HTTP客户端
        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));
        }
        
        // 这里仅作示例，实际项目中需要根据具体情况实现
        return "HTTP请求实现代码";
    }
}

9. 示例代码

9.1 PHP代码示例

/**
 * 生成签名
 * 
 * @param array $data 请求参数
 * @param string $privateKey 商户私钥
 * @return array 包含签名和签名字符串
 */
function makeSign($data, $privateKey)
{
    // 除去数组中的空值和签名参数
    $para_filter = array();
    foreach ($data as $key => $val) {
        if ($key == "sign" || $val === "" || $val === null) {
            continue;
        }
        $para_filter[$key] = $val;
    }

    // 按照键名字典序排序
    ksort($para_filter);
    reset($para_filter);

    // 拼接字符串
    $str_sign = "";
    foreach ($para_filter as $key => $val) {
        $str_sign .= $key . $val;
    }

    // 添加私钥
    $str_sign .= $privateKey;

    // MD5加密并转大写
    $sign = strtoupper(md5($str_sign));

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

9.2 下单请求示例

// 配置信息
$config = [
    'merchant_id' => 1,
    'private_key' => 'your_private_key',
    'notify_url'  => 'https://您的域名/notify.php',
    'gateway_url' => 'https://支付域名/getway.html',
];

// 组装下单参数
$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' => '测试商品',
];

// 生成签名
$sign_data = makeSign($params, $config['private_key']);
$params['sign'] = $sign_data['sign'];

// 发起HTTP请求
$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);

// 处理响应
$result = json_decode($response, true);
print_r($result);

9.3 异步通知处理示例

// 获取所有请求参数
$data = $_POST;

// 获取商户信息（实际应用中应该从数据库获取）
$private_key = 'your_private_key';

// 验证签名
$sign = $data['sign'];
unset($data['sign']);

// 签名验证
$sign_data = makeSign($data, $private_key);
if ($sign_data['sign'] === $sign) {
    // 验证成功，处理订单逻辑
    // ...
    
    // 返回成功标识
    echo 'success';
} else {
    // 签名验证失败
    echo 'fail';
}

9.4 余额查询示例

// 配置信息
$config = [
    'merchant_id' => 1,
    'private_key' => 'your_private_key',
    'balance_url' => 'https://支付域名/balance.html',
];

// 组装参数
$timestamp = time();

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

// 生成签名
$sign_data = makeSign($params, $config['private_key']);
$params['sign'] = $sign_data['sign'];

// 发起HTTP请求
$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);

// 处理响应
$result = json_decode($response, true);
if ($result['code'] == 1) {
    echo "余额查询成功：" . $result['data']['balance'] . " " . $result['data']['currency'] . "\n";
} else {
    echo "查询失败：" . $result['msg'] . "\n";
}

print_r($result);