签名&代码示例

RSA-SHA512 接口请求签名

I. 目的

为保障接口的完整性与调用方身份，平台使用 RSA 非对称签名，摘要算法为 SHA-512（算法名 SHA512withRSA）。签名用于确认请求来自商户，并保证路径、正文和时间戳未被改动。

II. 何时需要签名

商户与 Setu 之间的全部 API 请求都要签名。Setu 发给商户的回调和响应同样要签名，待签名字符串见第四节，其中不含请求路径。

III. 结构与规则

每个请求都必须携带按下列步骤算出的 Signature 请求头，并同时携带 MerchantID 和 Timestamp。

签名算法

摘要： SHA-512（512 位安全散列）

签名： RSA，PKCS#1 v1.5，使用商户私钥

算法名： SHA512withRSA

签名步骤

第 1 步：计算正文哈希（Body Hash）

对实际发送的 JSON 正文原始字节（UTF-8）计算 SHA-512，输出小写十六进制，共 128 个字符。

GET、DELETE 以及正文为空时跳过本步。待签名字符串中不要写入空字符串的 SHA-512。

示例正文（末尾无换行）：

{"merchantRef":"0954f567-ea8f-49b4-920f-c49174aa2c1f","amount":100,"currency":"INR","method":"NATIVE","name":"LuciaLesch","phone":"82445415208","email":"quinten31@yahoo.com","redirectUrl":"https://www.redirect.com/"}

对应的小写十六进制 SHA-512：

bfcd0c58c547c1d5960c73a6cf130cf5ae3f96d115392bdc678a36dab1ea08bdaf271b73db17650536a0a78d04d771557f9c5d71596e36547fb2089deb780784

第 2 步：拼接待签名字符串

有正文时：

stringToSign = requestPathUri + sha512Hex + timestamp

无正文时：

stringToSign = requestPathUri + timestamp

requestPathUri 只取路径，以 / 开头，不含协议、域名和查询串。

有正文、时间戳为 1699447297 时的示例：

/v1/api/payment/initiatebfcd0c58c547c1d5960c73a6cf130cf5ae3f96d115392bdc678a36dab1ea08bdaf271b73db17650536a0a78d04d771557f9c5d71596e36547fb2089deb7807841699447297

使用私钥签名

用商户 RSA 私钥对 stringToSign 的 UTF-8 字节做 SHA512withRSA 签名。

将签名字节做标准 Base64 编码，得到 Signature 请求头。

请求头：

请求头	值
`MerchantID`	商户编号
`Timestamp`	与待签名字符串中相同的 Unix 秒级时间戳
`Signature`	上一步得到的 Base64
`Content-Type`	有正文时为 `application/json`

IV. 安全说明

商户请求使用商户私钥签名，Setu 使用商户公钥验签。
Setu 发给商户的回调和响应，使用 Setu 私钥签名，商户使用 Setu 公钥验签。待签名字符串为 sha512Hex + timestamp，不含 requestPathUri。
路径、正文哈希和时间戳都在签名范围内，签名完成之后不能单独改动其中任何一项。

V. 注意事项

待签名字符串区分大小写，必须逐字节一致。正文哈希必须是小写十六进制。
哈希的必须是实际发送的原始正文。字段顺序、空格、数字和字符串的差别都会改变哈希。
Timestamp 为当前 Unix 时间，单位是秒，并且与拼入待签名字符串的值相同。
Signature 使用标准 Base64（字母表含 +、/、=），单行输出，区分大小写。不要使用 URL-safe Base64。
私钥为 PKCS#8，即 -----BEGIN PRIVATE KEY-----。

VI. 代码示例

Java

Python

PHP

C#(.NET Core)

签名&代码示例

RSA-SHA512 接口请求签名#

I. 目的#

II. 何时需要签名#

III. 结构与规则#

IV. 安全说明#

V. 注意事项#