Merchant Connect ZPK 获取流程

1. 概述

本文档说明 Merchant Connect 集成在离线卡 PIN 交易前如何获取或刷新终端级 ZPK（区域 PIN 密钥）。

ZPK 接口是一个密钥管理 API。它不授权卡交易，也不调用 PSP。返回的 ZPK 用配置的机构级 ZMK/BDK 加密。终端或经批准的安全组件使用返回的密钥材料加密 PIN 块，并在后续的 Payment 请求中带上返回的 checkValue，以便 Merchant Connect 定位正确的 ZPK 版本。

3DES 说明： 在本文档中，3DES 指用于 PIN 块处理的三重 DES 加密。它不是 3DS（3-D Secure 持卡人认证）。

项目	说明
接口	ZPK 获取
方法	`GET`
路径	`/g2/v1/payment/mer/{sid}/zpk?terminalID={terminalID}`
协议	HTTPS + JSON 响应
调用方	商户主机或经批准的 POS 集成
请求体	无
密钥来源	机构级 ZMK/BDK
密钥作用域	机构 + 门店 `sid` + 终端 ID
PIN 算法	当前版本为 3DES
是否调用 PSP	否
后续操作	在离线卡 Payment 请求中使用 `checkValue`

{sid} 表示为目标环境分配的商户/门店标识符，在生产集成中不得硬编码。

2. 获取 ZPK

位置	字段	必填	类型	长度	说明
路径	`sid`	是	String	32	门店标识符，同时是 ZPK 绑定的门店维度。
查询参数	`terminalID`	是	String	8	已注册的终端标识符，是 ZPK 绑定的终端维度。

请求无 JSON 体。服务端通过解析 {sid} 代表的门店来推导机构维度。

3. 认证请求头

请求头	必填	说明
`Authorization`	是	Merchant Connect 签名。
`Content-Type`	是	`application/json; charset=utf-8`。
`DateTime`	是	ISO 8601 报文时间戳。
`MsgID`	是	商户生成的请求跟踪标识符。
`SignType`	是	已配置的签名方法，如 `SHA256`、`SHA512`、`HMAC-SHA256`、`HMAC-SHA512`。
`KeyID`	条件必填	启用多级签名密钥时必填。
`Idempotency-Key`	不适用	本 GET 接口无请求体，遵循部署环境的 GET 重试与跟踪策略。

4. 密钥作用域与生命周期

4.1 密钥作用域

Merchant Connect V1 对 ZPK 存储和查询使用终端级隔离：

维度	作用域	说明
密钥来源	机构	BDK/ZMK 在机构级配置。
门店	`sid`	门店从请求路径解析。
终端	`terminalID`	每个已注册终端拥有独立的 ZPK。
版本	`checkValue`	每个 ZPK 版本通过其 checkValue 标识。

ZPK 不得在不同门店或终端之间复用。同一机构级 ZMK/BDK 可作为派生来源，但生成的 ZPK 绑定仍是终端级别的。

4.2 轮换与过期

规则	行为
当前 ZPK	在获取下一个 ZPK 之前，终端的最新版 ZPK 始终为当前密钥。
上一个 ZPK	生成新 ZPK 时，旧版本仍可使用 1 小时。
版本计时	每个旧版本各有其 1 小时窗口；获取新密钥不会延长更早的版本。
查询	Payment 处理使用 `checkValue` 定位终端的当前或仍在有效期内的上一个 ZPK。
版本缺失或过期	Merchant Connect 返回 `B0034`；终端应在重试相关 PIN 交易前获取新的 ZPK。

5. 响应字段

字段路径	成功时必填	类型	长度	说明
`result`	是	Object	—	通用响应结果容器。
`result.code`	是	String	8	响应码。成功为 `S0000`；密钥或校验失败使用已记录的错误码。
`result.message`	是	String	1024	人类可读的响应消息。
`zpk`	成功时必填	Object	—	ZPK 结果容器。失败时省略。
`zpk.status`	成功时必填	String	20	结果状态：`Success` 或 `Failed`。
`zpk.zpk`	成功时必填	String	32	用机构 ZMK 加密后的 ZPK 密文，不是明文 ZPK。
`zpk.checkValue`	成功时必填	String	6	6 位十六进制校验值，Payment 处理时用于标识 ZPK 版本。

6. 请求与响应示例

以下所有值均为占位符。请勿在文档或源码中替换为生产密钥材料。

6.1 请求

请求无 body。

6.2 成功响应

{
  "result": {
    "code": "S0000",
    "message": "Success"
  },
  "zpk": {
    "status": "Success",
    "zpk": "{{zpkCiphertext}}",
    "checkValue": "{{checkValue}}"
  }
}

zpk.zpk 是加密后的 ZPK 密文。集成必须使用经批准的安全密钥管理流程解包；明文 ZPK 严禁在日志、源码或普通应用存储中暴露。

6.3 失败响应：机构密钥未配置

{
  "result": {
    "code": "B0049",
    "message": "ZMK not exist"
  }
}

7. 在线下卡 Payment 中使用 ZPK

成功获取 ZPK 响应后：

终端或经批准的安全组件使用配置的安全密钥流程解包返回的 ZPK。

终端用当前版本的 3DES 方法加密 PIN 块。

终端在 Payment 请求中带上加密的 PIN 和返回的 checkValue。

Merchant Connect 通过机构、门店、终端和 checkValue 定位 ZPK。

若 checkValue 命中当前或不足 1 小时的旧密钥，Merchant Connect 继续 PIN 处理。

若 checkValue 找不到或已过期，Merchant Connect 返回 B0034；按批准的 retry 策略获取新 ZPK 后重试。

Payment 相关字段示例：

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "pin": {
        "encryptedPin": "{{encryptedPinBlock}}",
        "pinEncryptMethod": "3DES",
        "checkValue": "{{checkValue}}"
      }
    }
  },
  "transInitiator": {
    "platform": "POS",
    "paymentScenario": "inStore",
    "terminalID": "{{terminalId}}"
  }
}

卡号、金额、币种、刷卡方式、终端等字段必须遵循 Payment API 契约。本节仅展示依赖 ZPK 的 PIN 字段。

8. 校验与错误处理

具体的 HTTP 状态码和消息格式必须遵循已部署的 Merchant Connect 错误码表。常见的 ZPK 结果包括：

错误码	含义	客户端处理
`S0000`	ZPK 获取成功	安全处理密文并保留 `checkValue`。
`C0000`	未找到机构	检查门店配置和机构映射。
`C0002`	未找到门店	修正 `sid` 后不要原样重试。
`C0003`	在请求的门店下未找到终端（含跨门店终端）	核对门店-终端关系和 `terminalID`。
`B0001`–`B0004`	集团、商户、门店或终端状态非法	重试前先修正资源状态。
`B0005`	未启用 Offline/ZPK 能力	启用所需的产品和配置。
`B0049`	机构 ZMK/BDK 未配置	通过经批准的密钥管理流程配置相应机构密钥。
`B0034`	Payment 的 `checkValue` 缺失、未知或已过期	获取新 ZPK 并按交易 retry 策略重试。
`E0000`	系统错误	按部署环境的重试和支持流程处理；不得记录密钥材料。

当失败原因是资源、配置或密钥版本错误时，请勿盲目重复请求。

ZPK

Merchant Connect ZPK 获取流程#

1. 概述#

2. 获取 ZPK#

3. 认证请求头#

4. 密钥作用域与生命周期#

4.1 密钥作用域#

4.2 轮换与过期#

5. 响应字段#

6. 请求与响应示例#

6.1 请求#

6.2 成功响应#

6.3 失败响应：机构密钥未配置#

7. 在线下卡 Payment 中使用 ZPK#

8. 校验与错误处理#