消息签名

SHA 签名规则

报文 Header 中的 Signature 字段是对报文 Body 内容的签名。以 Payment 接口为例：

第一步：构造待签名字符串

在计算签名结果之前，接入方需要构造一个待签名的字符串。

提示

将 HTTP method、Request URL、DateTime、Key、MsgID 和 HTTP Body 按固定顺序用换行符 (\n) 连接起来，得到待签名字符串.

按照以下方法构造的待签名的字符串，待签名的字符串有6行。每行都包含一个参数并以换行符结尾（最后一行没有换行符）。如果一行为空，则该行将不存在，并且不需要换行符。

换行符：\n（ASCII 码值为 0x0A）

待签名字符串参数	描述
HTTP method	POST/GET/PUT/DELETE
Request URL	请求路径+查询参数字符串。不包含 URL 的域名部分。
DateTime	请求发送的时间。与请求 Header 中的 DateTime 一致。
Key	由 EVO Cloud 分配的签名密钥。
MsgID	消息 ID。与请求 Header 中的 MsgID 一致。
HTTP body	您要在请求报文 Body 中发送的所有参数。

信息

下面是一个构建完成的待签名字符串的样例

POST
/g2/v0/payment/acq/10130014/evo.offline.payment
2024-03-05T17:58:25+08:00
NeTQlv6okyBmbelQP1RujxYmnp0S4GtA
M20240305175825926
{"merchantTransInfo":{"merchantTransID":"T20240305175317143","merchantTransTime":"2024-03-05T17:53:17+08:00"},"paymentMethod":{"type":"card","card":{"posEntryMode":"manual","pinFlag":false,"termReadability":"5","cardInfo":{"cardNumber":"4761340000000043"}}},"transAmount":{"currency":"HKD","value":"1.00"},"autoCapture":false,"pspInfo":{"mcc":"5499","sponsorCode":"441378","merchantID":"202106305812001","terminalID":"00000001","merchantName":"Test","storeID":"202106305812001","storeName":"Test Store","street":"Test street","city":"MYS","postCode":"202000","nation":"MYS"}}

第二步：计算签名密文

使用SHA256或SHA512计算待签名字符串的哈希值。将得到哈希值作为签名值。
例如，使用SHA256对第一步中的待签名字符串进行签名，得到的签名值为 df8c22b3b91920b4fa2f180693d66dd89231da21a26dd466431234ee652d5ce3

第三步：将签名放入 HTTP 请求的 Header 中

将 HTTP Header 中的 SignType 设置为您使用的签名算法，将 Authorization 设置为第二步中计算得到的签名值，最终得到最终要发送的 HTTP 请求报文：

POST /g2/v0/payment/acq/10130014/evo.offline.payment HTTP/1.1
Host: {EVO_Cloud_DOMAIN_NAME.com}
DateTime: 2024-03-05T17:58:25+08:00
MsgID: M20240305175825926
SignType: SHA256
Authorization: df8c22b3b91920b4fa2f180693d66dd89231da21a26dd466431234ee652d5ce3
Content-Type: application/json

{"merchantTransInfo":{"merchantTransID":"T20240305175317143","merchantTransTime":"2024-03-05T17:53:17+08:00"},"paymentMethod":{"type":"card","card":{"posEntryMode":"manual","pinFlag":false,"termReadability":"5","cardInfo":{"cardNumber":"4761340000000043"}}},"transAmount":{"currency":"HKD","value":"1.00"},"autoCapture":false,"pspInfo":{"mcc":"5499","sponsorCode":"441378","merchantID":"202106305812001","terminalID":"00000001","merchantName":"Test","storeID":"202106305812001","storeName":"Test Store","street":"Test street","city":"MYS","postCode":"202000","nation":"MYS"}}

验签规则

当您收到来自 EVO Cloud 的应答或异步通知时，建议您对报文 Header 中的签名结果进行验签，验签流程如下：

构造待签名字符串，方法与签名时一致。

对待签名字符串进行哈希值计算，使用的算法与您请求时的算法一致。

将第2步的结果与报文 Header 中的 Authorization 进行对比，如果一致则为验签成功。

国密签名规则

报文 Header 中的 Signature 字段是对报文 Body 内容的签名。使用的签名算法为 SM2withSM3，以 Payment 接口为例：

密钥使用规则

在使用国密算法进行签名时，需要用到两对 SM2 密钥对，其中一对由 EVO Cloud 生成，另一对由您生成。在密钥生成后，相互共享公钥。

密钥使用规则	收单机构 -> EVO Cloud	EVO Cloud -> 收单机构
签名	机构的私钥（机构自行生成并保存）	EVO Cloud 的私钥（EVO CLoud 自行生成并保存）
验签	机构的公钥（机构自行生成并线下交互给 EVO Cloud）	EVO Cloud 的公钥（EVO Cloud自行生成并线下交互给机构）

密钥格式

私钥：64个字符（0-9，A-F），不区分大小写
公钥：128个字符（0-9，A-F），不区分大小写

第一步：构造待签名字符串

在计算签名结果之前，接入方需要构造一个待签名的字符串。

提示

将 HTTP method、Request URL、DateTime、MsgID 和 HTTP Body 按固定顺序用换行符 (\n) 连接起来，得到待签名字符串.

按照以下方法构造的待签名的字符串，待签名的字符串有5行。每行都包含一个参数并以换行符结尾（最后一行没有换行符）。如果一行为空，则该行将不存在，并且不需要换行符。

换行符：\n（ASCII 码值为 0x0A）

待签名字符串参数	描述
HTTP method	POST/GET/PUT/DELETE
Request URL	请求路径+查询参数字符串。不包含 URL 的域名部分。
DateTime	请求发送的时间。与请求 Header 中的 DateTime 一致。
MsgID	消息 ID。与请求 Header 中的 MsgID 一致。
HTTP body	您要在请求报文 Body 中发送的所有参数。

下面是一个构建完成的待签名字符串的样例

POST
/g2/v0/payment/acq/10130014/evo.offline.payment
2024-03-05T17:58:25+08:00
M20240305175825926
{"merchantTransInfo":{"merchantTransID":"T20240305175317143","merchantTransTime":"2024-03-05T17:53:17+08:00"},"paymentMethod":{"type":"card","card":{"posEntryMode":"manual","pinFlag":false,"termReadability":"5","cardInfo":{"cardNumber":"4761340000000043"}}},"transAmount":{"currency":"HKD","value":"1.00"},"autoCapture":false,"pspInfo":{"mcc":"5499","sponsorCode":"441378","merchantID":"202106305812001","terminalID":"00000001","merchantName":"Test","storeID":"202106305812001","storeName":"Test Store","street":"Test street","city":"MYS","postCode":"202000","nation":"MYS"}}

第二步：计算摘要

使用 SM3 算法杂凑方式计算待签名字符串的摘要，将得到的摘要用于下一步的签名。

计算后得到的摘要为：4B652731CB154F60C16324F84D218E1EF6979500AFF69750167A3FE1E637C6FA

第三步：计算签名

使用 SM2 算法对第二步中得到的摘要进行签名（签名格式使用der编码、ASN.1，UserID默认1234567812345678）

假设私钥为：769cdff9cc8b28365a99d61213c13e03d304a1c5c1e8e78343c5e983f82f94d7

签名后得到签名结果为：

0d9c607e8e519e3467ab0b3cc30a2150ee64f4d4001b3daa34e353757df0b4e75aecf7eaf66657752b5a91c0a6db86e067bdd643a38d6eadcde07d78ad7f6134

（每次计算签名结果时签名结果不同）

第四步：将签名放入 HTTP 请求的 Header 中

将 HTTP Header 中的 SignType 设置为您使用的签名算法，将 Authorization 设置为第三步中计算得到的签名值（hex 格式，无需转 base64），最终得到最终要发送的 HTTP 请求报文：

POST /g2/v0/payment/acq/10130014/evo.offline.payment HTTP/1.1
Host: {EVO_Cloud_DOMAIN_NAME.com}
DateTime: 2024-03-05T17:58:25+08:00
MsgID: M20240305175825926
SignType: SM2withSM3
Authorization: 0d9c607e8e519e3467ab0b3cc30a2150ee64f4d4001b3daa34e353757df0b4e75aecf7eaf66657752b5a91c0a6db86e067bdd643a38d6eadcde07d78ad7f6134
Content-Type: application/json

{"merchantTransInfo":{"merchantTransID":"T20240305175317143","merchantTransTime":"2024-03-05T17:53:17+08:00"},"paymentMethod":{"type":"card","card":{"posEntryMode":"manual","pinFlag":false,"termReadability":"5","cardInfo":{"cardNumber":"4761340000000043"}}},"transAmount":{"currency":"HKD","value":"1.00"},"autoCapture":false,"pspInfo":{"mcc":"5499","sponsorCode":"441378","merchantID":"202106305812001","terminalID":"00000001","merchantName":"Test","storeID":"202106305812001","storeName":"Test Store","street":"Test street","city":"MYS","postCode":"202000","nation":"MYS"}}

验签规则

当您收到来自 EVO Cloud 的应答或异步通知时，建议您对报文 Header 中的签名结果进行验签，验签流程如下：

构造待签名字符串，方法与签名时一致。

计算待签名字符串的摘要，方法与签名时一致。

使用 EVO Cloud 提供的公钥对报文 Header 中 Authorization 字段中的签名信息进行解密。

对比 2、3 两步中的结果，如果一致则为验签成功。

SHA 签名规则#

第一步：构造待签名字符串#

第二步：计算签名密文#

第三步：将签名放入 HTTP 请求的 Header 中#

验签规则#

国密签名规则#

密钥使用规则#

第一步：构造待签名字符串#

第二步：计算摘要#

第三步：计算签名#

第四步：将签名放入 HTTP 请求的 Header 中#

验签规则#

SHA 签名规则

第一步：构造待签名字符串

第二步：计算签名密文

第三步：将签名放入 HTTP 请求的 Header 中

验签规则

国密签名规则

密钥使用规则

第一步：构造待签名字符串

第二步：计算摘要

第三步：计算签名

第四步：将签名放入 HTTP 请求的 Header 中

验签规则