This section aims to explain the signature mechanism and message content used between the accessing party's system and EVO Payment when starting API integration.

Message Protocol

Communication needs to follow the HTTP protocol.

Message Content

According to the HTTP protocol, message content should be divided into two independent parts: the HTTP request/response Header and the HTTP request/response Body.

Request/Response Header

The content of the request/response Header should include the following parameters:

Header Parameters	Description
Content-Type	Specify “application/json; charset=utf-8”; the request and response message bodies must be in JSON format, and the character encoding must be UTF-8. This field will also be returned in the response.
DateTime	The time when the request is sent, in a format that follows ISO8601: YYYY-MM-DDThh:mm:ssTZD. This field will also be returned in the response.
KeyID	The unique identifier of the signature key assigned by EVO Payment. This identifier should be the same in the response and request, and it can be sent as an optional item.
MsgID	This is an ID used to trace every API request from the merchant. It is recommended to use a UUID (Universally Unique Identifier) or GUID (Globally Unique Identifier), for example, 2d21a5715c034efb7e0aa383b885fc7a. It is recommended to keep the length of this value to no more than 32 characters. EVO Payment will not validate this value and will return it unchanged in the response message. Usage instructions: The field type is string (maximum length 1024).
SignType	Encryption method, such as: SHA256, SHA512, HMAC-SHA256, HMAC-SHA512
Authorization	Message signature. For details, please refer to the Message Signature section.

Signature Method

Each API request and response message contains a message signature that needs to be verified. The message sender must generate the signature before sending the message, and the message receiver must verify the signature before applying business logic. To generate/verify a message signature, the following steps need to be performed.

Obtain the Signature Key

The merchant needs to apply to the acquirer or EVO Payment account manager for a signature key assigned by EVO Payment. The key is a 32-character string, and each sid will be assigned a key. For example, 64b59e70e15445196b1b5d2935f4e1bc. The merchant should properly store this key on the server side. If there is a risk that the key has been leaked, the merchant needs to promptly contact the acquirer or EVO Payment account manager to reset it.

Generate the Signature

Before sending a request message to EVO Payment, the merchant needs to generate a message signature and place it in the request message.
1.Construct the string to be signed
Before using a specific signature algorithm, the merchant needs to construct a string to be signed. The construction method is as follows:
Generate the string to be signed according to the following method. The string to be signed contains 6 lines. Each line contains one parameter and ends with a newline character, except for the last line. If a line is empty, that line will not exist. The newline character is \n (ASCII code value 0x0A).

1.HTTP method: POST/GET/PUT/DELETE.
2.Request URL: Request path + query string. Remember to remove the domain part of the URL.
3.DateTime in HTTP header: The time of the message being sent.
4.Signature key: The key assigned by EVO Payment.
5.MsgID in HTTP header: The ID for the merchant to trace every API request.
6.HTTP body: All the data submitted in the HTTP body.

The following is an example of a string to be signed:

2.Calculate the signature value

Use the SHA256, SHA512, HMAC-SHA256, or HMAC-SHA512 algorithm to calculate the hash value of the string to be signed. The merchant uses the resulting hash value as the signature value. For HMAC signature types, the signature key is the same as the signature key assigned by EVO Payment.

Example: Signature value calculated using SHA256:
e9ce1bfb697c272fa75848ef0a7eb7c4f8019e5f46dc3141fe936830c32f397c

3.Place the calculated signature in the HTTP Header
The merchant can obtain an HTTP request message with a signature and send it to EVO Payment:

Verify the Signature of Messages Received from EVO Payment

1.Construct the string to be signed
Based on the EVO Payment request received, construct a string using the same fields as the string constructed for signing above (same as the code block above)

2.Calculate the signature using the same signature method
Calculate the signature using the same method as EVO Payment

3.Verify the signature

Obtain the Authorization value in the HTTP request Header and compare it with the signature value calculated above to see whether they match. If they match, continue business logic processing on the merchant side. If they do not match, processing on the merchant side should be stopped, and check whether the key is correct. If necessary, contact the EVO Payment account manager for assistance

Security Requirements and Message Format

Message Protocol#

Message Content#

Request/Response Header#

Signature Method#

Obtain the Signature Key#

Generate the Signature#