Notification - Gate Pay DOCS

Processing Requirements

For every callback received, you must:

Verify the signature first — See Authentication and Security for signature verification details
Parse the business data and perform idempotent processing
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:

Validate headers and verify the signature
Parse bizType, bizId, and bizStatus
Run idempotency checks on the business-unique identifier
Update local business state
Return the success response
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 for details.

Callback Message Structure

All callbacks contain the following top-level fields:

Field	Type	Description
bizType	string	Notification category (see 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:

{
  "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:

{
  "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.

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:

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

Withdrawal / Payout Callbacks

For withdrawal and payout operations, see 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.

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

Receive the callback request
Verify the signature using the merchant secret key (see Authentication and Security)
Extract and parse the data field (JSON string → object)
Check idempotency key (e.g., transactionId or merchantTradeNo)
Store the notification durably before processing
Process the business logic asynchronously
Return {"returnCode": "SUCCESS", "returnMessage": ""} with HTTP 200

This design ensures reliability and prevents duplicate processing.

Authentication and Security — Signature verification and security practices
Payments — Payment callback details
Payout — Payout callback details
Institutional API — 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:

the signature has been verified
idempotency validation has passed
the event has been persisted
the local business record is updated consistently with the callback result

​Processing Requirements

​Recommended Processing Order

​Trigger and Retry Mechanism

​Callback Message Structure

​Callback Acknowledgement Response

​bizType Enumeration

​General Notes

​Payment Product to bizType Mapping

​Hosted Checkout Payment Notification

​Refund Notifications

​Address Payment Notifications

​PAY_ADDRESS Status Enumeration

​PAY_ADDRESS data Fields

​TRANSFER_ADDRESS Status Enumeration

​TRANSFER_ADDRESS data Fields

​CHAIN_ADDRESS Status Enumeration

​CHAIN_ADDRESS data Fields

​Static Address Collection Notification

​data Fields

​Withdrawal / Payout Callbacks

​Main Order Fields

​Sub-order Fields

​Institution API Callbacks

​data Fields (JSON string)

​Callback Integration Guide

​Integration Requirements

​Recommended Processing Flow

​Related Documentation

​Event Catalog Summary

​Processing Model

​Event Catalog

​Terminal-State Handling Rules

​Related Reading