API Rules

Protocol and certificate

EVO Cloud 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 certificate issued by the known certificate authority (CA).

Time express

All the API fields with type DateTime, for example, merchantTransInfo.merchantTransTime, follow the format defined in ISO 8601 (YYYY-MM-DDThh:mm:ssTZD).

HTTP header

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

Header Parameters	Description
Content-Type	Specify `application/json; charset=utf-8`, which means the message body of the request and response must be in JSON format, and the character encoding is UTF-8. It will be echoed back in the response message.
DateTime	The 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`. It will be echoed back in the response message.
KeyID	The unique identifier for the signature key assigned by EVO Cloud. The response and request should be the same and can be optionally sent.
MsgID	An 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. Usage Instruction: Field Type: String(1024)
SignType	The method of the message being signed. It can be `SHA256`, `SHA512`, `HMAC-SHA256`, or `HMAC-SHA512`.
Authorization	The 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 EVO Cloud from the acquirer or EVO Cloud account manager. The key is a 32-character string assigned per sid. For example, 64b59e70e15445196b1b5d2935f4e1bc. The merchant should keep the key secret on server-side, and if at risk of being compromised, needs to contact the acquirer or EVO Cloud account manager to reset it promptly.

Generate the message signature for the message to be sent

Before sending a request message to EVO Cloud, 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.

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 be not existed. \n (ASCII code value is 0x0A) is the newline character.

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

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/S024116/payment
2021-12-31T08:30:59+08:00
64b59e70e15445196b1b5d2935f4e1bc
2d21a5715c034efb7e0aa383b885fc7a
{
    "merchantTransInfo": {
        "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
        "merchantTransTime": "2021-12-31T08:30:59+08:00"
    },
    "storeInfo": {
        "mcc": "5411"
    },
    "transAmount": {
        "currency": "USD",
        "value": "10.00"
    },
    "validTime": "120",
    "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
    "paymentMethod": {
        "type": "e-wallet",
        "e-wallet": {
            "paymentBrand": "Alipay"
        }
    },
    "transInitiator": {
        "platform": "WEB"
    },
    "tradeInfo": {
        "tradeType": "Sale of goods",
        "goodsName": "iPhone 13",
        "goodsDescription": "This is an iPhone 13",
        "totalQuantity": "2"
    },
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
    "metadata": "This is a metadata"
}

Step 2: Calculate the signature value

Use SHA256, SHA512, HMAC-SHA256 or HMAC-SHA512 to calculate the hash of the string to be signed. The merchant will get the hash value as the signature value. For HMAC sign type the sign key is same as signing key that assign by EVO Cloud.

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

For example, using HMAC-SHA256 with the string to be signed above, the signature value is ef949039abf8ba97f82cb80afb2e595a0edccfea9c330ff39cc40d9cf1ec3e05.

Step 3: Put the signature into HTTP header

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

SignType: SHA256
Authorization: 41e4d284fce485523b62a20922ade75f92469c7eed742dfaa0d8e0b4f213f0ae

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

POST /g2/v1/payment/mer/S024116/payment HTTP/1.1
Host: {EVO_Cloud_DOMAIN_NAME.com}
DateTime: 2021-12-31T08:30:59+08:00
MsgID: 2d21a5715c034efb7e0aa383b885fc7a
SignType: SHA256
Authorization: 41e4d284fce485523b62a20922ade75f92469c7eed742dfaa0d8e0b4f213f0ae
Content-Type: application/json
Content-Length: 815

{
    "merchantTransInfo": {
        "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
        "merchantTransTime": "2021-12-31T08:30:59+08:00"
    },
    "storeInfo": {
        "mcc": "5411"
    },
    "transAmount": {
        "currency": "USD",
        "value": "10.00"
    },
    "validTime": "120",
    "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
    "paymentMethod": {
        "type": "e-wallet",
        "e-wallet": {
            "paymentBrand": "Alipay"
        }
    },
    "transInitiator": {
        "platform": "WEB"
    },
    "tradeInfo": {
        "tradeType": "Sale of goods",
        "goodsName": "iPhone 13",
        "goodsDescription": "This is an iPhone 13",
        "totalQuantity": "2"
    },
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
    "metadata": "This is a metadata"
}

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:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DateTime: 2021-12-31T08:30:59+08:00
MsgID: 2d21a5715c034efb7e0aa383b885fc7a
SignType: SHA256
Authorization: 5ebcac84d8438af64bf9ef7f1fe0b63014ac05e3f2abb4c82c817aa7b9108b49

{
    "result": {
        "code": "S0000",
        "message": "Success",
        "pspResponseCode": "PAYMENT_IN_PROCESS",
        "pspMessage": "Payment is processing."
    },
    "action": {
        "type": "redirectUser",
        "redirectData": {
            "url": "https://ALIPAY_REDIRECT_URL.com",
            "method": "GET"
        }
    },
    "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 1: Construct the string to be signed

Obtain the response body, and use the same rule described in <Message signature> Step 1 to construct the string to be signed.

CAUTION

For GET type’s response the body need to be added in the string
If there are query parameter in your request url, you also need add them in the part Request URL in string to be verify signed.

Here is the example of the string to be signed:

POST
/g2/v1/payment/mer/S024116/payment
2021-12-31T08:30:59+08:00
64b59e70e15445196b1b5d2935f4e1bc
2d21a5715c034efb7e0aa383b885fc7a
{
    "result": {
        "code": "S0000",
        "message": "Success",
        "pspResponseCode": "PAYMENT_IN_PROCESS",
        "pspMessage": "Payment is processing."
    },
    "action": {
        "type": "redirectUser",
        "redirectData": {
            "url": "https://ALIPAY_REDIRECT_URL.com",
            "method": "GET"
        }
    },
    "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"
}

TIP

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:

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 message from EVO Cloud, EVO Cloud will use the same SignType which you used in POST type request.

In the example above, use SHA256 to calculate the hash of the string above, the signature value is 5ebcac84d8438af64bf9ef7f1fe0b63014ac05e3f2abb4c82c817aa7b9108b49.

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.

Parameter rules

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

Whether the request succeeds or not is irrelevant with the order of the query parameters.
Whether the request succeeds or not is irrelevant with 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.
The length of all the fields is the number of bytes not the number of characters.

Idempotency

Overview

Idempotency is a Web API design principle defined as the ability to apply the same operation multiple times without changing the result beyond the first try. EVO Cloud API guarantees the idempotency of GET, PUT and DELETE requests, so it’s always safe to retry them. Because a certain amount of intermittent failure is to be expected, the merchant needs a way of reconciling failed requests with a server, and idempotency provides a mechanism for that.

Idempotency for PUT and DELETE requests

Although the point of idempotency is not that multiple identical requests get the same response, but rather that if the merchant sends the same request multiple times, the status of the server remains the same as if the request was only sent once. To simplify error handling for merchants, EVO Cloud implements idempotent processing for PUT and DELETE requests using the HTTP header Idempotency-Key: <key>.

Key Features

Idempotency Key:
- A unique identifier for the message with a maximum length of 64 characters (UUID is recommended).
- If the merchant does not receive a response (e.g., due to a timeout), they can safely retry the request with the same header.
Processing Logic:
- If EVO Cloud has already processed the request, the response from the first attempt will be returned without duplication.
- The idempotency layer in EVO Cloud compares incoming parameters to those of the original request and will return an error unless they are the same, preventing accidental misuse.
Key Storage:
- Idempotency keys are saved at the store level in EVO Cloud, meaning keys are unique to the sid.
- Keys are valid for a minimum period of 24 hours after the first submission but may be retained for longer.
Execution and Validations:
- Results are saved only if an API endpoint starts executing.
- If incoming parameter validations fail, no idempotent result will be saved, as the API endpoints have not been executed, making it safe to retry these requests.
Retry Strategy:
- It is suggested to use an exponential backoff strategy when retrying transactions to avoid flooding the API and running into rate limiting. Learn more about exponential backoff.

The merchant can identify a previously executed response replayed from EVO Cloud by the header Idempotent-Replayed: true.

To enable idempotent behavior, EVO Cloud must maintain a consistent and stateful datastore to compare requests against each other. This idempotent processing relies on the availability of this datastore.

In the unlikely event that the datastore becomes unavailable, the API will return an HTTP 503 – Service Unavailable status. The merchant can retry the request later using the same idempotency key. If there are multiple 503 responses, the merchant may either pause processing and retry the requests later or fallback to non-idempotent processing by not submitting the Idempotency-Key header.

Idempotency for GET and POST requests

Sending idempotency keys in GET requests has no effect and should be avoided, as GET requests are idempotency by definition.

For POST request, EVO Cloud API does NOT guarantee the idempotency. See Error Handling in EVO Cloud Integration Guide for details on how to handle the error with POST request.

Return status and judgement

If an API request is successful with HTTP status code 200, EVO Cloud will provide 3 types of objects to describe the return status for the merchant in the response body:

Object Name	Usage
action	This object informs the merchant that additional action needs to be performed on the front-end web page or app to complete the request. Upon receiving a response containing this object, the merchant should perform the action indicated by `action.type` with the provided parameters. For more details, refer to the EVO Cloud Integration Guide and the specification of each API in Chapter 7.
result	This object indicates the result of the API call. Every response from EVO Cloud with an HTTP status code of 200 contains this object. Merchants can use it to check the result of the API call, including any failure reasons described within the object. For more information, see the Result Code in the Appendix.
paymentMethod.token, payment, capture, cancel, refund, customClearance	These objects are used across different API endpoints and contain a status field to inform the merchant of the object's status. Merchants can utilize this information to check the business status of each object. Refer to the specification of each API in Chapter 7 for further details.

When receiving the response message from EVO Cloud, the merchant should implement the following steps to process it:

Step 1: Check the HTTP status code. If 200, go ahead.
Step 2: Verify the signature. See Message signature for more details.
Step 3: Check if there is an action object in the response body. If yes, perform the action in the front-end web page or APP.
Step 4: If no action object in the response body, check the result object to see if the API call is successful. If yes, go ahead.
Step 5: Check the status field in the objects paymentMethod.token, payment, capture, cancel, refund or dataSubmission for different API requests to get the business status of the request.

Features

After Payment

Features

Authentication

Tokenization

Payment

After Payment

PaymentMethod

FXRateInquiry

Payment

Capture

Cancel

Refund

CancelOrRefund

DataSubmission

Notification

Linkpay

Retrieve Linkpay

Refund

Retrieve Linkpay Refund

Notification

API Rules ​

Protocol and certificate ​

Time express ​

HTTP header ​

Message signature ​

Get the signature key ​

Generate the message signature for the message to be sent ​

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

Parameter rules ​

Idempotency ​

Overview ​

Idempotency for PUT and DELETE requests ​

Idempotency for GET and POST requests ​

Return status and judgement ​