Notification - Gate Pay DOCS

Processing Requirements

For every callback received, you must:

Verify the signature first — See Authentication and Security for signature verification details
Parse the business data and perform idempotent processing
Return the agreed success response

Since the same business event may be delivered more than once, you must implement idempotency using a business-unique identifier.

Recommended Processing Order

To reduce the risk of duplicate processing, premature final-state decisions, or incorrect fund posting, process callbacks in the following order:

Validate headers and verify the signature
Parse bizType, bizId, and bizStatus
Run idempotency checks on the business-unique identifier
Update local business state
Return the success response
Use query APIs for final confirmation on critical fund events

For payment, refund, reward-distribution, and other fund-related flows, callbacks should usually be treated as the primary event source, while final confirmation for critical outcomes should still be verified through the relevant query APIs.

Trigger and Retry Mechanism

Trigger When the order status changes (payment success, timeout, cancellation, closure, or exception), GatePay sends a notification to your configured callback URL. Retry If you do not return the agreed success response or the request times out, GatePay will retry the callback. Signature Verification You must verify all callback signatures before processing. See Authentication and Security for details.

Callback Message Structure

All callbacks contain the following top-level fields:

Field	Type	Description
bizType	string	Notification category
bizId	string	Order ID or business ID
bizStatus	string	Business status (varies by bizType)
client_id	string	Merchant client_id
data	string	Business payload as a JSON string; call `JSON.parse` before use. Structure varies by `bizType` — see each notification subpage.

Example Callback:

{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cdhu-fgrfg44-5ggd-cdvsa",
  "data": "{\"merchantTradeNo\":\"M202603120001\",\"orderAmount\":\"100.00\"}"
}

Callback Acknowledgement Response

Return the following JSON response with HTTP 200:

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

HTTP 200 status is recommended to indicate successful receipt.

​Processing Requirements

​Recommended Processing Order

​Trigger and Retry Mechanism

​Callback Message Structure

​Callback Acknowledgement Response

Processing Requirements

Recommended Processing Order

Trigger and Retry Mechanism

Callback Message Structure

Callback Acknowledgement Response