--- url: >- https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/guide/paymentNotify/index.md description: >- The payment notification integration guide introduces how to configure and receive asynchronous notifications from PingPongCheckOut. Developers need to provide a web service that supports HTTP POST, set an effective `notificationUrl` to receive JSON formatted notification data, and return HTTP status codes according to the agreement. The document also provides key details such as IP information for callback notification servers and retry mechanisms. --- ## Asynchronous Notification Overview - First, the merchant configures the asynchronous callback notification `notificationUrl` address. - Whenever transaction-related events occur (such as successful transactions), the PingPongCheckOut notification service will create a JSON object containing event-related data and other 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 can perform subsequent business processing based on the asynchronous notification message. The process is described as follows: ```mermaid sequenceDiagram participant Buyer as 🛒 Buyer participant MerchantFrontend as 💻 Merchant Frontend participant MerchantBusinessSystem as 🏪 Merchant Business System participant PingPong as 🔄 PingPongCheckOut Buyer->>MerchantFrontend: 1. Select products and checkout activate MerchantFrontend MerchantFrontend->>MerchantBusinessSystem: 2. Request to create order activate MerchantBusinessSystem MerchantBusinessSystem->>PingPong: 3. Create payment order (POST /orders) activate PingPong PingPong-->>MerchantBusinessSystem: 4. Return payment order information (including checkoutUrl) deactivate PingPong MerchantBusinessSystem-->>MerchantFrontend: 5. Return payment link deactivate MerchantBusinessSystem MerchantFrontend->>Buyer: 6. Display payment options MerchantFrontend->>Buyer: 7. Redirect to payment page (checkoutUrl) deactivate MerchantFrontend Buyer->>PingPong: 8. Complete payment on payment page activate PingPong PingPong->>MerchantBusinessSystem: 9. 📡 Asynchronous notification of payment result activate MerchantBusinessSystem Note over PingPong,MerchantBusinessSystem: 🔁 Supports retry mechanism (see retry flowchart for details) MerchantBusinessSystem-->>PingPong: 10. 🟢 Confirm receipt of notification deactivate MerchantBusinessSystem PingPong->>Buyer: 11. Display payment result deactivate PingPong opt Actively query payment result MerchantBusinessSystem->>PingPong: 12. Query order status activate PingPong PingPong-->>MerchantBusinessSystem: 13. Return latest order status deactivate PingPong end ``` [//]: # () ## Receiving Asynchronous Notifications ### Prepare a web service that supports HTTP POST The PingPongCheckOut notification service will push JSON formatted data in HTTP POST manner, so the web service provided by developers needs to be able to receive and parse JSON data from HTTP POST requests and return corresponding HTTP status codes. ### Set callback notification URL Developers can configure the callback notification URL through the `notificationUrl` parameter in each interface input parameters. - The notificationUrl needs to fill in the real address of the merchant's own system, do not fill in the example addresses on the interface documentation or demo. - The notificationUrl must be a complete full path address starting with https:// or http://, and ensure that the domain name and IP in the URL are accessible from the public network, do not fill in localhost, 127.0.0.1, 192.168.x.x and other local or intranet IPs. - The notificationUrl cannot carry parameters. #### Correct Examples - Complete public URL: `https://example.pay.cn:8080/notify/receive` - Public IP with a concrete service path: `https://122.X.X.5:8080/notify/receive` #### Incorrect Examples - Relative path only: `./PayNotify.aspx` - Domain only without a concrete service path: `https://example.demo.cn:80` - Local or intranet address that is not publicly reachable: `https://localhost:8080/notify/` ### Receive and Respond For merchant transaction notification responses, follow these agreements: | Reception Result | HTTP Code Agreement | Response Message Format Agreement | |------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------| | Reception Success | 200 <= `httpcode` < 300, such as: 200, 201, 204 | No response message required (returning has no effect) | | Reception Failure |

`httpcode` > 300 or `httpcode` < 200
200 <= `httpcode` < 300, such as: 200, 201, 204

Any response body content
Need to return response message 'FAIL'

| :::note Tip Retry mechanism: In case of reception failure, the retry mechanism will be triggered. PingPongCheckout will resend with incremental time intervals within a period of time, with intervals of `5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h` (if intermediate retry notifications succeed, they will be interrupted and no further retries will continue). ::: ```mermaid sequenceDiagram participant Merchant as 🏪 Merchant Business System participant NotificationService as 📡 PingPongCheckOut Notification Service Note over NotificationService: 📢 Initial notification NotificationService->>Merchant: 1. Send JSON notification via HTTP POST activate Merchant Merchant-->>NotificationService: 2. Respond to notification (success or failure) deactivate Merchant alt Reception Success (200 <= HTTP Code < 300 and does not return "FAIL") Note over NotificationService: ✅ Notification process ends else Reception Failure Note over NotificationService: 🔁 Trigger retry mechanism Note over NotificationService: ⏱️ Wait 5 seconds then Note over NotificationService: 🔄 1st retry NotificationService->>Merchant: 3. Retry notification 1 activate Merchant Merchant-->>NotificationService: 4. Respond to notification (success or failure) deactivate Merchant alt Reception Success Note over NotificationService: ⏹️ Interrupt retry, process ends else Reception Failure Note over NotificationService: ⏱️ Wait 5 seconds then Note over NotificationService: 🔄 2nd retry NotificationService->>Merchant: 5. Retry notification 2 activate Merchant Merchant-->>NotificationService: 6. Respond to notification (success or failure) deactivate Merchant alt Reception Success Note over NotificationService: ⏹️ Interrupt retry, process ends else Reception Failure Note over NotificationService: ⏱️ Continue retrying with incremental time intervals Note over NotificationService: Intervals are 3 minutes/10 minutes/20 minutes/30 minutes/30 minutes/30 minutes/60 minutes/3 hours/3 hours/3 hours Note over Merchant,NotificationService: 🔄 Each retry repeats the same request-response pattern Note over Merchant,NotificationService: ✅ Any successful reception will interrupt subsequent retries end end end ``` :::warning Note 1. Merchants should not 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 losing them. If you must carry parameters, please use pathInfo URL mode. 3. The processing logic of asynchronous notification code should not perform login state verification. :::
## PingPongCheckout Callback Notification Server Information If the merchant side requires firewall configuration before allowing PingPongCheckout message notification service to push data, please set up the firewall according to the following information and add the IP to the whitelist: ### Production Environment | Region | IP Address | |:-------|:-----------| | EU | 3.125.243.2 | | EU | 3.126.196.22 | | EU | 18.195.199.34 | | SG | 188.239.12.25 | | US | 52.40.91.195 | | US | 44.253.41.116 | | US | 54.187.20.194 | ### Sandbox Environment | IP Address | |:-----------| | 52.76.198.228 | ## Notification Messages Transaction Asynchronous Notification
Refund Asynchronous Notification
Pre-Authorization Capture Notification
Pre-Authorization Void Notification