> ## 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](/global/essentials/version/100/en/common/notification)** — event catalog, terminal-state handling, and product-to-`bizType` mapping
4. **[Best practices](/global/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](/global/api-reference/version/100/en/common/securityAndSignature).
2. **Parse `data`**: For standard-envelope callbacks, `data` is a **JSON string** — call `JSON.parse` before reading fields. **Exception:** **Payout (`WITHDRAW`)** has no `data` field and uses the dedicated `main_order` + `suborders` shape (see [Payout status notification](/global/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; absent for `WITHDRAW` (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

| bizType | Description |
| - | - |
| `PAY` | Gate Pay order status |
| `PAY_FIAT` | Fiat payment order status |
| `PAY_ADDRESS` | Address payment order status |
| `TRANSFER_ADDRESS` | Address payment fund credit |
| `CHAIN_ADDRESS` | Address payment on-chain transaction lifecycle |
| `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](/global/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 |
| `CHAIN_ADDRESS` | `PAY_PASSED` / `PAY_CONFIRMING` / `PAY_DONE` | No | Record the status during on-chain transaction and verification |
| `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 |
| 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 |
| PAY\_PASSED | On-chain transaction compliance verification passed (`CHAIN_ADDRESS`) |
| PAY\_CONFIRMING | On-chain transaction sync started (`CHAIN_ADDRESS`) |
| PAY\_DONE | On-chain transaction confirmed (`CHAIN_ADDRESS`) |
| PAID | Batch order paid |
| RISK\_ADDRESS | Fixed address risk |

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


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