> ## 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 (Payment / OTC / Payout / Subscription / Institution groups in this menu)
3. **[Guide: Notification](/essentials/version/100/en/common/notification)** — event catalog, terminal-state handling, and product-to-`bizType` mapping
4. **[Best practices](/api-reference/version/100/en/common/bestPractices)** — 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](/api-reference/version/100/en/common/securityAndSignature).
2. **Parse `data`**: For callbacks using the standard envelope, `data` is always a **JSON string** — call `JSON.parse` before reading fields. **Payout (`WITHDRAW`)** has no `data` field and uses the dedicated `main_order` + `suborders` shape (see [Payout status notification](/api-reference/version/100/en/endpoint/withdraw/callback)). 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 (`WITHDRAW` excepted; see payout notification page) |

### Message JSON example

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

## bizType

| bizType                                           | Description                          |
| ------------------------------------------------- | ------------------------------------ |
| `PAY`                                             | Gate Pay order status                |
| `PAY_FIAT`                                        | Fiat payment order status            |
| `PAY_ADDRESS` / `TRANSFER_ADDRESS`                | Address payment status / fund credit |
| `PAY_FIXED_ADDRESS`                               | Static address collection            |
| `FIXED_ADDRESS_RISK`                              | Static address risk                  |
| `PAY_REFUND`                                      | Refund status                        |
| `PAY_BATCH`                                       | Batch transfer / reward              |
| `PAY_GIFT_BATCH`                                  | Gift card batch payment              |
| `PAY_UNRESOLVED`                                  | Unresolved payment                   |
| `INSTITUTION`                                     | Institution sub-account result       |
| `OTC`                                             | OTC on-ramp / off-ramp               |
| `WITHDRAW`                                        | Payout / withdrawal batch            |
| `SUBSCRIPTION_ORDER_STATUS`                       | Subscription order status            |
| `SUBSCRIPTION_PAYMENT` / `ACCOUNT_AUTH_DEDUCTION` | Subscription / authorized deduction  |

## Terminal states at a glance

See the full [event catalog in the Guide](/essentials/version/100/en/common/notification#event-catalog).

| bizType             | bizStatus (examples)                                      | Terminal | Suggested action                     |
| ------------------- | --------------------------------------------------------- | -------- | ------------------------------------ |
| `PAY` / `PAY_FIAT`  | `PAY_SUCCESS`                                             | Yes      | Mark paid and fulfill                |
| `PAY` / `PAY_FIAT`  | `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            |
| `PAY_ADDRESS`       | `PAY_EXPIRED_IN_PROCESS`                                  | No       | Do not finalize until chain confirms |
| `TRANSFER_ADDRESS`  | `TRANSFERRED_ADDRESS_BLOCK`                               | Yes      | Mark exceptional; do not credit      |
| `PAY_FIXED_ADDRESS` | `PAY_BLOCK`                                               | Yes      | Risk funds; do not credit            |
| `WITHDRAW`          | `WITHDRAW_SUCCESS` / `WITHDRAW_PARTIAL` / `WITHDRAW_FAIL` | Yes      | Reconcile batch and sub-orders       |
| `INSTITUTION`       | `INSTITUTION_ACCOUNT_FAIL`                                | Yes      | Record failure; manual follow-up     |

## bizStatus enum (payment / address)

| bizStatus                      | Description                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------- |
| PAY\_SUCCESS                   | Payment successful                                                           |
| PAY\_ERROR                     | Payment failed                                                               |
| PAY\_CLOSE                     | Payment closed                                                               |
| PAY\_BLOCK                     | Static address review / risk block                                           |
| REFUND\_SUCCESS                | Refund successful                                                            |
| REFUND\_PROCESS                | Refund in process                                                            |
| REFUND\_REJECTED               | Refund rejected                                                              |
| PAY\_EXPIRED\_IN\_PROCESS      | Target amount reached during validity but on-chain records still unconfirmed |
| TRANSFERRED\_ADDRESS\_IN\_TERM | Address credited within term                                                 |
| TRANSFERRED\_ADDRESS\_DELAY    | Delayed address credit                                                       |
| CONVERT\_ADDRESS\_PAY\_DELAY   | Convert address payment delayed                                              |
| TRANSFERRED\_ADDRESS\_BLOCK    | Address transfer blocked                                                     |
| PAID                           | Batch order paid                                                             |
| RISK\_ADDRESS                  | Fixed address risk                                                           |

Subscription, OTC, institution, and unresolved-payment statuses are documented on their respective pages.