基本信息
接口名称
统一下单
请求方式
POST
Content-Type
application/json
字符编码
UTF-8
请求地址
POST /api/transactions/unified-order
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| outTradeNo | string | 是 | 商户订单号 |
| merchantNo | string | 是 | 商户号 |
| productCode | string | 是 | 产品编码 |
| totalFee | int | 是 | 订单金额,单位:分,必须大于0 |
| sign | string | 是 | 签名 |
| signType | string | 是 | 签名类型,默认:md5 |
| timestamp | string | 是 | 毫秒时间戳 |
| tradeType | int | 否 | 交易类型:1-代收,2-代付,默认:1 |
| notifyUrl | string | 是 | 异步通知地址 |
| clientIp | string | 否 | 终端IP |
| nonceStr | string | 否 | 随机字符串(建议使用UUID) |
| attach | string | 否 | 附加数据,回调时原样返回 |
请求示例
{
"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": "附加信息"
}
"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();
}
{
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();
}
响应参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | string | 响应码:200-成功,400-失败 |
| message | string | 响应信息 |
| data | object | 响应数据 |
data 对象
| 参数名 | 类型 | 描述 |
|---|---|---|
| outTradeNo | string | 商户订单号 |
| transactionId | string | 平台订单号 |
| payInfo | string | 支付信息(如支付链接) |
| totalFee | int | 订单金额(分) |
| status | int | 订单状态:0-处理中,1-成功,2-失败 |
响应示例
成功响应
{
"code": "SUCCESS",
"message": "下单成功",
"data": {
"outTradeNo": "202405180001",
"transactionId": "T202405180001234",
"payInfo": "https://pay.platform.com/pay/T202405180001234",
"totalFee": 100,
"status": 0
}
}
"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": "400",
"message": "签名错误",
"data": null
}
状态码(Code)
| 错误码 | 描述 |
|---|---|
| 200 | 成功 |
| 400 | 失败 |
| 其他 | 失败 |
注意事项
- 时间戳使用毫秒级时间戳,平台会验证时间戳有效期(5分钟内)
- 商户订单号需保证唯一性
- 金额单位为分,避免浮点数精度问题
- 所有字段(除sign外)都必须参与签名