Skip to main content

Callback Notification Explanation

For transactions such as payments, refunds, and withdrawals, after the user completes the transaction, Pay Protocol will notify the merchant system of the transaction result as parameters through a POST request, according to the notifyUrl passed in by the merchant in the API.

For recharge transactions, after the user completes the recharge, Pay Protocol will notify the merchant system of the transaction result as parameters through a POST request, according to the recharge callback address set by the merchant in the admin console. Please visit Recharge Integration Process -> (Call Process 4) to complete the callback configuration for recharge.

Callback Notification Parameters​

Request Headers​

All callback notifications will include the following parameters in the request headers:

ParameterTypeDescriptionExample Value
X-PAY-KEYStringMerchant's API KeyF1R28pRQ
X-PAY-TIMESTAMPStringUnix timestamp of the request, in seconds1684304935
X-PAY-SIGNStringSignature, details can be found in Introduction to Request SignatureZ0VwhFhFIFePC5M62DdcABkIQDQQUvshzItY9wSKVcg=
Content-TypeStringType of the request bodyapplication/json

Request Body​

For specific callback notification content, please refer to the corresponding interface documentation:

Callback Response​

After the merchant system receives the callback, it needs to return a plain/text type string success to inform Pay Protocol that the callback notification has been successfully received.

Callback Notification Features​

  1. The callback notification address provided by the merchant must be a publicly accessible HTTPS address.
  2. Callback notifications are asynchronous, and the merchant system must be able to handle duplicate notifications.
  3. Callbacks are sent using POST requests.
  4. Callbacks are generally sent at the time of transaction confirmation (success or failure), and are sent up to 6 times, respectively at 0 seconds, 15 seconds, 30 seconds, 3 minutes, 5 minutes, and 10 minutes after transaction confirmation.
  5. When the merchant callback address returns success normally, the system will consider the callback successful and will not send subsequent callback notifications.
  6. Merchants can also call the API interface to actively trigger a callback notification, for details, please refer to the corresponding integration process documentation.

Callback Notification Signature Verification​

The signing method of callback notifications is the same as that of API requests, for details, please refer to Signature Generation.

Points to note:

  1. timestamp is the X-PAY-TIMESTAMP in the request headers.
  2. method is fixed as POST.
  3. requestPath is the path of the callback notification. For example, if a merchant sets the callback address to https://your-callback-url.com/callback, then requestPath is /callback.
  4. body is the request body string of the callback notification.

Compare the sign obtained from the signature with the X-PAY-SIGN in the callback notification, and compare the merchant's API Key with the X-PAY-KEY in the callback request headers. If they match, it means the signature verification has passed.

Last updated on