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

# Notifications Overview

> Explains GatePay asynchronous notifications, including payload structure, status enums, retry rules, and signature verification.

## Reading path

We recommend this order when integrating notifications:

1. **This page (overview)** — shared envelope, retries, signature verification, and `bizType` reference
2. **Business notification pages** — field tables and examples (the refund and reward-distribution pages in this menu)
3. **[Guide: Notification](https://docs.gate.com/eu/essentials/version/100/en/common/notification.md)** — event catalog, terminal-state handling, and product-to-`bizType` mapping
4. **[Best practices](https://docs.gate.com/eu/api-reference/version/100/en/common/bestPractices.md)** — payment query fallback, 10s refund rule, and security guidance

## Overview

When order status changes (payment success, timeout, cancellation, closure, exception, and similar events), GatePay sends an asynchronous POST notification to the **callback URL** configured at merchant registration.

* **Delivery**: GatePay delivers JSON notifications to your callback URL via POST.
* **Retry**: If delivery fails due to network or other issues, GatePay retries after **15 seconds (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice)**. If retries still fail, use the relevant query APIs to obtain the latest status.
* **Idempotency**: The same business event may be delivered more than once. Implement idempotent processing using business-unique identifiers such as `bizId` and `merchantTradeNo`.

## Processing requirements

1. **Verify signature**: Validate the signature before processing business logic. Request headers include `X-GatePay-Timestamp`, `X-GatePay-Nonce`, and `X-GatePay-Signature`. See [Security and Signature](https://docs.gate.com/eu/api-reference/version/100/en/common/securityAndSignature.md).
2. **Parse `data`**: For standard-envelope callbacks, `data` is a **JSON string** — call `JSON.parse` before reading fields. **Exception:** Some payout-shaped payloads may omit `data` and use a dedicated order list shape. On the EU site, prefer [Reward Distribution Notification](https://docs.gate.com/eu/api-reference/version/100/en/endpoint/withdraw/rewardDistributionNotify.md) for batch reward callbacks. Top-level `client_id` / `clientId` may be absent or mixed; follow the actual callback.
3. **Acknowledge**: Return HTTP 200 with JSON `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. Returning `FAIL` or timing out triggers retries.

## Message structure

| Field | Description |
| - | - |
| bizType | Business type |
| bizId | Business ID |
| bizStatus | Business status |
| client\_id / clientId | Application ClientId (field name varies; may be absent) |
| data | Business payload as a JSON string (see each business notification page) |

### Message JSON example

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "order_123456",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "your_client_id",
  "data": "{...}"
}
```

## bizType

On the EU site, documented callback pages cover payment, refund, and reward-distribution notifications:

| bizType | Description |
| - | - |
| `PAY` | Gate Pay order status |
| `PAY_REFUND` | Refund status |
| `PAY_BATCH` | Batch transfer / reward |

## Terminal states at a glance

| bizType | bizStatus (examples) | Terminal | Suggested action |
| - | - | - | - |
| `PAY` | `PAY_SUCCESS` | Yes | Mark paid and fulfill |
| `PAY` | `PAY_ERROR` / `PAY_CLOSE` | Yes | Mark failed/closed; stop polling |
| `PAY_REFUND` | `REFUND_PROCESS` | No | Mark processing; wait or query |
| `PAY_REFUND` | `REFUND_SUCCESS` / `REFUND_REJECTED` | Yes | Reconcile / manual review |

## bizStatus enum (payment)

| bizStatus | Description |
| - | - |
| PAY\_SUCCESS | Payment successful |
| PAY\_ERROR | Payment failed |
| PAY\_CLOSE | Payment closed |
| REFUND\_SUCCESS | Refund successful |
| REFUND\_PROCESS | Refund in process |
| REFUND\_REJECTED | Refund rejected |
| PAID | Batch order paid |

Other statuses may appear in production payloads but are not published in the EU API Reference.


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