统一下单接口文档

Unified Order API Documentation

基本信息
接口名称
统一下单
请求方式
POST
Content-Type
application/json
字符编码
UTF-8
请求地址
POST /api/transactions/unified-order
请求参数
参数名 类型 必填 描述
outTradeNostring是商户订单号
merchantNostring是商户号
productCodestring是产品编码
totalFeeint是订单金额,单位:分,必须大于0
signstring是签名
signTypestring是签名类型,默认:md5
timestampstring是毫秒时间戳
tradeTypeint否交易类型:1-代收,2-代付,默认:1
notifyUrlstring是异步通知地址
clientIpstring否终端IP
nonceStrstring否随机字符串(建议使用UUID)
attachstring否附加数据,回调时原样返回
请求示例
{
    "outTradeNo": "202405180001",
    "merchantNo": "M10001",
    "productCode": "ALIPAY_WAP",
    "totalFee": 100,
    "sign": "abc123def456...",
    "signType": "md5",
    "timestamp": "1716001234567",
    "tradeType": 1,
    "notifyUrl": "https://merchant.com/notify",
    "clientIp": "192.168.1.100",
    "nonceStr": "abc123xyz",
    "attach": "附加信息"
}
签名规则
1
参数排序
所有参数(排除 sign)按参数名 ASCII 码升序排序
2
拼接字符串
将排序后的参数按 key=value 格式用 & 连接
3
拼接密钥
末尾拼接 &key=商户密钥
4
MD5 加密
计算 MD5(32位小写)
签名示例代码(C#)
public static string GenerateSign(Dictionary<string, string> dict, string merchantKey)
{
    dict.Remove("sign");
    var sortedDict = dict.OrderBy(x => x.Key);
    var signStr = string.Join("&", sortedDict.Select(x => $"{x.Key}={x.Value}"));
    signStr = $"{signStr}&key={merchantKey}";

    using var md5 = MD5.Create();
    var bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(signStr));
    return BitConverter.ToString(bytes).Replace("-", "").ToLower();
}
响应参数
参数名类型描述
codestring响应码:200-成功,400-失败
messagestring响应信息
dataobject响应数据
data 对象
参数名类型描述
outTradeNostring商户订单号
transactionIdstring平台订单号
payInfostring支付信息(如支付链接)
totalFeeint订单金额(分)
statusint订单状态:0-处理中,1-成功,2-失败
响应示例
成功响应
{
    "code": "SUCCESS",
    "message": "下单成功",
    "data": {
        "outTradeNo": "202405180001",
        "transactionId": "T202405180001234",
        "payInfo": "https://pay.platform.com/pay/T202405180001234",
        "totalFee": 100,
        "status": 0
    }
}
失败响应
{
    "code": "400",
    "message": "签名错误",
    "data": null
}
状态码(Code)
错误码描述
200成功
400失败
其他失败
注意事项
  • 时间戳使用毫秒级时间戳,平台会验证时间戳有效期(5分钟内)
  • 商户订单号需保证唯一性
  • 金额单位为分,避免浮点数精度问题
  • 所有字段(除sign外)都必须参与签名