1. 概述
HaiPay 全新推出了密钥配置面板,旨在为商户提供更便捷、更安全的密钥管理体验。新面板兼容原有配置逻辑,同时增加了以下核心功能:- 一键生成密钥对 — 商户可直接在平台侧生成 RSA 2048 公私钥对,无需安装额外工具
- 业务ID灵活映射 — 支持为不同业务ID(appId)配置不同公钥,也支持一键配置“所有”业务ID
- 批量密钥替换 — 通过穿梭框直观管理业务ID与密钥的映射关系
- 多维度密钥查看 — 商户公钥、Haipay公钥、加密字段分标签页管理
签名使用 SHA256WithRSA 签名算法,密钥长度为 2048位。商户私钥用于请求报文加签,商户公钥上传至 HaiPay 用于验签;HaiPay 公钥用于验证平台返回报文的签名。
公私钥的作用
在 HaiPay 的通信架构中,公私钥承担着请求签名和响应验签的核心安全保障:图1:商户与平台之间的公私钥签名/验签流程
2. 前置准备
在使用密钥配置面板之前,请确保您已完成以下准备工作:1
获取商户平台账号
合作确认后,HaiPay 将根据《商户接入申请表》中填写的“管理员账号信息”创建商户管理平台账号。请注意查收 HaiPay 下发的激活邮件,按指引激活账号。首次登录需更改密码。
2
登录商户管理平台
使用激活后的管理员账号登录 HaiPay 商户管理自助平台。
3
进入开发配置
在商户端主菜单中,找到新增的「开发配置」主菜单,点击进入密钥配置面板。
3. 面板总览
进入「开发配置」-「密钥配置」后,您将看到如下面板。面板顶部有三个标签页,分别管理不同类型的密钥:
图2:密钥配置面板主页面 — 您的公钥标签页
新商户的平台公钥和加密字段默认配置到“所有”业务ID。若以往的老商户有多个不同公钥的,将展示为多行。
密钥展示与复制
面板中的密钥内容较长,为了美观会进行中间省略显示。点击密钥字段即可复制完整信息到剪贴板。
图3:Haipay公钥标签页 — 切换至平台公钥查看和搜索
4. 关联业务ID筛选
面板顶部提供关联业务ID筛选项,支持单选下拉搜索。您可以搜索该商户关联的所有 appId 进行筛选查看。
图4:关联业务ID搜索筛选 — 支持下拉搜索特定 appId
关于“所有”业务ID
- 如果该用户的所有 appId 都使用同一个密钥,则 appId 栏会显示为“所有”
- 用户无论搜索什么 appId,都会展示选项为“所有”的行
- 当 appId 为“所有”时,后续新增业务也会为其自动配置该公钥
5. 新增/更换密钥
点击面板右上角的「新增/更换密钥」按钮,将弹出密钥配置弹窗。在该弹窗中,您可以选择密钥生成方式和业务ID映射范围。
图5:新增/更换密钥弹窗 — 选择生成方式和映射范围
1
选择密钥替换方式
提供两种方式(详见下一章):
- 推荐 由 HaiPay 一键生成所有公私钥 — 平台侧生成 RSA 2048 密钥对,私钥复制至剪贴板,平台仅保存公钥
- 使用您自行创建的公私钥 — 手动录入已生成的公钥
2
选择映射业务ID范围
提供两个选项:
- 全部 — 该密钥将应用于所有业务ID
- 特定业务ID — 打开穿梭框,为特定业务ID配置该公钥
3
生成或录入密钥
根据所选方式,点击“生成”按钮生成密钥对,或在文本框中录入您的公钥。
4
确认替换
点击底部按钮提交,系统将进行二次确认弹窗。确认后新密钥立即生效,旧密钥失效。
6. 密钥生成方式
方式一:由 HaiPay 平台一键生成 推荐
这是最简便的方式。HaiPay 平台将在您点击“生成”后,直接为您生成一对 RSA 2048 公私钥。
图6:选择“由 HaiPay 一键生成”后的密钥配置界面
1
选择生成方式
在弹窗中选择“由 HaiPay 一键生成所有公私钥”(默认选中,标注“推荐”)。
2
点击“生成”按钮
系统将在平台侧生成一对 RSA 2048 公私钥。公钥显示在“您的公钥”字段,私钥显示在“您的私钥”字段。
3
点击“新增/替换并复制私钥”
提交替换后,私钥将自动复制到您的剪贴板。请立即保存到安全位置。
4
二次确认
系统弹出二次确认弹窗,确认后新密钥立即生效。
- 私钥不会保存在平台,仅本次复制到剪贴板。请务必立即保存,关闭页面后无法再次获取。
- 替换密钥后,原密钥将立即失效,使用旧密钥签名的请求将无法通过验签。
- 请在业务低峰期操作,确保新密钥已配置到您的系统中再执行替换。
方式二:使用自行创建的公私钥
如果您已有密钥对或希望自行管理密钥生成过程,可以选择此方式。此时会弹出文本框,要求您录入公钥。
图7:选择“使用自行创建的公私钥” — 需手动录入公钥
OpenSSL 生成
使用 openssl 命令行工具生成 RSA 2048 位密钥对,需安装 openssl,密钥位数 2048 位,可参考网上示例。
在线生成工具
使用 HaiPay 提供的在线 RSA 密钥生成工具(纯 JS 实现,不会与服务器交互,不会泄露商户密钥信息)。
代码生成
使用 Java、PHP 等 SDK 代码生成 RSA 2048 位密钥对并转为 PEM 格式。
与方式一的区别选择自行创建方式时,替换仍需二次弹窗确认,但不会将私钥复制至剪贴板(因为没有平台生成私钥的操作)。私钥由您自行保管。
7. 业务ID映射
在新增/更换密钥弹窗中,“映射业务ID”提供两个选项:“全部”和“特定业务ID”。不同的选择决定了密钥与业务ID的关联方式。7.1 不更改映射ID(选择“全部”)
当选择“全部”时,新的公钥将应用到该商户下的所有业务ID。后续新增的业务也会自动配置上该公钥。
图8:映射业务ID选择“全部” — 公钥应用于所有业务ID
7.2 更改密钥映射(选择“特定业务ID”)
当选择“特定业务ID”时,将打开一个穿梭框(Transfer Box),用于选择将该公钥映射到哪些业务ID。
图9:穿梭框界面 — 左侧为未映射/全部业务ID,右侧为已选定业务ID

图10:穿梭框详细视图 — 含搜索、分页、穿梭按钮
8. 密钥覆盖提醒
当您在新增/更换密钥弹窗中提交配置时,如果新的映射范围会覆盖已有公钥的关联关系,系统会自动弹出密钥覆盖提醒,告知您哪些业务ID将受到影响。这是为了防止误操作导致线上签名验证失败。什么时候会触发覆盖提醒?当您的新密钥映射的业务ID中,已经有其他公钥在关联时,就会触发覆盖提醒。系统需要您确认:是否用新公钥替换这些业务ID原有公钥的关联关系。
图11:密钥覆盖提醒完整流程 — 从提交到二次确认到生效
8.1 部分映射覆盖
当您的修改仅影响部分已映射的业务ID时,系统会弹出“密钥覆盖提醒”弹窗,明确列出受影响的具体业务ID。 弹窗内容如下:- 标题:密钥覆盖提醒
- 警告文案:“此次修改将覆盖以下业务id关联的密钥,旧密钥将立即失效。是否继续?”
- 受影响的业务ID:系统逐行列出所有受影响的 appId(如 1122、3344、5566 等)
- 操作按钮:「取消」(返回弹窗页面) / 「确认替换」(进入二次确认)

图12:密钥覆盖提醒(部分映射覆盖) — 列出受影响的具体业务ID
8.2 全部映射覆盖
当您将一个原本仅映射部分业务ID的公钥,更改为映射“所有”业务ID时,该操作会覆盖所有业务ID原有的密钥关联。此时弹窗会警告所有业务ID都将受影响。 弹窗内容如下:- 标题:密钥覆盖提醒
- 警告文案:“此次修改将覆盖所有业务id关联的密钥,旧密钥将立即失效。是否继续?”
- 操作按钮:「取消」(返回弹窗页面) / 「确认替换」(进入二次确认)

图13:密钥覆盖提醒(全部映射覆盖) — 警告所有业务ID都将受影响
“全部映射覆盖”意味着商户名下所有业务ID的密钥将一次性全部替换。这是影响范围最大的操作,请务必确认:
- 新私钥已安全保存并配置到您的所有业务系统中
- 选择在业务低峰期执行此操作
- 已通知相关开发/运维团队做好配合准备
8.3 二次确认
无论您在覆盖提醒弹窗中点击的是“部分映射覆盖”还是“全部映射覆盖”的「确认替换」按钮,系统都会再弹出二次确认弹窗,作为最后一道安全防线。 二次确认弹窗内容如下:- 标题:确定替换新密钥?
- 警告文案:“替换密钥是高危操作,原密钥失效后您将不能使用,请务必谨慎操作。”
- 操作按钮:「取消」(返回覆盖提醒弹窗) / 「确认替换」(执行替换,密钥立即生效)

图14:二次确认弹窗 — 提醒替换密钥是高危操作
8.4 确认后的执行逻辑
在二次确认点击「确认替换」后,系统将立即执行密钥替换,具体逻辑如下:关于“返回/取消”按钮无论在第一层覆盖提醒弹窗还是第二层二次确认弹窗中,点击「取消」或「返回」按钮都会回到密钥配置弹窗页面,不会直接关闭弹窗。您可以继续修改配置或手动关闭弹窗。
9. 单独更换密钥或修改映射
除了使用顶部“新增/更换密钥”按钮进行批量操作外,您还可以针对特定的公钥进行单独操作。在数据表的“操作”列中,每行提供两个操作链接:
图15:操作列 — “替换密钥”和“更换业务id映射”
单独操作的逻辑与使用顶部按钮一致,区别在于:
- 替换密钥时,业务ID映射是固定的,仅更换密钥内容
- 更换映射时,公钥是固定的,可不修改,仅调整映射范围

图16:更换业务ID映射 — 穿梭框中选择新的映射范围
10. 安全最佳实践
- 私钥仅显示一次 — 通过平台一键生成密钥时,私钥仅复制到剪贴板,平台不保存。关闭页面后无法再次获取。
- merchantSecretKey 和商户 RSA 私钥均属于敏感信息,不得写入前端代码、客户端应用、日志或公开仓库。
- 立即保存私钥 — 生成密钥后请立即将私钥保存到安全的密钥管理系统或加密存储中。
- 密钥泄露应急 — 若不慎泄露密钥,请及时通过平台更新密钥。
签名安全规则
签名生成规则:
将所有字段值不为
null 且不为 "" 的参数,排除 sign、sign_type 字段后,按字段名 ASCII 升序排序,取 key 和 value 按 k1=v1&k2=v2&... 的格式进行拼接,并在结尾追加 &key=merchantSecretKey(商户密钥)作为待签名串。商户使用 RSA 私钥按 SHA256WithRSA 算法对待签名串进行签名。
11. 密钥格式要求
上传公钥至 HaiPay 平台时,请注意以下格式要求:12. 常见问题
Q: 选择「HaiPay一键生成」后,私钥保存在哪里?
Q: 选择「HaiPay一键生成」后,私钥保存在哪里?
私钥不会保存在 HaiPay 平台。生成后,私钥会自动复制到您的剪贴板,您需要立即保存到安全的位置。平台仅保存公钥用于验签。
关闭弹窗后私钥将无法再次获取,请务必在操作时立即保存。
Q: 替换密钥后旧密钥还能用吗?
Q: 替换密钥后旧密钥还能用吗?
不能。替换密钥后,原密钥将立即失效。使用旧私钥签名的请求将无法通过 HaiPay 的验签。请在业务低峰期操作,并确保新私钥已配置到您的系统中后再执行替换。
Q: 业务ID显示为「所有」是什么意思?
Q: 业务ID显示为「所有」是什么意思?
当 appId 栏显示为“所有”时,表示该密钥应用于商户名下的所有业务ID。后续新增的业务也会自动配置上该公钥。如果您需要为不同业务ID配置不同密钥,请使用“特定业务ID”映射功能。
Q: 穿梭框中「显示/隐藏已映射」按钮的作用是什么?
Q: 穿梭框中「显示/隐藏已映射」按钮的作用是什么?
穿梭框左侧面板默认仅展示未映射的业务ID。点击“显示/隐藏已映射”按钮可以切换显示已映射到其他密钥的业务ID,方便您在不同密钥之间调整映射关系。顶部名称也会相应切换为“映射业务ID”或“全部业务ID”。
Q: 为什么更换密钥时会有多次弹窗确认?
Q: 为什么更换密钥时会有多次弹窗确认?
密钥替换是高危操作,系统设计了多层确认机制以防止误操作:
- 第一层:密钥覆盖提醒 — 告知哪些业务ID会受影响
- 第二层:二次确认弹窗 — 最终确认是否执行替换
Q: 如何为不同业务ID配置不同公钥?
Q: 如何为不同业务ID配置不同公钥?
在“新增/更换密钥”弹窗中,映射业务ID选择“特定业务ID”,打开穿梭框。在穿梭框中将需要映射的业务ID从左侧移至右侧,确认后该公钥将仅应用于右侧选中的业务ID。您也可以在数据表操作列点击“更换业务id映射”来调整已有公钥的映射范围。
Q: 验签失败怎么办?
Q: 验签失败怎么办?
请检查以下几点:
- 确认使用的私钥与上传至平台的公钥是同一对密钥
- 确认签名串是否按 ASCII 升序排序拼接
- 确认排除了
sign和sign_type字段 - 确认字段值为
null或""的参数未参与签名 - 确认待签名串使用 UTF-8 编码
- 确认未使用宽松空值判断(如 PHP
empty()或 JS!value) - 验证返回报文时,确认将所有新增有效字段纳入验签
相关主题
集成步骤指南
从账号创建到首次 API 调用的完整接入流程。
联调环境与请求地址
API 联调环境说明与请求地址一览。
接口说明与公共规则
HaiPay 接口说明与公共请求/返回规则。
RSA 在线密钥生成工具
纯 JS 实现的 RSA 密钥对在线生成工具,不会与服务器交互。

