Signature

SHA Signature Rules

The Signature field in the message header is a signature of the message body content. For example, in the Payment interface:

Step 1: Generate a signature string

TIP

http method, URL string, DateTime, Key, msgID, http body are concatenated in fixed order with newlines(\n) to get the signature string.

String Parameter for Signing	Description
HTTP Method	POST/GET/PUT/DELETE
Request URL	Request path + query parameter string. Excludes the domain part of the URL.
DateTime	The time when the request is sent. Must match the DateTime in the request header.
Key	The signature key assigned by EVO Cloud.
MsgID	Message ID. Must match the MsgID in the request header.
HTTP Body	All parameters you want to send in the request body.

Example

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"}}

Step 2: Calculate the Signature ciphertext

Use SHA256 or SHA512 to compute the hash value of the string to be signed. The resulting hash value will serve as the signature value.
For example, signing the string from Step 1 using SHA256 gives the signature value df8c22b3b91920b4fa2f180693d66dd89231da21a26dd466431234ee652d5ce3.

Step 3: Include the Signature in the HTTP Request Header

Set the SignType in the HTTP header to the signature algorithm used, and set Authorization to the signature value computed in Step 2. The final HTTP request to be sent looks like this:

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"}}

Signature Verification Rules

When you receive a response or asynchronous notification from EVO Cloud, verify the signature in the message header. The verification process is as follows:

Construct the string to be signed using the same method as during signing.

Compute the hash value of the string to be signed, using the same algorithm as in your request.

Compare the result from Step 2 with the Authorization in the message header; if they match, the signature verification is successful.

National Secret Signature Rules

The Signature field in the message header is a signature of the message body content. For example, in the Payment interface:

Key Usage Rules

When using the national secret algorithm for signing, two pairs of SM2 key pairs are required: one pair generated by EVO Cloud and another pair generated by you. After key generation, share the public keys with each other.

Key Usage Rules	Acquirer -> EVO Cloud	EVO Cloud -> Acquirer
Signing	Institution's private key (generated and stored by the institution)	EVO Cloud's private key (generated and stored by EVO Cloud)
Verification	Institution's public key (generated by the institution and shared offline with EVO Cloud)	EVO Cloud's public key (generated by EVO Cloud and shared offline with the institution)

Key Format

Private Key: 64 characters (0-9, A-F), case insensitive

Public Key: 128 characters (0-9, A-F), case insensitive

Step 1: Construct the String to be Signed

Before calculating the signature result, the connecting party needs to construct a string to be signed.

TIP

Connect the HTTP method, Request URL, DateTime, MsgID, and HTTP Body in a fixed order using newline characters (\n) to obtain the string to be signed.

The string to be signed consists of 5 lines, each containing a parameter and ending with a newline character (the last line does not have a newline character). If a line is empty, that line will not exist, and no newline character is needed.

Newline Character: \n (ASCII code value is 0x0A)

String to be Signed Parameters	Description
HTTP method	POST/GET/PUT/DELETE
Request URL	Request path + query parameter string. Excludes the domain part of the URL.
DateTime	The time the request is sent, consistent with the DateTime in the request header.
MsgID	Message ID, consistent with the MsgID in the request header.
HTTP body	All parameters you want to send in the request message body.

:::info Here is a sample constructed string to be signed:

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"}}

Step 2: Calculate the Digest

Use the SM3 algorithm to calculate the digest of the string to be signed. The resulting digest will be used in the next step for signing.

The calculated digest is: 4B652731CB154F60C16324F84D218E1EF6979500AFF69750167A3FE1E637C6FA

Step 3: Calculate the Signature

Use the SM2 algorithm to sign the digest obtained in Step 2. Assume the private key is: 769cdff9cc8b28365a99d61213c13e03d304a1c5c1e8e78343c5e983f82f94d7

The resulting signature is:

0d9c607e8e519e3467ab0b3cc30a2150ee64f4d4001b3daa34e353757df0b4e75aecf7eaf66657752b5a91c0a6db86e067bdd643a38d6eadcde07d78ad7f6134

(the signature result will differ each time it is calculated).

Step 4: Place the Signature in the HTTP Request Header

Set the SignType in the HTTP header to the signing algorithm you used, and set Authorization to the signature value calculated in Step 3. The final HTTP request message to be sent will be:

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"}}

Signature Verification Rules

When you receive a response or asynchronous notification from EVO Cloud, it is recommended that you verify the signature result in the message header. The verification process is as follows:

Construct the string to be signed using the same method as when signing.

Calculate the digest of the string to be signed, using the same method as when signing.

Use the public key provided by EVO Cloud to decrypt the signature information in the Authorization field of the message header.

Compare the results of steps 2 and 3. If they match, the verification is successful.

SHA Signature Rules#

Step 1: Generate a signature string#

Step 2: Calculate the Signature ciphertext#

Step 3: Include the Signature in the HTTP Request Header#

Signature Verification Rules#

National Secret Signature Rules#

Key Usage Rules#

Step 1: Construct the String to be Signed#

Step 2: Calculate the Digest#

Step 3: Calculate the Signature#

Step 4: Place the Signature in the HTTP Request Header#

Signature Verification Rules#

SHA Signature Rules

Step 1: Generate a signature string

Step 2: Calculate the Signature ciphertext

Step 3: Include the Signature in the HTTP Request Header

Signature Verification Rules

National Secret Signature Rules

Key Usage Rules

Step 1: Construct the String to be Signed

Step 2: Calculate the Digest

Step 3: Calculate the Signature

Step 4: Place the Signature in the HTTP Request Header

Signature Verification Rules