EVO Cloud API Portal

简体中文

ENG

简体中文

ENG

Signature and Message Header ​

To verify the integration of messages, each API request and response includes a message signature that must be validated. The message sender must generate the signature before sending the message, and the receiver must validate the signature before processing the message. The process of generating /validating the message signature involves the following steps.

Signature Algorithm Description ​

Step 1: Generate a signature string HTTP method, URL string, DateTime, Key, msgID and HTTP body are concatenated in fixed order with newlines(\n) to get the signature string.

  • HTTP method: POST/GET/PUT/DELETE.
  • URL string: URL path + URL parameters.
  • DateTime: Time 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.
  • Key: Key assigned by EVO Cloud for signing / verifying.
  • MsgID: The suggested value is UUID or GUID to mark this request, such 2d21a5715c034efb7e0aa383b885fc7a. Do not exceed 32 characters in length.
  • HTTP body: All the parameters that you want to send in request body. (GET type request without this parameter)

Step 2: Calculate signature ciphertext Sign the signature of the string by using SHA256, SHA512, HMAC-SHA256 or HMAC-SHA512.

Step3: Put the signature into the Header of HTTP request Authorization in Header of HTTP request is set as sign.

HTTP Header ​

Below parameters are mandatory to be sent in HTTP header.
  • Authorization: Sign value.
  • Content-type: application/json.
  • DateTime: The request time. The format is YYYY-MM-DDThh:mm:ss+hh:00. Such as 2020-03-04T15:39:40+08:00.
  • MsgID: The suggested value is UUID or GUID to mark this request, such as 2d21a5715c034efb7e0aa383b885fc7a. Do not exceed 32 characters in length.
  • SignType: Algorithm for calculating signatures. SHA256, SHA512, HMAC-SHA256 or HMAC-SHA512.

Example of signature ​

  • For example, the JSON message to be sent is as below:
js
{
    "authorise":{
        "merchantTransID":"202003041539404253642536",
        "storeNum":"999290058120001",
        "merchantTransTime":"2020-03-04T15:39:40+08:00",
        "transAmount":{
            "currency":"USD",
            "value":"10.00"
        },
        "paymentMethod":{
            "token":"pmt_e8b8ec5207975018b90a97c79f2975fa"
        }
    },
    "pspInfo":{
        "sponsorCode":"403111",
        "name":"VISA",
        "merchantID":"999290058120001",
        "merchantName":"test merchant",
        "merchantShortName":"test",
        "street":"Shanghai Pudong district",
        "city":"Shanghai",
        "nation":"CHN",
        "postalCode":"201210",
        "mcc":"5812"
    }
}
  • The first step is to generate the signature string stringSign (using newlines(\n) for connection), assuming signing key = hJ2uGZX2fadzOaYIQifxYVgcIxd60y5C0HlNIRyL2tc. *Please notice the space if you copy below sample from PDF to confirm signature.
js
POST
/v1/payment/sys/SGP/10000001/evo.e-commerce.authorise
2020-03-04T15:39:40+08:00
hJ2uGZX2fadzOaYIQifxYVgcIxd60y5C0HlNIRyL2tc
2d21a5715c034efb7e0aa383b885fc7a
{"authorise":{"merchantTransID":"202003041539404253642536","storeNum":"999290058120001","merchantTransTime":"2020-03-04T15:39:40+08:00","transAmount":{"currency":"156","value":"10.00"},"paymentMethod":{"token":"pmt_e8b8ec5207975018b90a97c79f2975fa"}},"pspInfo":{"sponsorCode":"403111","name":"VISA","merchantID":"999290058120001","merchantName":"test merchant","merchantShortName":"test","street":"Shanghai Pudong district","city":"Shanghai","nation":"CHN","postalCode":"201210","mcc":"5812"}}

• The second step is to calculate the signature value. Sign Type is SHA256

js
sign = SHA256(stringSign) // Note: SHA256 way of signature giving
// In this example, result of sign calculation is "6569cf242b1b7541b0e34f73f3940b04bb363aae14d3712b626abf5e4202c972"

Sign Type is HMAC-SHA256

js
sign = HMAC-SHA256(stringSign,signkey) // Note: For HMAC sign type the sign key is same as signing key that assign by EVO Cloud.
// In this example, result of sign calculation is "A774BBF83B1ABD5DFDD0B1090AAFA3BDBCE6D88DE3B7923FEAE03F9085645428"

• The third step is to put sign in the Header.

js
HTTPReq.Header.Set('Authorization', '6569cf242b1b7541b0e34f73f3940b04bb363aae14d3712b626abf5e4202c972');

• Final data sent (CURL version):

js
curl -X POST \
  HTTPs://everonet.com/v1/payment/sys/SGP/10000001/evo.e-commerce.authorise \
  -H 'Authorization: a59310a9a282a0b72b0871527aa630217d0c3ce30321479a1ffc3f5633dd05be' \
  -H 'Content-type: application/json' \
  -H 'DateTime: 2020-03-04T15:39:40+08:00' \
  -H 'MsgID: 2d21a5715c034efb7e0aa383b885fc7a' \
  -H 'SignType: SHA256' \
  -d '{"authorise":{"merchantTransID":"202003041539404253642536","storeNum":"999290058120001","merchantTransTime":"2020-03-04T15:39:40+08:00","transAmount":{"currency":"156","value":"10.00"},"paymentMethod":{"token":"pmt_e8b8ec5207975018b90a97c79f2975fa"}},"pspInfo":{"sponsorCode":"403111","name":"VISA","merchantID":"999290058120001","merchantName":"test merchant","merchantShortName":"test","street":"Shanghai Pudong district","city":"Shanghai","nation":"CHN","postalCode":"201210","mcc":"5812"}}'

Verify the message signature for the message to be received from EVO Cloud ​

It is highly recommended that the merchant verifies the signature of the message from EVO Cloud, including the API response message and notification message. Here is an example of the response message from EVO Cloud for the above request sample. The following steps show how to verify the signature for it:

js
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DateTime: 2023-07-06T11:27:38+08:00
MsgID: 2c450f8904f4428fa9af077e04557eb0
SignType: SHA256
Authorization: 55b6209adf43213fbacdbc618f34f63a3cf3d1cb670aba86a8bd43bf29f3d9d9

{"merchantOrderInfo":{"merchantOrderID":"T307061688614058119","status":"Pending"},"transAmount":{"currency":"KRW","value":"100"},"result":{"code":"S0000","message":"success"},"linkUrl":"https://hkg-counter-uat.everonet.com/linkpay/348b828e99964ceeb3bc9dc53790c0cf","expiryTime":"2023-08-03T06:07:38+08:00"}

Step 1: Construct the string to be signed Obtain the response body, and use the same rule described in 4.1 to construct the string to be signed. (For GET type’s response the body need to be added in the string) Here is the example of the string to be signed:

js
POST
/g2/v0/payment/mer/S003770/evo.e-commerce.linkpay
2023-07-06T11:27:38+08:00
bed9f8eac5a448248c8220cda84ee435
2c450f8904f4428fa9af077e04557eb0
{"merchantOrderInfo":{"merchantOrderID":"T307061688614058119","status":"Pending"},"transAmount":{"currency":"KRW","value":"100"},"result":{"code":"S0000","message":"success"},"linkUrl":"https://hkg-counter-uat.everonet.com/linkpay/348b828e99964ceeb3bc9dc53790c0cf","expiryTime":"2023-08-03T06:07:38+08:00"}

Important: For notification, the Request URL in signed string is the webhook in the request message. And webhook is defined by merchant. If the webhook does not have Path part. Then this line will be not existed. Such as:

js
POST
2021-12-31T08:30:59+08:00
64b59e70e15445196b1b5d2935f4e1bc
2d21a5715c034efb7e0aa383b885fc7a
{
"eventCode": "LinkPay",
	"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 example above, use SHA256 to calculate the hash of the string above, the signature value is 55b6209adf43213fbacdbc618f34f63a3cf3d1cb670aba86a8bd43bf29f3d9d9. 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 if unmatched, don't continue the business logic processing on the merchant side, check whether the sign key is correct or not, and contact EVO Cloud account manager for help if needed.