Notifications Overview

​

Reading path

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 — event catalog, terminal-state handling, and product-to-bizType mapping
4. Best practices — payment query fallback, 10s refund rule, and security guidance

​

Overview

• 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.
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). 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

​

Message JSON example

{
  "bizType": "PAY",
  "bizId": "order_123456",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "your_client_id",
  "data": "{...}"
}

​

bizType

​

Terminal states at a glance

​

bizStatus enum (payment / address)