Accept Notification

It is applicable to both EC and In-Store Scenario.

EVO Cloud notification is a webhook to inform you the status update of your request. You can expect for a notification for any request processed asynchronously. For example, the payment request in pending status, or the capture, cancel, refund and data submission requests. You can use the notification to automate your business processes such as order management.

Here is the matrix for you reference to see when you can expect a notification:

API Request	API Usage	Notification Trigger
POST PaymentMethod	Tokenize a payment method for a user	Notification sent when the token is generated successfully or fails. Use `paymentMethod.merchantTransInfo` to match your tokenization request in the database.
POST Payment	Make a payment	Notification sent when the payment is completed or fails. If `authenticationOnly` is true, you’ll receive a notification upon completion or failure of authentication. Use `payment.merchantTransInfo` to match your payment request in the database. Different Capture Modes: - Instant Payment: Notification when payment gets captured or fails. - Separate Authorization and Capture: Notification when authorized or fails, followed by another notification for capture status if authorized (includes additional capture object).
POST Capture	Capture a payment	Notification sent when the payment is captured successfully or fails. Use `payment.merchantTransInfo` or `capture.merchantTransInfo` to match requests in the database.
POST Cancel	Cancel a payment	Notification sent when the payment is cancelled successfully or fails. Use `payment.merchantTransInfo` or `cancel.merchantTransInfo` to match requests in the database.
POST Refund	Refund a payment	Notification sent when the payment is refunded successfully or fails. Use `payment.merchantTransInfo` or `refund.merchantTransInfo` to match requests in the database.
POST CancelOrRefund	Close or refund a payment	Notification sent when the payment is refunded/closed successfully or fails. Use `payment.merchantTransInfo` or `refund.merchantTransInfo`/`cancel.merchantTransInfo` to match requests in the database.
POST DataSubmission	Submit data for Customs Clearance	Notification sent when the payment order is successfully submitted to customs or fails. Use `payment.merchantTransInfo` or `dataSubmission.merchantTransInfo` to match requests in the database.
PUT DataSubmission	Resubmit or correct information submitted to customs	Notification sent when the payment order is successfully resubmitted or fails. Use `payment.merchantTransInfo` or `dataSubmission.merchantTransInfo` to match requests in the database.

Other asynchronous notification scenarios unrelated to API calls.

Scenarios	Description
MPM (Static QR Code) transactions	If configured, EVO Cloud will send an asynchronous notification to the specified Webhook after a successful payment. Only successful transactions trigger these notifications.
Settlement notification	If configured, EVO Cloud will send an asynchronous notification to the specified Webhook when a settlement operation occurs. Below is a matrix for reference on when to expect a settlement notification.

Settlement Operations	Description
Merchant Dispute Debit	This is the record of a transaction that is debited to the merchant for a dispute transaction.
Merchant Dispute Credit	This is the record of a transaction that is credited to the merchant for a dispute transaction.
Merchant Risk Hold	This is the record of a transaction that is held for further settlement by the acquirer.
Merchant Risk Release	This is the record of a transaction that is released to the merchant for a transaction held.
Merchant Fee Debit	This is the record of the merchant fee charged to the merchant by the acquirer.
Merchant Fee Credit	This is the record of the merchant fee paid to the merchant by the acquirer.

To process a notification, the following steps are required.

Step 1: Expose an endpoint on your server

Notifications are sent as HTTP callbacks (webhooks) to an endpoint of your server. EVO Cloud requires you to use HTTPS endpoints with TLS v1.2.

To receive notifications, you need a server that has:

An endpoint that can receive an HTTP POST.

For live environments: An open TCP port for HTTPS traffic (443, 8443, or 8843) with TLS v1.2.

For testing environments: An open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (448, 8443, or 8843) with TLS v1.2.

Depending on your network and security requirements, you may also need to add our network to your firewall's whitelist by either adding a domain allow list or systematically resolving our IP addresses with DNS lookup. Please note that we do not provide a list of IP addresses for the allow list, since the IP addresses change over time due to various reasons such as ISP configuration changes. And if you prefer to perform DNS lookup for EVO Cloud domain name, we recommend you to check hourly. However, if you choose to hardcode the resolved IP addresses to the allow list, you still have the risk of a disruption if the IP addresses change during the DNS lookup interval.

Step 2: Send a request with webhook URL

For any request message to EVO Cloud, the webhook is acceptable in the request parameters. Specify it when you send the request and then you can expect a notification for status update of the transaction.

Please note that only when the transaction status becomes Success, you can receive the notification from EVO Cloud.

Step 3: Accept the notification

To ensure that your server is properly accepting the notification, we require you to acknowledge every notification of any type with a response in http code 200.

If we don't receive this response within 5 seconds, all notifications to your endpoint will be queued and retried. See chapter Queued notifications for more details.

When your server receives a notification:

Verify the signature included in the notification. This is to confirm that the notification is sent by EVO Cloud, and not modified during transmission. See API Rules in EVO Cloud API Specification for more details. If the signature is not valid, we recommend you to not acknowledge the notification.

Store the notification in your database / queue.

Acknowledge the notification with an HTTP 200 OK.

Apply your business logic. Make sure that you acknowledge the notification before applying any business logic, because a breakage in your business logic can prevent important updates from reaching your system.

See chapter Notification structure for more details.

Queued notifications

To ensure that the notification is properly delivered, you need to acknowledge it with an appropriate response message. See Step 3 for more details.

If we don't receive the response message within 15 seconds, the notification will be queued, and we'll then retry sending the notification until it is accepted.

The retry attempts happen regularly for up to 9 times, at increasing time intervals:

15 seconds

30 seconds

3 minutes

30 minutes

60 minutes

90 minutes

120 minutes

240 minutes

If your server still does not acknowledge notifications after all the above, our CE team will inform you of this.

The notification queues are maintained separately for each notification, meaning that one queued notification won't affect the others.

Notification structure

Each notification contains an eventCode specifying the type of event initiated the notification.

Event Code	Description
PaymentMethod	Notification for payment method
Payment	Notification for payment
Capture	Notification for capture
Cancel	Notification for cancel
Refund	Notification for refund
DataSubmission	Notification for data submission
StaticQRCode	Notification for MPM (Static QR Code) transaction
NetworkTokenDeleted	Notification for network token deleted
NetworkTokenStatusUpdated	Notification for network token updated
Settlement	Notification for settlement operation

For other fields in the notification message, please refer to EVO Cloud API Specification for more details.

Here is an example of a notification for a successful payment:

Step 1: Expose an endpoint on your server#

Step 2: Send a request with webhook URL#

Step 3: Accept the notification#

Queued notifications#

Notification structure#

Step 1: Expose an endpoint on your server

Step 2: Send a request with webhook URL

Step 3: Accept the notification

Queued notifications

Notification structure