> ## 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](/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](/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 | | 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 | | 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](/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 | | 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 | | TRANSFERRED\_ADDRESS\_BLOCK | Risk-controlled funds; not credited | ### TRANSFER\_ADDRESS data Fields | Field | Description | | --------------- | --------------------------- | | merchantTradeNo | Merchant order number | | 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. *** ## Static Address Collection Notification **bizType:** `PAY_FIXED_ADDRESS` **bizStatus:** `PAY_SUCCESS` (credit succeeded) or `PAY_BLOCK` (risk funds, not credited) ### 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](/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](/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](/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](/essentials/version/100/en/common/authentication) — Signature verification and security practices * [Payments](/essentials/version/100/en/inflow/payment/payment) — Payment callback details * [Payout](/essentials/version/100/en/outflow/payout) — Payout callback details * [Institutional API](/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 | | `TRANSFER_ADDRESS` | `TRANSFERRED_ADDRESS_BLOCK` | Risk-controlled funds | Yes | Mark the order as exceptional and route to manual review | | `PAY_FIXED_ADDRESS` | `PAY_SUCCESS` | Static-address collection succeeded | Yes | Mark the collection as credited | | `PAY_FIXED_ADDRESS` | `PAY_BLOCK` | Static-address risk-controlled funds | Yes | Mark the event exceptional and route to manual review | | `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](/essentials/version/100/en/common/notification) * [Quickstart](/essentials/version/100/en/common/quickstart) * [Payment](/essentials/version/100/en/inflow/payment/payment) * [Payout](/essentials/version/100/en/outflow/payout) * [OTC](/essentials/version/100/en/otc)