> ## 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](/global/essentials/version/100/en/common/authentication) 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, OTC, payout, 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](/global/essentials/version/100/en/common/authentication) for details.

## Callback Message Structure

All callbacks contain the following top-level fields:

| Field | Type | Description |
| - | - | - |
| bizType | string | Notification category (see [bizType Enumeration](#biztype-enumeration)) |
| 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. Not used on `WITHDRAW` callbacks. 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.

## bizType Enumeration

| Value | Description |
| - | - |
| PAY | Status change for non-address payment orders |
| PAY\_REFUND | Status change for refund orders |
| PAY\_BATCH | Status change for batch reward orders |
| PAY\_GIFT\_BATCH | Status change for batch gift-card payments |
| PAY\_ADDRESS | Status change for address payment orders |
| TRANSFER\_ADDRESS | Funds-flow notification for address payments |
| CHAIN\_ADDRESS | On-chain transaction lifecycle notification for address payments |
| PAY\_FIXED\_ADDRESS | Static-address collection notification |
| WITHDRAW | Withdrawal / payout status change |
| INSTITUTION | Institution API account-related notification |

***

## General Notes

* This notification chapter explains the shared rules for payment, refund, address collection, static-address collection, payout, and institution-related callbacks.
* Detailed callback interpretation for each business flow should still be read together with the corresponding product guide and API Reference.
* If your integration uses multiple payment methods, route processing by `bizType` rather than assuming all callbacks share the same field set.
* Do not rely on a single callback alone to finalize financial state changes in critical flows; combine callbacks with the appropriate query or detail endpoint when needed.

## Payment Product to bizType Mapping

If your integration covers multiple payment products, define the internal routing model from product flow to `bizType` first:

| Product or Scenario | Primary bizType | Notes |
| - | - | - |
| Hosted checkout, web launch, and ordinary non-address payment | `PAY` | Used for non-address payment order status changes |
| Refund | `PAY_REFUND` | Used for refund-state progression |
| Address payment | `PAY_ADDRESS` | Used for address payment order state changes |
| Address-payment fund credit | `TRANSFER_ADDRESS` | Used for credit, delayed-credit, or risk-control outcomes |
| Address-payment on-chain lifecycle | `CHAIN_ADDRESS` | Used for on-chain sync, compliance passed, and confirmation events |
| Static-address collection | `PAY_FIXED_ADDRESS` | Used for static-address collection results |
| Payout / withdrawal | `WITHDRAW` | Used for batch and sub-order status changes |
| Institution sub-account related events | `INSTITUTION` | Used for institution account-opening results |

This page already includes the event catalog summary and terminal-state handling guidance, so you can continue reading the business-specific sections below.

## Hosted Checkout Payment Notification

Hosted checkout payments follow the general `PAY` callback model. For non-address payments, interpret the payment amount using `orderAmount`. For more details on payment integrations, see [Payments](/global/essentials/version/100/en/inflow/payment/payment).

***

## Refund Notifications

Refund orders use the `PAY_REFUND` callback type.

* Use the merchant-side unique identifier `refundRequestId` as the primary key for refund query and reconciliation.
* API-initiated refunds and refunds triggered manually in the merchant console are different operational entry points; the callback description in this documentation applies to API integrations.
* For reliable refund status handling, combine callbacks with the refund query endpoints.

***

## Address Payment Notifications

### PAY\_ADDRESS Status Enumeration

| Status | Applicable Mode | Description |
| - | - | - |
| PAY\_SUCCESS | Non-convert / Convert | Payment succeeded |
| PAY\_ERROR | Non-convert / Convert | Payment failed |
| PAY\_CLOSE | Non-convert / Convert | Order closed |
| PAY\_EXPIRED\_IN\_PROCESS | Non-convert / Convert | Target amount reached within validity period, but still unconfirmed on-chain records |
| PENDING | Convert | Pending |
| PROCESS | Convert | Processing |
| PAID | Convert | Paid |
| EXPIRED | Convert | Expired |

### PAY\_ADDRESS data Fields

| Field | Applicable Mode | Description |
| - | - | - |
| merchantTradeNo | Non-convert / Convert | Merchant order number |
| originalMerchantTradeNo | Non-convert / Convert | Associated original merchant order number (populated for supplementary-order scenarios) |
| productType | Non-convert / Convert | Product type |
| productName | Non-convert / Convert | Product name |
| goodsName | Non-convert / Convert | Goods name |
| tradeType | Non-convert / Convert | Transaction type |
| terminalType | Non-convert / Convert | Terminal type |
| currency | Non-convert / Convert | Pricing currency |
| orderAmount | Non-convert / Convert | Order amount |
| payerId | Non-convert / Convert | Payer identifier |
| createTime | Non-convert / Convert | Creation time |
| transactionId | Non-convert / Convert | Platform transaction ID |
| waitAmountOnChain | Non-convert / Convert | On-chain amount detected but not yet finally credited |
| doneAmountOnChain | Non-convert / Convert | On-chain amount already confirmed and credited |
| channelId | Non-convert / Convert | Channel identifier |
| chain | Non-convert / Convert | Chain name |
| address | Non-convert / Convert | Collection address |
| fromAddress | Non-convert / Convert | Payer address |
| payCurrency | Convert | Payment currency used for conversion |
| payAmount | Convert | Payment amount used for conversion |
| rate | Convert | Exchange rate |
| overPay | Convert | Overpayment amount |

### TRANSFER\_ADDRESS Status Enumeration

| Status | Description |
| - | - |
| TRANSFERRED\_ADDRESS\_IN\_TERM | Credited within the validity period |
| TRANSFERRED\_ADDRESS\_DELAY | Credited after the validity period |
| CONVERT\_ADDRESS\_PAY\_DELAY | Convert delayed-payment notification only; no credit |

### TRANSFER\_ADDRESS data Fields

| Field | Description |
| - | - |
| merchantTradeNo | Merchant order number |
| originalMerchantTradeNo | Associated original merchant order number (populated for supplementary-order scenarios) |
| originalOrderId | Associated original order ID (populated for supplementary-order scenarios) |
| currency | Currency |
| orderAmount | Order amount |
| createTime | Creation time |
| transactionId | Platform transaction ID |
| transferAmount | On-chain transfer amount |
| txHash | Blockchain transaction hash |
| chain | Chain name |
| address | Address |
| channelId | Channel identifier |

Note: In historical payloads or different business flows, the transaction hash field may appear as `txHash`, `tx_hash`, or `hash`, so parsers should handle these variants compatibly.

### CHAIN\_ADDRESS Status Enumeration

| Status | Description |
| - | - |
| PAY\_PASSED | On-chain transaction compliance verification passed |
| PAY\_CONFIRMING | On-chain transaction sync started |
| PAY\_DONE | On-chain transaction confirmed |

### CHAIN\_ADDRESS data Fields

| Field | Type | Description |
| - | - | - |
| merchantTradeNo | string | Merchant order number |
| productType | string | `goodsType` at order creation |
| productName | string | `goodsName` at order creation |
| clientId | string | Merchant `client_id` |
| tradeType | string | `terminalType` at order creation |
| goodsName | string | Goods name |
| terminalType | string | Terminal type |
| currency | string | Order currency |
| orderAmount | number | Order amount |
| payerId | int64 | Payer UID |
| createTime | int64 | Order creation time (milliseconds) |
| transferAmount | number | On-chain received amount |
| txHash | string | On-chain transaction hash |
| channelId | string | Channel identifier |
| chain | string | Blockchain network |
| address | string | Collection address |
| fromAddress | string | Payer address |
| passedTime | int64 | On-chain transaction compliance verification passed time (milliseconds); returned when `bizStatus=PAY_PASSED` |
| confirmingTime | int64 | On-chain transaction sync started time (milliseconds); returned when `bizStatus=PAY_CONFIRMING` |
| doneTime | int64 | On-chain transaction confirmed time (milliseconds); returned when `bizStatus=PAY_DONE` |

***

## Static Address Collection Notification

**bizType:** `PAY_FIXED_ADDRESS`
**bizStatus:** `PAY_SUCCESS` (credit succeeded)

### data Fields

| Field | Type | Required | Description |
| - | - | - | - |
| channel\_id | string | Yes | Channel identifier (snake\_case; legacy payloads may use `channelId`) |
| currency | string | Yes | Currency |
| orderAmount | string | No | Order amount |
| amount | string | Yes | Actual credited amount |
| createTime | number | Yes | Creation time (milliseconds) |
| transactionId | string | Yes | Platform transaction ID |
| transactionTime | number | Yes | Transaction time (milliseconds) |
| chain | string | Yes | Chain name |
| address | string | Yes | Collection address |

**Success Response:**

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

***

## Withdrawal / Payout Callbacks

For withdrawal and payout operations, see [Payout](/global/essentials/version/100/en/outflow/payout) for detailed callback structures and field descriptions.

**bizType:** `WITHDRAW`

### Main Order Fields

| Field | Required | Description |
| - | - | - |
| batch\_id | Yes | Batch ID |
| merchant\_id | Yes | Merchant ID |
| status | Yes | INIT / PROCESSING / PARTIAL / FAIL / SUCCESS |
| client\_id | Yes | client\_id used to create the batch |
| pay\_back\_status | Yes | Rollback status |
| channel\_id | Yes | Channel identifier |

### Sub-order Fields

| Field | Required | Description |
| - | - | - |
| suborder\_id | Yes | Sub-order ID |
| chain | Yes | Chain |
| address | Yes | Address |
| currency | Yes | Currency |
| amount | Yes | Amount |
| fee | Yes | Fee |
| txHash | Yes | Transaction hash |
| status | Yes | DONE / FAIL |
| merchant\_withdraw\_id | Yes | Merchant withdrawal ID |
| fee\_type | Yes | 0=internal deduction; 1=external deduction |
| finish\_time | Yes | Completion time |
| sub\_amount | Yes | Total sub-order amount |
| done\_amount | Yes | Actually completed amount |

***

## Institution API Callbacks

**bizType:** `INSTITUTION`
**bizStatus:** `INSTITUTION_ACCOUNT_SUCCESS` or `INSTITUTION_ACCOUNT_FAIL`

For institution account-related notifications, see [Institutional API](/global/essentials/version/100/en/internalflow/institution).

### data Fields (JSON string)

| Field | Description |
| - | - |
| request\_id | Request identifier |
| account\_id | Account ID |
| customer\_id | Customer ID |
| display\_name | Account display name |
| status | ACTIVE or FAIL |
| created | Timestamp in milliseconds |

***

## Callback Integration Guide

### Integration Requirements

| Item | Recommendation |
| - | - |
| **Endpoint** | Use a dedicated path such as `/webhook/gatepay` |
| **Protocol** | HTTPS with TLS 1.2+ |
| **Processing Strategy** | Verify signature → store idempotently → process business asynchronously → return SUCCESS |
| **Signature Verification** | Never return SUCCESS if signature verification fails |
| **data Parsing** | The `data` field is a JSON string and requires secondary parsing |
| **Duplicate Handling** | Support duplicate notifications using idempotent processing |

### Recommended Processing Flow

1. **Receive** the callback request
2. **Verify** the signature using the merchant secret key (see [Authentication and Security](/global/essentials/version/100/en/common/authentication))
3. **Extract** and parse the `data` field (JSON string → object)
4. **Check** idempotency key (e.g., transactionId or merchantTradeNo)
5. **Store** the notification durably before processing
6. **Process** the business logic asynchronously
7. **Return** `{"returnCode": "SUCCESS", "returnMessage": ""}` with HTTP 200

This design ensures reliability and prevents duplicate processing.

***

## Related Documentation

* [Authentication and Security](/global/essentials/version/100/en/common/authentication) — Signature verification and security practices
* [Payments](/global/essentials/version/100/en/inflow/payment/payment) — Payment callback details
* [Payout](/global/essentials/version/100/en/outflow/payout) — Payout callback details
* [Institutional API](/global/essentials/version/100/en/internalflow/institution) — Institution callback details

## Event Catalog Summary

## Processing Model

* Route processing by `bizType` first instead of assuming every callback shares the same field set
* Then evaluate `bizStatus` to determine whether the event is intermediate or terminal
* Finally apply idempotent updates keyed by business identifiers such as `merchantTradeNo`, `refundRequestId`, or `batch_id`

## Event Catalog

| bizType | bizStatus | Business Meaning | Terminal | Recommended Action |
| - | - | - | - | - |
| `PAY` | `PAY_SUCCESS` | Non-address payment succeeded | Yes | Mark the order successful and continue fulfillment |
| `PAY` | `PAY_ERROR` | Non-address payment failed | Yes | Mark the order failed and allow retry or manual handling |
| `PAY` | `PAY_CLOSE` | Order closed | Yes | End the flow and stop polling |
| `PAY_REFUND` | `REFUND_PROCESS` | Refund is processing | No | Mark refund as processing and continue waiting for callback or query |
| `PAY_REFUND` | `REFUND_SUCCESS` | Refund succeeded | Yes | Mark refund as complete and reconcile funds |
| `PAY_REFUND` | `REFUND_REJECTED` | Refund rejected | Yes | Mark refund failed and route to manual review |
| `PAY_ADDRESS` | `PAY_SUCCESS` | Address payment succeeded | Yes | Mark the order successful and persist chain-side payment details |
| `PAY_ADDRESS` | `PAY_EXPIRED_IN_PROCESS` | Target amount reached during validity period but on-chain records are still unconfirmed | No | Continue confirmation handling and avoid prematurely finalizing the order |
| `TRANSFER_ADDRESS` | `TRANSFERRED_ADDRESS_IN_TERM` | Funds credited within the valid period | Yes | Mark funds as credited |
| `TRANSFER_ADDRESS` | `TRANSFERRED_ADDRESS_DELAY` | Delayed credit | Yes | Mark delayed settlement and apply business-specific handling |
| `TRANSFER_ADDRESS` | `CONVERT_ADDRESS_PAY_DELAY` | Delayed convert-address payment notice | No | Continue handling together with query results and order mode |
| `CHAIN_ADDRESS` | `PAY_PASSED` | On-chain transaction compliance verification passed | No | Record the status during on-chain transaction and verification |
| `CHAIN_ADDRESS` | `PAY_CONFIRMING` | On-chain transaction sync started | No | Record the status during on-chain transaction and verification |
| `CHAIN_ADDRESS` | `PAY_DONE` | On-chain transaction confirmed | No | Record the status during on-chain transaction and verification |
| `PAY_FIXED_ADDRESS` | `PAY_SUCCESS` | Static-address collection succeeded | Yes | Mark the collection as credited |
| `WITHDRAW` | `WITHDRAW_SUCCESS` | Payout batch fully succeeded | Yes | Mark the batch successful and finalize reconciliation |
| `WITHDRAW` | `WITHDRAW_PARTIAL` | Payout batch partially succeeded | Yes | Split handling between successful and failed sub-orders |
| `WITHDRAW` | `WITHDRAW_FAIL` | Payout batch failed | Yes | Mark failed and route to retry or manual review |
| `INSTITUTION` | `INSTITUTION_ACCOUNT_SUCCESS` | Sub-account creation succeeded | Yes | Record successful account creation |
| `INSTITUTION` | `INSTITUTION_ACCOUNT_FAIL` | Sub-account creation failed | Yes | Record the failure and route for manual review |

## Terminal-State Handling Rules

For terminal events, it is best to advance downstream business only after all of the following are true:

1. the signature has been verified
2. idempotency validation has passed
3. the event has been persisted
4. the local business record is updated consistently with the callback result

## Related Reading

* [Notification](/global/essentials/version/100/en/common/notification)
* [Quickstart](/global/essentials/version/100/en/common/quickstart)
* [Payment](/global/essentials/version/100/en/inflow/payment/payment)
* [Payout](/global/essentials/version/100/en/outflow/payout)
* [OTC](/global/essentials/version/100/en/otc)


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