> ## Documentation Index
> Fetch the complete documentation index at: https://developer.speedpay.hk/llms.txt
> Use this file to discover all available pages before exploring further.

# 加密与解密指南

> 签名、验签和敏感字段加密的处理说明。

## 请求签名

Open API 请求需要携带 RSA 签名。平台会使用商户在 SpeedPay 商户平台上传的公钥验证请求签名，用于确认请求体完整性、真实性和不可否认性。

## 密钥准备

商户需先生成 RSA 密钥对，并将公钥上传到 SpeedPay 商户平台的 API KEY 配置中。私钥只保存在商户服务端安全路径中。

```bash theme={null}
openssl genrsa -out private_pkcs1.pem 2048
openssl pkcs8 -topk8 -inform PEM -in private_pkcs1.pem -out private_pkcs8.pem -nocrypt
openssl rsa -in private_pkcs8.pem -pubout -out public_pkcs8.pem
```

上传公钥后，系统会生成对应的 API KEY。后续接口调用需携带 API KEY 标识商户身份。

## 签名规则

待签名字符串为实际传输中的完整 JSON 请求体字符串：

```text theme={null}
S1 = request.body
bytes = SHA256withRSA(S1, private_pkcs8)
sign = BASE64(bytes)
Authorization = sign
```

签名结果放入 HTTP Header：

```http theme={null}
Authorization: BASE64_SIGNATURE
Content-Type: application/json
```

请求体的序列化结果必须与实际发送内容完全一致。字段顺序、空格、换行或转义变化都会导致验签失败。

## 回调验签

商户接收 SpeedPay 回调时，需要使用 SpeedPay 提供的公钥验证回调签名。签名及安全机制与商户调用 Open API 相同，验签通过后才能处理业务数据。

## 敏感信息保护

卡三要素、支付密码、证件号、手机号、邮箱等敏感字段需按平台约定处理。商户不应明文记录敏感数据，也不应在普通业务日志中输出完整卡号、CVV 或证件信息。

## 建议

| 建议   | 说明                               |
| ---- | -------------------------------- |
| 私钥保存 | 私钥只保存在商户服务端安全配置或密钥管理系统中          |
| 环境隔离 | 测试和生产环境使用不同密钥                    |
| 回调地址 | 在 API KEY 配置中填写可公网访问的 HTTPS 回调地址 |
| 签名失败 | 不处理业务数据，不返回过多内部细节                |