Skip to main content

1. 概述

HaiPay 全新推出了密钥配置面板,旨在为商户提供更便捷、更安全的密钥管理体验。新面板兼容原有配置逻辑,同时增加了以下核心功能:
  • 一键生成密钥对 — 商户可直接在平台侧生成 RSA 2048 公私钥对,无需安装额外工具
  • 业务ID灵活映射 — 支持为不同业务ID(appId)配置不同公钥,也支持一键配置“所有”业务ID
  • 批量密钥替换 — 通过穿梭框直观管理业务ID与密钥的映射关系
  • 多维度密钥查看 — 商户公钥、Haipay公钥、加密字段分标签页管理
签名使用 SHA256WithRSA 签名算法,密钥长度为 2048位。商户私钥用于请求报文加签,商户公钥上传至 HaiPay 用于验签;HaiPay 公钥用于验证平台返回报文的签名。
如果您是首次接入 HaiPay,建议先阅读 集成步骤指南 了解完整接入流程。

公私钥的作用

在 HaiPay 的通信架构中,公私钥承担着请求签名和响应验签的核心安全保障:
图1:商户与平台之间的公私钥签名/验签流程

2. 前置准备

在使用密钥配置面板之前,请确保您已完成以下准备工作:
1

获取商户平台账号

合作确认后,HaiPay 将根据《商户接入申请表》中填写的“管理员账号信息”创建商户管理平台账号。请注意查收 HaiPay 下发的激活邮件,按指引激活账号。首次登录需更改密码。
2

登录商户管理平台

使用激活后的管理员账号登录 HaiPay 商户管理自助平台。
3

进入开发配置

在商户端主菜单中,找到新增的「开发配置」主菜单,点击进入密钥配置面板。
商户 appId 和密钥是配套使用的,区分币种、区分测试环境与正式环境。请确保在正确的环境下配置密钥。

3. 面板总览

进入「开发配置」-「密钥配置」后,您将看到如下面板。面板顶部有三个标签页,分别管理不同类型的密钥:
密钥配置面板主页面
图2:密钥配置面板主页面 — 您的公钥标签页
新商户的平台公钥和加密字段默认配置到“所有”业务ID。若以往的老商户有多个不同公钥的,将展示为多行。

密钥展示与复制

面板中的密钥内容较长,为了美观会进行中间省略显示。点击密钥字段即可复制完整信息到剪贴板。
Haipay公钥标签页
图3:Haipay公钥标签页 — 切换至平台公钥查看和搜索

4. 关联业务ID筛选

面板顶部提供关联业务ID筛选项,支持单选下拉搜索。您可以搜索该商户关联的所有 appId 进行筛选查看。
关联业务ID筛选
图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 公私钥。
HaiPay一键生成密钥
图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 格式。
公钥上传至 HaiPay 平台时,请去掉前后的 -----BEGIN PUBLIC KEY----------END PUBLIC KEY-----,以及换行和空格。仅保留 Base64 编码内容。
与方式一的区别选择自行创建方式时,替换仍需二次弹窗确认,但不会将私钥复制至剪贴板(因为没有平台生成私钥的操作)。私钥由您自行保管。

7. 业务ID映射

在新增/更换密钥弹窗中,“映射业务ID”提供两个选项:“全部”“特定业务ID”。不同的选择决定了密钥与业务ID的关联方式。

7.1 不更改映射ID(选择“全部”)

当选择“全部”时,新的公钥将应用到该商户下的所有业务ID。后续新增的业务也会自动配置上该公钥。
不更改映射ID — 选择全部
图8:映射业务ID选择“全部” — 公钥应用于所有业务ID

7.2 更改密钥映射(选择“特定业务ID”)

当选择“特定业务ID”时,将打开一个穿梭框(Transfer Box),用于选择将该公钥映射到哪些业务ID。
穿梭框 — 业务ID映射
图9:穿梭框界面 — 左侧为未映射/全部业务ID,右侧为已选定业务ID
穿梭框的结构如下:
该面板内的业务ID从右侧移至左侧时,不视作已经映射了的业务ID。若有其他密钥映射了业务ID,则进行隐藏,但不针对该密钥的映射进行隐藏
穿梭框详细视图
图10:穿梭框详细视图 — 含搜索、分页、穿梭按钮

8. 密钥覆盖提醒

当您在新增/更换密钥弹窗中提交配置时,如果新的映射范围会覆盖已有公钥的关联关系,系统会自动弹出密钥覆盖提醒,告知您哪些业务ID将受到影响。这是为了防止误操作导致线上签名验证失败。
什么时候会触发覆盖提醒?当您的新密钥映射的业务ID中,已经有其他公钥在关联时,就会触发覆盖提醒。系统需要您确认:是否用新公钥替换这些业务ID原有公钥的关联关系。
根据影响范围不同,会有两种警告类型:
图11:密钥覆盖提醒完整流程 — 从提交到二次确认到生效

8.1 部分映射覆盖

当您的修改仅影响部分已映射的业务ID时,系统会弹出“密钥覆盖提醒”弹窗,明确列出受影响的具体业务ID 弹窗内容如下:
  • 标题:密钥覆盖提醒
  • 警告文案“此次修改将覆盖以下业务id关联的密钥,旧密钥将立即失效。是否继续?”
  • 受影响的业务ID:系统逐行列出所有受影响的 appId(如 1122、3344、5566 等)
  • 操作按钮:「取消」(返回弹窗页面) / 「确认替换」(进入二次确认)
密钥覆盖提醒 — 部分业务ID
图12:密钥覆盖提醒(部分映射覆盖) — 列出受影响的具体业务ID
列表中的业务ID对应的旧公钥在确认替换后将立即失效。请确保这些业务ID已在您的系统中配置好新私钥,否则相关请求将验签失败。

8.2 全部映射覆盖

当您将一个原本仅映射部分业务ID的公钥,更改为映射“所有”业务ID时,该操作会覆盖所有业务ID原有的密钥关联。此时弹窗会警告所有业务ID都将受影响。 弹窗内容如下:
  • 标题:密钥覆盖提醒
  • 警告文案“此次修改将覆盖所有业务id关联的密钥,旧密钥将立即失效。是否继续?”
  • 操作按钮:「取消」(返回弹窗页面) / 「确认替换」(进入二次确认)
密钥覆盖提醒 — 所有业务ID
图13:密钥覆盖提醒(全部映射覆盖) — 警告所有业务ID都将受影响
“全部映射覆盖”意味着商户名下所有业务ID的密钥将一次性全部替换。这是影响范围最大的操作,请务必确认:
  • 新私钥已安全保存并配置到您的所有业务系统中
  • 选择在业务低峰期执行此操作
  • 已通知相关开发/运维团队做好配合准备

8.3 二次确认

无论您在覆盖提醒弹窗中点击的是“部分映射覆盖”还是“全部映射覆盖”的「确认替换」按钮,系统都会再弹出二次确认弹窗,作为最后一道安全防线。 二次确认弹窗内容如下:
  • 标题:确定替换新密钥?
  • 警告文案“替换密钥是高危操作,原密钥失效后您将不能使用,请务必谨慎操作。”
  • 操作按钮:「取消」(返回覆盖提醒弹窗) / 「确认替换」(执行替换,密钥立即生效)
确定替换新密钥 — 二次确认
图14:二次确认弹窗 — 提醒替换密钥是高危操作
两层确认机制的设计目的:第一层(密钥覆盖提醒)让您了解影响范围,第二层(二次确认)让您最终决定是否执行。请在仔细阅读警告文案后再点击确认。

8.4 确认后的执行逻辑

在二次确认点击「确认替换」后,系统将立即执行密钥替换,具体逻辑如下:
关于“返回/取消”按钮无论在第一层覆盖提醒弹窗还是第二层二次确认弹窗中,点击「取消」或「返回」按钮都会回到密钥配置弹窗页面,不会直接关闭弹窗。您可以继续修改配置或手动关闭弹窗。

9. 单独更换密钥或修改映射

除了使用顶部“新增/更换密钥”按钮进行批量操作外,您还可以针对特定的公钥进行单独操作。在数据表的“操作”列中,每行提供两个操作链接:
单独更换密钥和更换业务ID映射
图15:操作列 — “替换密钥”和“更换业务id映射”
单独操作的逻辑与使用顶部按钮一致,区别在于:
  • 替换密钥时,业务ID映射是固定的,仅更换密钥内容
  • 更换映射时,公钥是固定的,可不修改,仅调整映射范围
更换业务ID映射界面
图16:更换业务ID映射 — 穿梭框中选择新的映射范围

10. 安全最佳实践

  • 私钥仅显示一次 — 通过平台一键生成密钥时,私钥仅复制到剪贴板,平台不保存。关闭页面后无法再次获取。
  • merchantSecretKey 和商户 RSA 私钥均属于敏感信息,不得写入前端代码、客户端应用、日志或公开仓库。
  • 立即保存私钥 — 生成密钥后请立即将私钥保存到安全的密钥管理系统或加密存储中。
  • 密钥泄露应急 — 若不慎泄露密钥,请及时通过平台更新密钥。

签名安全规则

签名生成规则: 将所有字段值不为 null 且不为 "" 的参数,排除 signsign_type 字段后,按字段名 ASCII 升序排序,取 key 和 value 按 k1=v1&k2=v2&... 的格式进行拼接,并在结尾追加 &key=merchantSecretKey(商户密钥)作为待签名串。商户使用 RSA 私钥按 SHA256WithRSA 算法对待签名串进行签名。
  • 如果字段值为 null"",无需参与验签
  • 接口响应字段可能增加,验证签名时必须将返回报文中的新增有效字段一并纳入验签,不能仅按固定字段列表验签
  • 待签名串必须按 UTF-8 编码为字节序列后再执行 SHA256WithRSA 签名或验签
  • 不要使用宽松空值判断(如 PHP empty() 或 JS !value)过滤参数,否则可能错误排除 0false"0",导致验签失败

11. 密钥格式要求

上传公钥至 HaiPay 平台时,请注意以下格式要求:
如果您选择“HaiPay 一键生成”方式,平台会自动处理格式,您无需手动处理。该注意事项仅适用于“自行创建公私钥”方式。

12. 常见问题

私钥不会保存在 HaiPay 平台。生成后,私钥会自动复制到您的剪贴板,您需要立即保存到安全的位置。平台仅保存公钥用于验签。
关闭弹窗后私钥将无法再次获取,请务必在操作时立即保存。
不能。替换密钥后,原密钥将立即失效。使用旧私钥签名的请求将无法通过 HaiPay 的验签。请在业务低峰期操作,并确保新私钥已配置到您的系统中后再执行替换。
当 appId 栏显示为“所有”时,表示该密钥应用于商户名下的所有业务ID。后续新增的业务也会自动配置上该公钥。如果您需要为不同业务ID配置不同密钥,请使用“特定业务ID”映射功能。
穿梭框左侧面板默认仅展示未映射的业务ID。点击“显示/隐藏已映射”按钮可以切换显示已映射到其他密钥的业务ID,方便您在不同密钥之间调整映射关系。顶部名称也会相应切换为“映射业务ID”或“全部业务ID”。
密钥替换是高危操作,系统设计了多层确认机制以防止误操作:
  • 第一层:密钥覆盖提醒 — 告知哪些业务ID会受影响
  • 第二层:二次确认弹窗 — 最终确认是否执行替换
任意一步点击“返回/取消”都会回到弹窗页面,不会直接关闭。
在“新增/更换密钥”弹窗中,映射业务ID选择“特定业务ID”,打开穿梭框。在穿梭框中将需要映射的业务ID从左侧移至右侧,确认后该公钥将仅应用于右侧选中的业务ID。您也可以在数据表操作列点击“更换业务id映射”来调整已有公钥的映射范围。
请检查以下几点:
  • 确认使用的私钥与上传至平台的公钥是同一对密钥
  • 确认签名串是否按 ASCII 升序排序拼接
  • 确认排除了 signsign_type 字段
  • 确认字段值为 null"" 的参数未参与签名
  • 确认待签名串使用 UTF-8 编码
  • 确认未使用宽松空值判断(如 PHP empty() 或 JS !value
  • 验证返回报文时,确认将所有新增有效字段纳入验签

相关主题

集成步骤指南

从账号创建到首次 API 调用的完整接入流程。

联调环境与请求地址

API 联调环境说明与请求地址一览。

接口说明与公共规则

HaiPay 接口说明与公共请求/返回规则。

RSA 在线密钥生成工具

纯 JS 实现的 RSA 密钥对在线生成工具,不会与服务器交互。

最后修改于 2026年9月4日