Skip to main content

​
Processing Requirements

For every callback received, you must:
  1. Verify the signature first — See Authentication and Security 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.

​
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:
FieldTypeDescription
bizTypestringNotification category (see bizType Enumeration)
bizIdstringOrder ID or business ID
bizStatusstringBusiness status (varies by bizType)
client_idstringMerchant client_id
datastringBusiness payload as a JSON string; structure varies by bizType
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

ValueDescription
PAYStatus change for non-address payment orders
PAY_REFUNDStatus change for refund orders
PAY_BATCHStatus change for batch reward orders
PAY_GIFT_BATCHStatus change for batch gift-card payments
PAY_ADDRESSStatus change for address payment orders
TRANSFER_ADDRESSFunds-flow notification for address payments
PAY_FIXED_ADDRESSStatic-address collection notification
WITHDRAWWithdrawal / payout status change
INSTITUTIONInstitution API account-related notification

​
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.

​
Address Payment Notifications

​
PAY_ADDRESS Status Enumeration

StatusApplicable ModeDescription
PAY_SUCCESSNon-convert / ConvertPayment succeeded
PAY_ERRORNon-convert / ConvertPayment failed
PAY_CLOSENon-convert / ConvertOrder closed
PAY_EXPIRED_IN_PROCESSNon-convert / ConvertTarget amount reached within validity period, but still unconfirmed on-chain records
PENDINGConvertPending
PROCESSConvertProcessing
PAIDConvertPaid
EXPIREDConvertExpired

​
PAY_ADDRESS data Fields

FieldApplicable ModeDescription
merchantTradeNoNon-convert / ConvertMerchant order number
productTypeNon-convert / ConvertProduct type
productNameNon-convert / ConvertProduct name
goodsNameNon-convert / ConvertGoods name
tradeTypeNon-convert / ConvertTransaction type
terminalTypeNon-convert / ConvertTerminal type
currencyNon-convert / ConvertPricing currency
orderAmountNon-convert / ConvertOrder amount
payerIdNon-convert / ConvertPayer identifier
createTimeNon-convert / ConvertCreation time
transactionIdNon-convert / ConvertPlatform transaction ID
waitAmountOnChainNon-convert / ConvertOn-chain amount detected but not yet finally credited
doneAmountOnChainNon-convert / ConvertOn-chain amount already confirmed and credited
channelIdNon-convert / ConvertChannel identifier
chainNon-convert / ConvertChain name
addressNon-convert / ConvertCollection address
fromAddressNon-convert / ConvertPayer address
payCurrencyConvertPayment currency used for conversion
payAmountConvertPayment amount used for conversion
rateConvertExchange rate
overPayConvertOverpayment amount

​
TRANSFER_ADDRESS Status Enumeration

StatusDescription
TRANSFERRED_ADDRESS_IN_TERMCredited within the validity period
TRANSFERRED_ADDRESS_DELAYCredited after the validity period
CONVERT_ADDRESS_PAY_DELAYConvert delayed-payment notification only; no credit
TRANSFERRED_ADDRESS_BLOCKRisk-controlled funds; not credited

​
TRANSFER_ADDRESS data Fields

FieldDescription
merchantTradeNoMerchant order number
currencyCurrency
orderAmountOrder amount
createTimeCreation time
transactionIdPlatform transaction ID
transferAmountOn-chain transfer amount
txHashBlockchain transaction hash
chainChain name
addressAddress
channelIdChannel identifier

​
Static Address Collection Notification

bizType: PAY_FIXED_ADDRESS bizStatus: PAY_SUCCESS (credit succeeded) or PAY_BLOCK (risk funds, not credited)

​
data Fields

FieldTypeRequiredDescription
channelIdstringYesChannel identifier
currencystringYesCurrency
orderAmountstringNoOrder amount
amountstringYesActual credited amount
createTimenumberYesCreation time (milliseconds)
transactionIdstringYesPlatform transaction ID
transactionTimenumberYesTransaction time (milliseconds)
chainstringYesChain name
addressstringYesCollection address
Success Response: 
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

​
Withdrawal / Payout Callbacks

For withdrawal and payout operations, see Payouts for detailed callback structures and field descriptions. bizType: WITHDRAW

​
Main Order Fields

FieldRequiredDescription
batch_idYesBatch ID
merchant_idYesMerchant ID
statusYesINIT / PROCESSING / PARTIAL / FAIL / SUCCESS
client_idYesclient_id used to create the batch
pay_back_statusYesRollback status
channel_idYesChannel identifier

​
Sub-order Fields

FieldRequiredDescription
suborder_idYesSub-order ID
chainYesChain
addressYesAddress
currencyYesCurrency
amountYesAmount
feeYesFee
txHashYesTransaction hash
statusYesDONE / FAIL
merchant_withdraw_idYesMerchant withdrawal ID
fee_typeYes0=internal deduction; 1=external deduction
finish_timeYesCompletion time
sub_amountYesTotal sub-order amount
done_amountYesActually 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)

FieldDescription
request_idRequest identifier
account_idAccount ID
customer_idCustomer ID
display_nameAccount display name
statusACTIVE or FAIL
createdTimestamp in milliseconds

​
Callback Integration Guide

​
Integration Requirements

ItemRecommendation
EndpointUse a dedicated path such as /webhook/gatepay
ProtocolHTTPS with TLS 1.2+
Processing StrategyVerify signature → store idempotently → process business asynchronously → return SUCCESS
Signature VerificationNever return SUCCESS if signature verification fails
data ParsingThe data field is a JSON string and requires secondary parsing
Duplicate HandlingSupport duplicate notifications using idempotent processing
  1. Receive the callback request
  2. Verify the signature using the merchant secret key (see Authentication and Security)
  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.