异步通知商户接口文档

Asynchronous Merchant Notification API Documentation

基本信息
接口名称
异步通知商户
请求方式
POST
Content-Type
application/json
字符编码
UTF-8
接口说明
触发时机
订单状态变更时(支付成功/失败)
通知方式
POST application/json
重试机制
失败后会重试通知(最多3次)
请求参数(商户接收)
参数名 类型 必填 描述
merchantIdstring是商户ID
outTradeNostring是商户订单号
systemOrderNostring是平台系统订单号
amountstring是订单金额(单位:分)
statestring是订单状态:1-成功,2-失败,3-处理中
successTimestring是成功时间(格式:yyyy-MM-dd HH:mm:ss)
timestampstring是毫秒时间戳
nonceStrstring是随机字符串(16位)
attachstring否附加数据,下单时原样返回
signTypestring是签名类型:SM3withSM2
signstring是国密签名(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..."
}
签名规则(国密 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);
}
验签示例代码
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);
    }
}
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);
    }
}
<?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';
}
*/
商户响应要求
成功响应
返回字符串 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 扩展。