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
20240305175825+0800
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 c0696645edb9f8413dcd458892cbcf9143ecd3fbde8a16c4d46d2f95e65ee4b2.

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: 20240305175825+0800
MsgID: M20240305175825926
SignType: SHA256
Authorization: c0696645edb9f8413dcd458892cbcf9143ecd3fbde8a16c4d46d2f95e65ee4b2
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:

1. Construct the string to be signed using the same method as during signing.
2. Compute the hash value of the string to be signed, using the same algorithm as in your request.
3. 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.

Here is a sample constructed string to be signed:

POST
/g2/v0/payment/acq/10130014/evo.offline.payment
20240305175825+0800
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: 10DC4ACE369A0F56FE44A2A352E35494FDD749D70D61034FF0C5D16DD0E15C50

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: 8362a0a7f35c27541508de8cc51e4aee62a8c8dd072966cee498e36df1ff9f042d5a60137bb058b26e1b57da04e9bed4a3c091d3227dbc8e5a815d249f47430b (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: 20240305175825+0800
MsgID: M20240305175825926
SignType: SM2withSM3
Authorization: 8362a0a7f35c27541508de8cc51e4aee62a8c8dd072966cee498e36df1ff9f042d5a60137bb058b26e1b57da04e9bed4a3c091d3227dbc8e5a815d249f47430b
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:

1. Construct the string to be signed using the same method as when signing.
2. Calculate the digest of the string to be signed, using the same method as when signing.
3. Use the public key provided by EVO Cloud to decrypt the signature information in the Authorization field of the message header.
4. Compare the results of steps 2 and 3. If they match, the verification is successful.