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 containing the string: SUCCESS.
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 and the response body SUCCESS.
- 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
- 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:
1.{
2. "eventCode": "Payment",
3. "paymentMethod": {
4. "e-wallet": {
5. "paymentBrand": "Alipay"
6. }
7. },
8. "payment": {
9. "status": "Captured",
10. "merchantTransInfo": {
11. "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
12. "merchantTransTime": "2021-12-31T08:30:59+08:00"
13. },
14. "evoTransInfo": {
15. "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
16. "evoTransTime": "2021-12-31T00:30:59Z"
17. },
18. "pspTransInfo": {
19. "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
20. "pspTransTime": "2021-12-31T08:30:59+08:00"
21. },
22. "transAmount": {
23. "currency": "USD",
24. "value": "10.00"
25. }
26. },
27. "pspData": {
28. "name": "Alipay"
29. },
30. "metadata": "This is a metadata"
31.}