> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification

> GatePay sends asynchronous notifications to your configured callback URL whenever order status changes. This guide covers the notification structure, callback types, and integration best practices.

## Processing Requirements

For every callback received, you must:

1. **Verify the signature first** — See [Authentication and Security](https://docs.gate.com/eu/essentials/version/100/en/common/authentication.md) for signature verification details
2. **Parse the business data** and perform idempotent processing
3. **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:

1. Validate headers and verify the signature
2. Parse `bizType`, `bizId`, and `bizStatus`
3. Run idempotency checks on the business-unique identifier
4. Update local business state
5. Return the success response
6. 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](https://docs.gate.com/eu/essentials/version/100/en/common/authentication.md) 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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
```

HTTP 200 status is recommended to indicate successful receipt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.