About EVONETSystem StatusPortal
Products Introduction

Authentication and Signature

Learn how to access Merchant Services APIs.

Suggest Edits

Protocol and certificate

Our API is an HTTP API that requires HTTPS with TLS v1.2 or higher. Client-side needs to validate the certificate got from the server during the TLS handshake. EVO Cloud API endpoints apply the certificate issued by the known certificate authority (CA).

HTTP header

The following HTTP header parameters are required when making API requests to EVONET and receiving the message from EVONET:

Header ParametersDescription
Content-TypeSpecify application/json; charset=utf-8, which means the message body of the request and response must be in the JSON format, and the character encoding is UTF-8. It will be echoed back in the response message.
DateTimeThe time when the message is sent. The format follows ISO 8601, which is YYYY-MM-DDThh:mm:ssTZD. For example, 2021-05-26T10:08:25+08:00.
MsgIDAn ID for a merchant to trace every API request. The suggested value is UUID or GUID, such as 2d21a5715c034efb7e0aa383b885fc7a. It is suggested to specify this value with no more than 32 characters in length. EVO Cloud will not validate this value and will echo it back in the response message.
SignTypeThe method of the message being signed. It can be SHA256 or SHA512.
AuthorizationThe message signature, see Message signature for more details.

Message signature

Each API request and response message contains the message signature to be validated. The message sender must generate the signature before sending the message, and the receiver must validate the signature before applying the business logic. To generate/validate the message signature, the following steps are required.

Get the signature key

The merchant needs to apply the signature key assigned by EVONET. The key is a 32-character string assigned per unique merchant. For example, fe898ce1422d4818bcd07fd873eda560. The merchant should keep the key secret on the server side, and if at risk of being compromised, needs to contact us to reset it promptly.

Generate the message signature for the message to be sent

Before sending a request message to EVONET, the merchant needs to generate the message signature and put it into the request message.

Step 1 Construct the string to be signed

Before using a specific signature algorithm, the merchant needs to construct a string to be signed.

📘

Concatenate HTTP method, URL string, DateTime, Key, msgID and HTTP body in fixed order with newlines (\n) to get the signature string.

Formulate the string to be signed according to the following method. The string to be signed has 6 lines. Each line includes a parameter and ends with a newline character, excluding the last line. If a line is empty, this line will not exist and a newline character is not required.

newline character: \n (ASCII code value is 0x0A)

ParameterDescription
HTTP methodPOST/GET/PUT/DELETE.
Request URLRequest path + query string. Remember to remove the domain part of the URL.
DateTimeTime to be sent in the request. The format is YYYY-MM-DDThh:mm:ss+hh:00. Such as 2020-03-04T15:39:40+08:00.
KeyKey assigned by EVONET for signing/verifying.
MsgIDThe suggested value is UUID or GUID to mark this request, such 2d21a5715c034efb7e0aa383b885fc7a. Do not exceed 32 characters in length.
HTTP bodyAll the parameters that you want to send in the request body.

📘

Example

Here is an example of the string to be signed. Please take care of the space and newline characters if you copy the sample from the document to your source code to validate:

POST
/g2/v1/payment/mer/S003991/payment
2023-08-09T18:32:18+08:00
fe898ce1422d4818bcd07fd873eda560
M202308091691577138200
{"merchantTransInfo":{"merchantTransID":"T308091691576982397","merchantTransTime":"2023-08-09T18:29:42+08:00","merchantOrderReference":"fill in ordernum in your system"},"transAmount":{"currency":"HKD","value":"1.00"},"returnURL":"https://YOUR_COMPANY.com/RETURNURL","paymentMethod":{"type":"e-wallet","e-wallet":{"paymentBrand":"WeChat_Pay"}},"transInitiator":{"userCreateIP":"222.71.133.101","platform":"WEB"},"userInfo":{"reference":"fill in buyer id in your system","email":"fill in buyer email","name":"fill in buyer name"},"tradeInfo":{"tradeType":"Sale of goods","goodsName":"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1","totalQuantity":"2"},"metadata":"This is a metadata","webhook":"https://YOUR_COMPANY.com/WEBHOOK"}

Step 2 Calculate the signature value

Use SHA256 or SHA512 to calculate the hash of the string to be signed. The merchant will get the hash value as the signature value.

For example, using SHA256 with the string to be signed above, the signature value is

9adfced837a63d79004f60ea4b7b488b6e7d8beb39e48165704089504390dc0d

Step 3 Put the Signature into the Header

Set the signature algorithm into HTTP header SignType, and signature value into Authorization as the following example:

SignType: SHA256
Authorization: 9adfced837a63d79004f60ea4b7b488b6e7d8beb39e48165704089504390dc0d

Then the merchant can get an HTTP request message with the signature as below to be sent:

POST /g2/v1/payment/mer/S003991/payment HTTP/1.1
Host: {EVONET_DOMAIN_NAME.com}
DateTime: 2023-08-09T18:32:18+08:00
MsgID: M202308091691577138200
SignType: SHA256
Authorization: 9adfced837a63d79004f60ea4b7b488b6e7d8beb39e48165704089504390dc0d
Content-Type: application/json

{"merchantTransInfo":{"merchantTransID":"T308091691576982397","merchantTransTime":"2023-08-09T18:29:42+08:00","merchantOrderReference":"fill in ordernum in your system"},"transAmount":{"currency":"HKD","value":"1.00"},"returnURL":"https://YOUR_COMPANY.com/RETURNURL","paymentMethod":{"type":"e-wallet","e-wallet":{"paymentBrand":"WeChat_Pay"}},"transInitiator":{"userCreateIP":"222.71.133.101","platform":"WEB"},"userInfo":{"reference":"fill in buyer id in your system","email":"fill in buyer email","name":"fill in buyer name"},"tradeInfo":{"tradeType":"Sale of goods","goodsName":"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1","totalQuantity":"2"},"metadata":"This is a metadata","webhook":"https://YOUR_COMPANY.com/WEBHOOK"}

Verify the message signature for the message to be received

It is highly recommended that the merchant verifies the signature of the message from EVONET, including the API response message and notification message.

Here is an example of the response message from EVONET for the above request sample. The following steps show how to verify the signature for it:

HTTP/1.1 200 OK
Date: Wed, 09 Aug 2023 10:32:18 GMT
Content-Type: application/json
Content-Length: 126
Connection: keep-alive
Authorization: 82e026d8b286eea6210c31ad600a85d6bec8e5839f8c640a7be071014a3e9395
Content-Encoding: gzip
DateTime: 2023-08-09T10:32:18Z
MsgID: aa0f3c2d784b8a2b448006cb36163fa0
SignType: SHA256
Vary: Accept-Encoding
X-Trace-Id: EWEdMsGtm7wcQwviArdwWgapD22rkFvze6JjelQW
Strict-Transport-Security: max-age=15724800; includeSubDomains
 
{"metadata":"This is a metadata","result":{"code":"C0009","message":"Duplicated merchantTransID T308091691576982397"}}

Step 1 Construct the string to be signed

Obtain the response body, and use the same rule described above to construct the string to be signed.

Here is an example of the string to be signed:

POST
/g2/v1/payment/mer/S003991/payment
2023-08-09T10:32:18Z
fe898ce1422d4818bcd07fd873eda560
aa0f3c2d784b8a2b448006cb36163fa0
{"metadata":"This is a metadata","result":{"code":"C0009","message":"Duplicated merchantTransID T308091691576982397"}}

🚧

Important

For Notification, the Request URL in signed string is the notification Request path + query string. This URL is defined by merchant. If the URL does not have a Path part ,then this line will be filled with a ‘/’. Such as below.

POST
/
2021-12-31T08:30:59+08:00
64b59e70e15445196b1b5d2935f4e1bc
2d21a5715c034efb7e0aa383b885fc7a
{
"eventCode": "Payment",
	"paymentMethod": {
	    "e-wallet": {
             "paymentBrand": "Alipay"
}
    },
"payment": {
        "status": "Pending",
        "merchantTransInfo": {
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "pspTransInfo": {
            "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
            "pspTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "pspData": {
        "name": "Alipay"
    },
    "metadata": "This is a metadata"
}

Step 2 Calculate the signature value

Get the SignType in the HTTP header, and use the algorithm specified by SignType to calculate the hash of the string to be signed.

In the response example above, use SHA256 to calculate the hash of the string above, the signature value is

82e026d8b286eea6210c31ad600a85d6bec8e5839f8c640a7be071014a3e9395

Step 3 Verify the signature value

Get the Authorization in the HTTP header and compare the value with the signature value calculated above to see if they are matched. If matched, go ahead to apply the business logic processing on the merchant side. Otherwise, don't continue the business logic processing on the merchant side, check whether the signature key is correct or not, and contact us for help if needed.

Parameter rules

The merchant should be aware of the following parameter rules when integrating with EVONET and make appropriate implementation accordingly:

  • Whether the request succeeds or not is irrelevant to the order of the query parameters.
  • Whether the request succeeds or not is irrelevant to the order of the key-value pairs in the request JSON in body parameters.
  • When the response is being processed, the order of the key-value pairs in the response JSON in body parameters should not be assumed.
  • New query parameters or JSON key-value pairs in body parameters may be added to the new API version.
  • When the value of a JSON key-value pair in the request or response in body parameters is null, it can be omitted.
  • The data in the API response may include the information entered by the merchant, which may be input by the user and has not been checked yet. To avoid XSS (cross-site scripting) attacks, the caller should conduct appropriate escaping or filtering based on the scenario before using the response data.

Updated about 1 year ago