商户身份认证参数配置

商户身份认证是支付 SDK 接入的第一道安全防线。系统通过 app_id、商户号、证书路径 和 密钥 四个参数完成双向身份校验，确保请求来自合法商户且数据未被篡改。任何参数取值错误或配置遗漏都会导致签名验证失败、请求被拒。本章将逐项解析各参数的含义、取值规则、测试验证方法及常见错误调参策略。

参数含义与取值规则总览

参数名称	含义	取值规则	示例值	测试注意事项
app_id	支付平台分配给商户的应用标识，唯一绑定一个应用或小程序	由平台自动生成；长度固定（通常16～32位字母数字组合）；不可自定义；区分大小写	wx20250101abc123	不能带入空格或特殊符号；测试环境与生产环境 app_id 不同
商户号 (mch_id)	商户在支付平台的唯一商户编号，用于结算与清算	平台审核通过后下发；8～15位纯数字；一户一码	14886688	不能与其他商户号混淆；部分平台测试商户号后三位为 001
证书路径	商户证书文件（.p12/.pem）的本地或内存/相对路径	文件后缀必须符合平台要求；路径中不要包含中文或空格；建议放在资源目录并硬编码	/etc/certs/mch_14886688.p12	运行环境必须拥有读取权限；测试证书与生产证书不可混用
密钥 (/签名密钥)	用于计算请求签名和验证响应的对称密钥	由平台生成或商户自行设置，通常32位Hex字符串或随机字符串；必须严格保密	2f7a8b1c3d4e5f6g7h8i9j0k1l2m3n4o	不能明文硬编码；测试密钥仅在沙箱环境有效

参数详解与测试配置

app_id

含义：app_id 是商户应用的全局唯一标识。支付平台通过 app_id 区分不同商户及其下不同应用（如 iOS App、微信小程序、H5 网页）。
获取方式：在商户后台创建应用后自动生成，通常位于“应用管理” → “应用详情”页面。
取值规则：
· 固定长度，常见16位、24位、32位。
· 仅包含字母、数字，部分平台允许下划线。
· 区分大小写（例如 wx1092AB 与 wx1092ab 视为不同应用）。
测试条件：
· 准备测试环境 app_id（通常前缀或后缀带 _test 或 sandbox）。
· 使用参数测试工具（如 Postman + SDK 签名库）发送一笔最低金额请求，若返回 invalid_appid 则说明 app_id 错误。

商户号 (mch_id)

含义：商户号是结算主体标识，与 app_id 属于多对一或一对一关系（取决于平台设计）。所有资金操作（退款、转账、对账）都基于商户号。
取值规则：纯数字，位数为8～15位，无校验位。
测试方式：
· 在商户后台“账户中心” → “商户信息”中复制商户号。
· 使用签名校验工具，传入错误的商户号，应收到 mch_not_exist 错误码。
· 若平台支持多商户号，需确认当前 SDK 配置的商户号是否具有该 app_id 的权限。

证书路径

含义：商户证书用于加解密和双向 TLS 认证。支付平台通过验证证书指纹确认商户身份。
取值规则：
· 路径格式：路径（推荐）或相对于 classpath 的相对路径。
· 文件扩展名：.p12（PKCS#12 格式，含私钥）、.pem（Base64 编码证书 + 私钥）。
· 若使用内存加载，路径参数可设置为流对象标识符（如 classpath:certs/mch.p12）。
测试注意：
· 运行环境（特别是 Docker、K8s 容器）必须有文件访问权限。
· 测试证书与生产证书内容不同，切勿混用。
· 证书文件不可放在公开仓库；建议使用环境变量传递路径。

密钥 ()

含义：对称密钥用于 HMAC-SHA256 或 MD5 签名。商户和支付平台各持一份，签名时使用该密钥对请求参数排序后计算摘要。
取值规则：
· 长度：32位 Hex 字符串（128 bit）或平台指定的固定长度。
· 字符集：[0-9a-zA-Z] 或 [0-9a-f]。
· 区分大小写。
安全要求：
· 禁止将密钥写在源码、配置文件或日志中。
· 建议使用密钥管理服务（KMS）或环境变量注入。
· 定期轮换密钥（通常每90天）。

配置验证流程

以下步骤可在沙箱环境快速验证参数是否正确：

1. 在商户平台生成测试 app_id 和测试商户号，下载测试证书，获取测试密钥。
2. 在 SDK 配置文件中填入四参数，并设置沙箱网关 URL。
3. 调用 “统一下单” 接口，参数使用 0.01 元并加上 attach 标记。
4. 观察返回结果：若返回 sign_failure，先排查密钥或证书路径；若返回 appid_mchid_not_match，则检查 app_id 与商户号的绑定关系。
5. 使用平台提供的签名校验工具，输入原始参数和密钥，比对 SDK 生成的签名是否一致。

常见错误与数据判断

错误码	原因	调参动作
invalid_appid	app_id 不存在或未绑定商户号	检查 app_id 是否输入错误；确认商户号是否有该应用的授权
mch_not_exist	商户号无效	核对商户号位数与数字；检查是否使用了生产环境的商户号在沙箱测试
cert_not_found	证书路径不存在或权限不足	检查路径符号链接、文件权限；确认容器内 /etc 或 /tmp 挂载
sign_failure	签名密钥错误或签名参数顺序不一致	使用签名校验工具对比 SDK 签名与平台网关签名；更换测试密钥
key_expired	密钥已过期	在商户后台重新生成密钥并更新配置

验收阈值

• 使用测试环境发起一笔1分（0.01元）支付请求，HTTP 状态码 200，JSON 返回 result_code=SUCCESS。
• 签名校验工具输出签名与 SDK 计算签名完全一致（Hex 字符串完全匹配）。
• 证书路径校验：在代码中加载证书对象，不抛出 FileNotFoundException 或 CertificateException。
• 密钥轮换测试：更新商户平台密钥后，SDK 配置同步更新，新的请求签名通过；使用旧密钥的请求应返回 sign_failure。

商户身份认证参数配置流程

SDK 配置示例（JSON 格式）

{
  "app_id": "wx20250101abc123",
  "mch_id": "14886688",
  "cert_path": "/etc/certs/mch_14886688.p12",
  "cert_password": "123456",          // 注意：生产环境不得明文
  "": "2f7a8b1c3d4e5f6g7h8i9j0k1l2m3n4o",
  "gateway_url": "https://sandbox.pay.com/gateway",
  "sign_type": "HMAC-SHA256"
}

上述配置填入 SDK 后，配合本地签名校验工具，依次校验 app_id、mch_id、cert_path、 四项值，直至工具输出与 SDK 生成的签名一致，即可确认参数配置正确。