基本信息
接口名称
异步通知商户
请求方式
POST
Content-Type
application/json
字符编码
UTF-8
接口说明
触发时机
订单状态变更时(支付成功/失败)
通知方式
POST application/json
重试机制
失败后会重试通知(最多3次)
请求参数(商户接收)
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| merchantId | string | 是 | 商户ID |
| outTradeNo | string | 是 | 商户订单号 |
| systemOrderNo | string | 是 | 平台系统订单号 |
| amount | string | 是 | 订单金额(单位:分) |
| state | string | 是 | 订单状态:1-成功,2-失败,3-处理中 |
| successTime | string | 是 | 成功时间(格式:yyyy-MM-dd HH:mm:ss) |
| timestamp | string | 是 | 毫秒时间戳 |
| nonceStr | string | 是 | 随机字符串(16位) |
| attach | string | 否 | 附加数据,下单时原样返回 |
| signType | string | 是 | 签名类型:SM3withSM2 |
| sign | string | 是 | 国密签名(Base64编码) |
请求示例(JSON格式)
{
"merchantId": "10001",
"outTradeNo": "202405180001",
"systemOrderNo": "T202405180001234",
"amount": "100",
"state": "1",
"successTime": "2024-05-18 15:30:00",
"timestamp": "1716015000000",
"nonceStr": "abc123def456",
"attach": "测试订单",
"signType": "SM3withSM2",
"sign": "MEUCIQD..."
}
"merchantId": "10001",
"outTradeNo": "202405180001",
"systemOrderNo": "T202405180001234",
"amount": "100",
"state": "1",
"successTime": "2024-05-18 15:30:00",
"timestamp": "1716015000000",
"nonceStr": "abc123def456",
"attach": "测试订单",
"signType": "SM3withSM2",
"sign": "MEUCIQD..."
}
签名规则(国密 SM3withSM2)
1
参数排序
所有参数(排除
sign)按参数名 ASCII 码升序排序2
拼接字符串
将排序后的参数按
key=value 格式用 & 连接3
生成待签名原文
将拼接后的字符串转换为 UTF-8 字节数组
4
国密签名
使用 SM3withSM2 算法,传入用户ID(默认:1234567812345678)和私钥进行签名
5
Base64 编码
将签名结果进行 Base64 编码,得到最终的 sign 值
签名示例代码(C#)
/// <summary>
/// 国密 SM3withSM2 签名(ASN.1 格式)
/// </summary>
public static byte[] SignSm3WithSm2Asn1Rs(byte[] msg, byte[] userId, AsymmetricKeyParameter privateKey)
{
ISigner signer = SignerUtilities.GetSigner("SM3withSM2");
signer.Init(true, new ParametersWithID(privateKey, userId));
signer.BlockUpdate(msg, 0, msg.Length);
byte[] sig = signer.GenerateSignature();
return sig;
}
/// <summary>
/// 生成签名(完整流程)
/// </summary>
public static string GenerateSign(Dictionary<string, string> param, AsymmetricKeyParameter privateKey)
{
byte[] msg = GetSignSourceBytes(param);
byte[] userId = Encoding.UTF8.GetBytes("1234567812345678");
byte[] signature = SignSm3WithSm2Asn1Rs(msg, userId, privateKey);
return Convert.ToBase64String(signature);
}
/// 国密 SM3withSM2 签名(ASN.1 格式)
/// </summary>
public static byte[] SignSm3WithSm2Asn1Rs(byte[] msg, byte[] userId, AsymmetricKeyParameter privateKey)
{
ISigner signer = SignerUtilities.GetSigner("SM3withSM2");
signer.Init(true, new ParametersWithID(privateKey, userId));
signer.BlockUpdate(msg, 0, msg.Length);
byte[] sig = signer.GenerateSignature();
return sig;
}
/// <summary>
/// 生成签名(完整流程)
/// </summary>
public static string GenerateSign(Dictionary<string, string> param, AsymmetricKeyParameter privateKey)
{
byte[] msg = GetSignSourceBytes(param);
byte[] userId = Encoding.UTF8.GetBytes("1234567812345678");
byte[] signature = SignSm3WithSm2Asn1Rs(msg, userId, privateKey);
return Convert.ToBase64String(signature);
}
验签示例代码
using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Security;
using System.Text;
public class Sm2Verifier
{
/// <summary>
/// 国密 SM3withSM2 验签
/// </summary>
public static bool VerifySm3WithSm2Asn1Rs(byte[] msg, byte[] userId, byte[] signature, AsymmetricKeyParameter publicKey)
{
ISigner signer = SignerUtilities.GetSigner("SM3withSM2");
signer.Init(false, new ParametersWithID(publicKey, userId));
signer.BlockUpdate(msg, 0, msg.Length);
return signer.VerifySignature(signature);
}
/// <summary>
/// 获取待签名字节数组
/// </summary>
public static byte[] GetSignSourceBytes(Dictionary<string, string> param)
{
// 1. 过滤 sign 字段
var filtered = param.Where(x => x.Key != "sign");
// 2. ASCII 升序排序
var sorted = filtered.OrderBy(x => x.Key);
// 3. 拼接字符串
string signStr = string.Join("&", sorted.Select(x => $"{x.Key}={x.Value}"));
// 4. 转为 UTF-8 字节数组
return Encoding.UTF8.GetBytes(signStr);
}
/// <summary>
/// 完整验签流程
/// </summary>
public static bool VerifyNotify(Dictionary<string, string> param, AsymmetricKeyParameter publicKey)
{
if (!param.ContainsKey("sign")) return false;
byte[] signature = Convert.FromBase64String(param["sign"]);
byte[] msg = GetSignSourceBytes(param);
byte[] userId = Encoding.UTF8.GetBytes("1234567812345678");
return VerifySm3WithSm2Asn1Rs(msg, userId, signature, publicKey);
}
}
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Security;
using System.Text;
public class Sm2Verifier
{
/// <summary>
/// 国密 SM3withSM2 验签
/// </summary>
public static bool VerifySm3WithSm2Asn1Rs(byte[] msg, byte[] userId, byte[] signature, AsymmetricKeyParameter publicKey)
{
ISigner signer = SignerUtilities.GetSigner("SM3withSM2");
signer.Init(false, new ParametersWithID(publicKey, userId));
signer.BlockUpdate(msg, 0, msg.Length);
return signer.VerifySignature(signature);
}
/// <summary>
/// 获取待签名字节数组
/// </summary>
public static byte[] GetSignSourceBytes(Dictionary<string, string> param)
{
// 1. 过滤 sign 字段
var filtered = param.Where(x => x.Key != "sign");
// 2. ASCII 升序排序
var sorted = filtered.OrderBy(x => x.Key);
// 3. 拼接字符串
string signStr = string.Join("&", sorted.Select(x => $"{x.Key}={x.Value}"));
// 4. 转为 UTF-8 字节数组
return Encoding.UTF8.GetBytes(signStr);
}
/// <summary>
/// 完整验签流程
/// </summary>
public static bool VerifyNotify(Dictionary<string, string> param, AsymmetricKeyParameter publicKey)
{
if (!param.ContainsKey("sign")) return false;
byte[] signature = Convert.FromBase64String(param["sign"]);
byte[] msg = GetSignSourceBytes(param);
byte[] userId = Encoding.UTF8.GetBytes("1234567812345678");
return VerifySm3WithSm2Asn1Rs(msg, userId, signature, publicKey);
}
}
import org.bouncycastle.crypto.CipherParameters;
import org.bouncycastle.crypto.params.ParametersWithID;
import org.bouncycastle.crypto.signers.SM2Signer;
import org.bouncycastle.crypto.params.ECPublicKeyParameters;
import java.util.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
public class Sm2Verifier {
/**
* 国密 SM3withSM2 验签
*/
public static boolean verifySm3WithSm2(byte[] msg, byte[] userId, byte[] signature, ECPublicKeyParameters publicKey) throws Exception {
SM2Signer signer = new SM2Signer();
CipherParameters param = new ParametersWithID(publicKey, userId);
signer.init(false, param);
signer.update(msg, 0, msg.length);
return signer.verifySignature(signature);
}
/**
* 获取待签名字节数组
*/
public static byte[] getSignSourceBytes(Map<String, String> params) {
// 1. 过滤 sign 字段
Map<String, String> filtered = new TreeMap<>(params);
filtered.remove("sign");
// 2. 拼接字符串(TreeMap 已按 key 排序)
StringBuilder sb = new StringBuilder();
List<String> keys = new ArrayList<>(filtered.keySet());
Collections.sort(keys);
for (int i = 0; i < keys.size(); i++) {
String key = keys.get(i);
sb.append(key).append("=").append(filtered.get(key));
if (i < keys.size() - 1) {
sb.append("&");
}
}
// 3. 转为 UTF-8 字节数组
return sb.toString().getBytes(StandardCharsets.UTF_8);
}
/**
* 完整验签流程
*/
public static boolean verifyNotify(Map<String, String> params, ECPublicKeyParameters publicKey) throws Exception {
if (!params.containsKey("sign")) {
return false;
}
byte[] signature = Base64.getDecoder().decode(params.get("sign"));
byte[] msg = getSignSourceBytes(params);
byte[] userId = "1234567812345678".getBytes(StandardCharsets.UTF_8);
return verifySm3WithSm2(msg, userId, signature, publicKey);
}
}
import org.bouncycastle.crypto.params.ParametersWithID;
import org.bouncycastle.crypto.signers.SM2Signer;
import org.bouncycastle.crypto.params.ECPublicKeyParameters;
import java.util.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
public class Sm2Verifier {
/**
* 国密 SM3withSM2 验签
*/
public static boolean verifySm3WithSm2(byte[] msg, byte[] userId, byte[] signature, ECPublicKeyParameters publicKey) throws Exception {
SM2Signer signer = new SM2Signer();
CipherParameters param = new ParametersWithID(publicKey, userId);
signer.init(false, param);
signer.update(msg, 0, msg.length);
return signer.verifySignature(signature);
}
/**
* 获取待签名字节数组
*/
public static byte[] getSignSourceBytes(Map<String, String> params) {
// 1. 过滤 sign 字段
Map<String, String> filtered = new TreeMap<>(params);
filtered.remove("sign");
// 2. 拼接字符串(TreeMap 已按 key 排序)
StringBuilder sb = new StringBuilder();
List<String> keys = new ArrayList<>(filtered.keySet());
Collections.sort(keys);
for (int i = 0; i < keys.size(); i++) {
String key = keys.get(i);
sb.append(key).append("=").append(filtered.get(key));
if (i < keys.size() - 1) {
sb.append("&");
}
}
// 3. 转为 UTF-8 字节数组
return sb.toString().getBytes(StandardCharsets.UTF_8);
}
/**
* 完整验签流程
*/
public static boolean verifyNotify(Map<String, String> params, ECPublicKeyParameters publicKey) throws Exception {
if (!params.containsKey("sign")) {
return false;
}
byte[] signature = Base64.getDecoder().decode(params.get("sign"));
byte[] msg = getSignSourceBytes(params);
byte[] userId = "1234567812345678".getBytes(StandardCharsets.UTF_8);
return verifySm3WithSm2(msg, userId, signature, publicKey);
}
}
<?php
/**
* 国密 SM3withSM2 验签(需要安装 gmssl 扩展)
* 安装命令:pecl install gmssl
*/
class Sm2Verifier {
/**
* 获取待签名字符串
* @param array $params 通知参数
* @return string 待签名字符串
*/
public static function getSignSourceString(array $params) {
// 1. 过滤 sign 字段
unset($params['sign']);
// 2. ASCII 升序排序
ksort($params, SORT_STRING);
// 3. 拼接字符串
array $pairs = [];
foreach ($params as $key => $value) {
$pairs[] = $key . '=' . $value;
}
return implode('&', $pairs);
}
/**
* 国密 SM3withSM2 验签(使用 gmssl 扩展)
* @param string $sign 签名值(Base64)
* @param string $data 待签名数据
* @param string $publicKey 公钥(PEM格式)
* @param string $userId 用户ID(默认:1234567812345678)
* @return bool
*/
public static function verifySm3WithSm2($sign, $data, $publicKey, $userId = '1234567812345678') {
try {
// 使用 gmssl 扩展验签
$result = gmssl_sm2_verify(
$sign,
$data,
$publicKey,
$userId
);
return $result === true;
} catch (Exception $e) {
return false;
}
}
/**
* 完整验签流程
* @param array $params 通知参数
* @param string $publicKey 公钥(PEM格式)
* @return bool
*/
public static function verifyNotify(array $params, $publicKey) {
// 1. 检查签名是否存在
if (!isset($params['sign'])) {
return false;
}
// 2. 获取签名值
$sign = $params['sign'];
// 3. 获取待签名源字符串
$sourceStr = self::getSignSourceString($params);
// 4. 验签
return self::verifySm3WithSm2($sign, $sourceStr, $publicKey);
}
}
// 使用示例
/*
$notifyData = json_decode(file_get_contents('php://input'), true);
$publicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----';
if (Sm2Verifier::verifyNotify($notifyData, $publicKey)) {
echo 'ok';
} else {
echo 'fail';
}
*/
/**
* 国密 SM3withSM2 验签(需要安装 gmssl 扩展)
* 安装命令:pecl install gmssl
*/
class Sm2Verifier {
/**
* 获取待签名字符串
* @param array $params 通知参数
* @return string 待签名字符串
*/
public static function getSignSourceString(array $params) {
// 1. 过滤 sign 字段
unset($params['sign']);
// 2. ASCII 升序排序
ksort($params, SORT_STRING);
// 3. 拼接字符串
array $pairs = [];
foreach ($params as $key => $value) {
$pairs[] = $key . '=' . $value;
}
return implode('&', $pairs);
}
/**
* 国密 SM3withSM2 验签(使用 gmssl 扩展)
* @param string $sign 签名值(Base64)
* @param string $data 待签名数据
* @param string $publicKey 公钥(PEM格式)
* @param string $userId 用户ID(默认:1234567812345678)
* @return bool
*/
public static function verifySm3WithSm2($sign, $data, $publicKey, $userId = '1234567812345678') {
try {
// 使用 gmssl 扩展验签
$result = gmssl_sm2_verify(
$sign,
$data,
$publicKey,
$userId
);
return $result === true;
} catch (Exception $e) {
return false;
}
}
/**
* 完整验签流程
* @param array $params 通知参数
* @param string $publicKey 公钥(PEM格式)
* @return bool
*/
public static function verifyNotify(array $params, $publicKey) {
// 1. 检查签名是否存在
if (!isset($params['sign'])) {
return false;
}
// 2. 获取签名值
$sign = $params['sign'];
// 3. 获取待签名源字符串
$sourceStr = self::getSignSourceString($params);
// 4. 验签
return self::verifySm3WithSm2($sign, $sourceStr, $publicKey);
}
}
// 使用示例
/*
$notifyData = json_decode(file_get_contents('php://input'), true);
$publicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----';
if (Sm2Verifier::verifyNotify($notifyData, $publicKey)) {
echo 'ok';
} else {
echo 'fail';
}
*/
商户响应要求
成功响应
返回字符串
ok失败响应
返回其他任何内容(如
fail)成功响应示例
ok
失败响应示例
fail
订单状态说明
| 状态码 | 描述 | 说明 |
|---|---|---|
| 1 | 成功 | 订单支付成功,金额已到账 |
| 2 | 失败 | 订单支付失败 |
| 3 | 处理中 | 订单处理中,暂未确认结果 |
注意事项
⚠️ 重要提醒
- 商户接收到通知后,需返回字符串
ok(不包含引号)表示接收成功 - 若商户未返回
ok或返回其他内容,系统会认为通知失败并重试 - 通知可能重复发送(网络抖动、超时等原因),商户需做好幂等处理
- 建议商户收到通知后先验证签名,确保通知来源合法
- 金额单位为分,避免浮点数精度问题
- 成功时间格式为:
yyyy-MM-dd HH:mm:ss - 重试策略:失败后间隔 30s、1min、2min 进行重试,最多3次
- 签名类型为
SM3withSM2,使用国密算法,私钥签名、公钥验签 - 用户ID(userId)为固定值,由平台分配,默认为:1234567812345678
- 签名结果为 ASN.1 格式 DER 编码,再进行 Base64 编码传输
- PHP 环境需要安装 gmssl 扩展:
pecl install gmssl - Java 环境需要引入 BouncyCastle 依赖
常见问题
Q1:为什么收到重复通知?
A:由于网络超时或商户响应慢,系统会重发通知。商户需要根据 outTradeNo 做幂等处理,避免重复入账。
Q2:签名验证失败怎么办?
A:检查公钥是否正确,确认所有字段(除sign外)都参与了签名,参数名大小写是否一致,用户ID是否匹配。
Q3:通知超时时间是多久?
A:系统默认等待响应超时时间为10秒。
Q4:SM3withSM2 签名需要什么环境?
A:C# 需要 BouncyCastle,Java 需要 BouncyCastle,PHP 需要 gmssl 扩展。