Payment Notification Integration Guide

About 1030 wordsAbout 3 min

2025-03-07

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:

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'

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).

Note

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.
Do not append query-type parameters after notificationUrl, to avoid losing them. If you must carry parameters, please use pathInfo URL mode.
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: