---
url: 'https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/notify/index.md'
description: >-
  The asynchronous notification interface is used to receive callback
  information for transaction-related events. It is suitable for scenarios that
  require real-time awareness of transaction status changes, such as transaction
  success, refunds, etc. Developers need to configure a publicly accessible
  `notificationUrl` address and ensure that the service supports receiving and
  parsing JSON data in HTTP POST requests. Key features include an automatic
  retry mechanism to handle network instability and clear HTTP response
  handling.
---
## Asynchronous Notification Overview

- First, the merchant configures the asynchronous callback notification `notificationUrl` address.
- Whenever a transaction-related event occurs (such as transaction success), the PingPongCheckOut notification service will create a JSON object containing event-related data and information.
- Then, the PingPongCheckOut notification service sends the JSON object to the developer-configured callback notification `notificationUrl` via HTTP POST request.
After receiving the callback notification, the merchant side can perform subsequent business processing based on the asynchronous notification message.

The process is described as follows:
<div style="width: 100%"><img style="width: 1000px;height: 381px" :src="$withBase('/notify.svg')"></div>

## Receiving Asynchronous Notifications

### Prepare a web service that supports HTTP POST
PingPongCheckOut notification service will push JSON formatted data in HTTP POST manner, so the Web service provided by the developer needs to be able to receive and parse JSON data from HTTP POST requests and return the corresponding HTTP status code.

### Set callback notification address
Developers can configure the callback notification URL address through the `notificationUrl` parameter in each interface input parameter.
> Asynchronous notifications are affected by network connection status on both sides, please ensure the notification address is publicly accessible

### Receive and Respond
For merchant transaction notification responses, follow these conventions:

| Reception Result | HTTP Code Convention                                                                                       | Response Message Format Convention                      |
|------------------|------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| Reception Success | 200 <= `httpcode` < 300, e.g.: 200, 201, 204                                                               | No need to return response message                      |
| Reception Failure | <ul><li> `httpcode` > 300 or `httpcode` < 200</li><li> 200 <= `httpcode` < 300, e.g.: 200, 201, 204</li></ul> | <ul><li> Any response body</li><li> Need to return response message 'FAIL'</li></ul> |

> Retry mechanism: In case of reception failure, the retry mechanism will be triggered. PingPongCheckout will re-send with increasing time intervals within a subsequent period of time, with intervals of `5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h` (if intermediate retry notifications succeed, the retry will be interrupted and no longer continue).

::: danger
1. Merchants cannot rely solely on asynchronous notifications. If transaction results are not received for a long time, merchants should actively initiate transaction queries to PingPongCheckout to check the corresponding transaction results;
2. Do not append query-type parameters after `notificationUrl` to avoid loss. If parameters must be carried, please use pathInfo URL mode;
3. The processing logic of asynchronous notification code cannot perform login state verification.
:::

## PingPongCheckout Callback Notification Server Information
If the merchant side requires firewall configuration to allow PingPongCheckout message notification service to push data, please configure the firewall according to the information below and add the IP addresses to the whitelist:

| Production Environment | Sandbox Environment |
|:----------------------|:-------------------|
| 3.125.243.2           | 52.76.198.228      |
| 3.126.196.22          ||
| 18.195.199.34         ||
| 188.239.12.25         ||

## Notification Messages

<a href="/en/notes/notify/subscription/notify/" target="_blank">Subscription Notification</a>
<br/>
<a href="/en/notes/notify/payment/notify/#transaction-asynchronous-notification" target="_blank">Transaction Asynchronous Notification</a>
<br/>
<a href="/en/notes/notify/refundNotify/#refund-asynchronous-notification" target="_blank">Refund Asynchronous Notification</a>
<br/>
<a href="/en/notes/notify/status/captureNotify/#pre-authorization-confirmation-notification" target="_blank">Pre-authorization Capture Notification</a>
<br/>
<a href="/en/notes/notify/status/voidNotify/#pre-authorization-cancellation-notification" target="_blank">Pre-authorization Cancellation Notification</a>