加密与解密

用 PHP SDK 加密和解密

初始化

安装 SDK 后，配置四份密钥。以下示例中的文件路径、API Key 请替换为自己的配置。

1. 加密发卡请求

$payload 是按发卡接口填写的业务参数；$idempotencyKey 是业务侧生成并保存的幂等键，同一业务重试复用。

SDK 自动生成加密信封并签名，不需要自行加密或再次包装 Body。另两种加密发卡接口使用相同方法，替换路径和业务参数即可。

2. 解密卡片敏感信息

请求发送普通 JSON。保存本次请求 ID，响应验签成功后，将 data 和本地请求 ID 交给 SDK 解密。

post() 自动验签；decryptSensitiveEnvelope() 自动核对指纹、重建 AAD 并解密。任一步抛出异常时停止处理。

3. 接收 Webhook

在回调地址的 PHP 处理程序中使用同一份本地配置：

handle() 自动验签、检查接收方并解密。失败时不返回成功；不要先解析再重新序列化原始请求体。

接收顺序：验签 → 校验指纹并重建 AAD → 解密 → 校验明文。 签名规则统一见认证与签名。

准备配置

配置	用途
平台鉴权公钥	验证响应和 Webhook 签名
平台加密公钥及指纹	加密发送给平台的请求
客户端加密私钥及配对公钥指纹	解密并核对信封接收密钥
接收方 API Key 业务 ID	Webhook 接收方校验及 AAD；从开发者中心对应 API Key 取得

指纹格式为 SHA256:<64 位小写 hex>，摘要对象为公钥的 SPKI DER 字节。指纹不匹配时，到开发者中心核对该 API Key 登记的加密公钥及轮换记录；不要直接信任信封提供的指纹。

信封与算法

{
  "algorithm": "RSA-OAEP-AES-256-GCM",
  "keyFingerprint": "SHA256:<公钥指纹>",
  "encryptedKey": "<标准 Base64>",
  "ciphertext": "<标准 Base64>",
  "aad": "<标准 Base64>"
}

Webhook 信封另含 envelopeVersion: 1。敏感 API 响应的信封位于 data，Webhook 信封是整个请求体。

项目	规则
密钥包装	RSA-OAEP，SHA-256、MGF1-SHA-256，空 Label
内容加密	AES-256-GCM，32 字节密钥、12 字节 IV、16 字节 Tag
`ciphertext` 布局	将 IV、密文、Tag 按顺序拼接，再进行 Base64 编码
明文	UTF-8 JSON

严格校验 Base64、算法及长度。GCM 认证失败立即终止，不解析或使用部分解密结果。兼容字段 encryptedPayload 不作为解密输入。

三种 AAD

四段以 | 连接后取 UTF-8 字节。使用本地上下文重建，再与严格 Base64 解码后的信封 aad 做长度校验及常量时间比较。

场景	第 1 段	第 2 段	第 3 段	第 4 段
加密请求	本次请求 ID	接口 `routeTemplate`	本次 `X-Timestamp`	平台加密公钥指纹
敏感响应	本次请求 ID	空字符串	加密时间戳	客户端加密公钥指纹
Webhook	投递 ID	固定字符串 `webhook`	`X-SlaunchX-Timestamp`	本地接收方 API Key 业务 ID

四段之间仅添加分隔符，不添加空格。敏感响应第二段为空，实际包含连续两个 |。

敏感响应时间戳

当前生产从信封 aad 获取第三段时间戳。先完成响应验签，再严格解析四段；仅提取时间戳，用本次发送的请求 ID 和本地公钥指纹重建完整 AAD。不要采用回显的请求 ID 或指纹替代本地值。

时间戳由 GCM 的 AAD 认证校验，不可替换成 X-Response-Timestamp。格式和 AAD 比对通过后仍须完成 GCM 认证。

Webhook 接收方

核对 X-SlaunchX-Key-Id 等于本地配置的接收方 API Key 业务 ID。AAD 第四段使用本地值，不是公钥指纹。解密后再次核对 deliveryBizId 和 eventType 与已验签请求头一致。

加密请求

以下发卡接口必须发送加密信封：

POST /card-products/10010105/cards/create

POST /card-products/10010106/shared/cards/create

POST /card-products/10010106/prepaid/cards/create

发卡预检发送普通 JSON。其他接口仅在接口定义明确标注加密时使用。

准备业务参数、持久化的幂等键及请求 ID。

使用本次时间戳构造 AAD，生成信封。

信封只序列化一次，对实际发送字节签名。

发送 X-Request-Id、X-Platform-Encryption-Key-Id 及接口要求的幂等键。

使用 SDK 时传入业务参数和加密选项即可，不手动包装第二层信封。建议先完成发卡预检；单张和多张均通过返回的批次 ID 查询结果。

查询卡片敏感信息

调用 POST /card-products/cards/sensitive/reveal 时，请求发送普通 JSON，不包装加密信封；响应的 data 是加密信封，按上述顺序验签和解密。解密后的明文字段：

字段	类型与校验
`pan`	字符串，12–19 位数字
`cvv`	字符串，3–4 位数字
`expiryMonth`	整数，1–12
`expiryYear`	整数

私钥及 PAN、CVV、解密明文仅在受控服务端流程内使用，不写入日志或错误报告。

Node.js 的 Fetch 响应头使用 headers.get()；Node HTTP 服务端的 Webhook 请求头是小写键对象，例如 req.headers['x-slaunchx-timestamp']。不要混用两种读取方式。

首次调用示例见 SDK 指南，各语言加密和接收器接口以对应交付版本的 README 为准。

用 PHP SDK 加密和解密#

初始化#

1. 加密发卡请求#

2. 解密卡片敏感信息#

3. 接收 Webhook#

准备配置#

信封与算法#

三种 AAD#

敏感响应时间戳#

Webhook 接收方#

加密请求#

查询卡片敏感信息#