第3章：商户号与配置
3.1 适用场景
- 新商户首次接入支付SDK，需完成商户号激活与绑定。
- 存量商户因密钥泄露或安全合规要求，需轮换（rotate）。
- 多环境（开发/测试/生产）部署时，需分别配置商户号与密钥。
3.2 前置条件
| 条件项 | 验证标准 |
|---|
| 已签约支付服务并获取商户注册邮箱 | 邮箱内收到“商户号开通通知” |
| 企业认证资料已通过审核 | 商户后台状态显示“已认证” |
| 具备管理员（Admin）角色权限 | 可访问“密钥管理”菜单项 |
| 系统环境已安装最新支付SDK | SDK版本号 >= 2.1.0 |
3.3 操作步骤
步骤1：获取商户号
- 登录商户管理后台（URL由支付机构提供，通常为
https://merchant.xxx.com）。
- 进入「账户中心」→「商户信息」页面。
- 复制显示为
mch_xxxxxxxxxxxx 格式的字符串，即为商户号（Merchant ID）。
- 通过安全通道（企业邮箱或加密IM）下发给应用开发负责人。
提示：商户号在支付机构内全局唯一，区分大小写，必须原样复制，不要手动输入。
步骤2：生成
- 在商户后台进入「安全设置」→「管理」。
- 点击「生成新密钥」。系统弹出密钥生成规则弹窗。
- 确认密钥类型为HMAC-SHA256，长度32字节，编码为十六进制字符串（64字符）。
- 点击「确认生成」，系统返回密钥明文（仅展示一次）。
- 立即复制密钥并存入受管密钥库（见步骤3）。
安全警告：密钥明文离开页面后，商户后台将不再以任何形式再次展示。丢失密钥只能重新生成，不可找回。
步骤3：密钥存储与安全规范
| 存储方式 | 安全等级 | 推荐场景 |
|---|
| 硬件安全模块（HSM） | 最高 | 生产环境、金融级合规 |
| 密钥管理服务（KMS） | 高 | 云原生部署、自动轮换 |
| 环境变量 + 加密配置文件 | 中 | 内部测试/开发环境 |
| 硬编码在源代码中 | 不允许 | — |
- 密钥必须使用AES-256-GCM加密后静态存储。
- 访问密钥的代码必须通过最小权限原则控制，仅支付模块可读取。
- 禁止在日志、监控、报错信息中输出密钥明文或密钥推导值。
- 密钥轮换周期：生产环境≤90天，测试环境≤180天。
步骤4：在SDK配置文件中注入参数
将商户号和密钥写入SDK初始化配置文件（YAML格式示例）：
# payment_sdk_config.yaml
merchant:
id: "mch_t8k3m1p9q2r7"
: "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
_encrypted: true
key_store: "kms://projects/payment/locations/global/keyRings/sdk/cryptoKeys/"
timeout_ms: 5000
retry_max: 3
关键：若配置文件中存储的是加密后的密钥，需在应用启动时通过密钥服务解密并加载到内存，不可在配置文件中保存明文。
3.4 输入输出物
| 角色 | 输入物 | 输出物 |
|---|
| 商户运营 | 商户注册资料、企业认证结果 | 商户号（MCH ID） |
| 安全管理员 | 密钥生成请求 | （密文信封） |
| 开发工程师 | 商户号、加密密钥、SDK配置文件模板 | 已注入参数的SDK配置文件 |
3.5 责任边界
- 商户运营：对商户号的正确性和唯一性负责，承担因商户号泄漏导致的资金风险。
- 安全管理员：负责密钥的生成、分发、轮换策略制定；不得将明文密钥直接传递给开发人员。
- 开发工程师：负责SDK配置文件的结构正确性和密钥解密逻辑安全性；对配置文件版本管理负责。
- QA测试员：验证配置在不同环境下的注入效果，确认密钥无法从运行时内存或日志中被非法读取。
3.6 记录材料
- 商户号签收确认单（含签字或邮件回执）。
- 密钥签发记录表：时间、操作人、密钥指纹（SHA-256摘要）、使用环境。
- 密钥轮换计划与执行记录。
- SDK配置文件的版本历史（Git提交记录）。
3.7 异常处理
| 异常场景 | 处理措施 |
|---|
| 商户号格式不正确 | 返回「商户号格式错误」提示，检查长度与前缀；联系运营重新获取。 |
| 密钥解密失败 | 检查KMS权限、加密算法匹配、Base64或Hex解码是否一致；重建密钥信封。 |
| 密钥已被吊销（403响应） | 立即停用旧密钥，触发紧急轮换流程；更新配置文件并重启服务。 |
| 重复生成密钥导致旧密钥失效 | 确认支付机构策略（部分机构会保留上一个有效密钥并行的过渡期）；协调降级窗口。 |
| SDK初始化报401 Unauthorized | 校验商户号与密钥是否匹配；确认密钥未过期；检查配置文件中是否有隐藏字符。 |
3.8 验收标准
- 功能验收：使用商户号+密钥发起一笔查询交易（如余额查询），返回200 OK且业务数据正确。
- 安全验收：
- 开发者无法从代码仓库或日志中找到明文密钥。
- 静态分析工具未检出密钥硬编码。
- 密钥存储路径权限仅为支付服务进程可读。
- 文档验收：商户号签收记录、密钥生成日志、配置文件版本号三者对齐可追溯。