跳转到主要内容

​
处理要求

对于每一笔收到的回调，你都必须：
  1. Verify the signature first — See 认证与安全 for signature verification details
  2. 解析业务数据 并进行幂等处理
  3. 返回约定的成功响应
由于同一业务事件可能被重复投递，因此你必须基于业务唯一标识实现幂等处理。

​
触发与重试机制

Trigger 当订单状态发生变化（如支付成功、超时、取消、关闭或异常）时，GatePay 会向你配置的回调地址发送通知。 Retry 如果你未返回约定的成功响应，或请求超时，GatePay 会按规则重试回调。 Signature Verification You must verify all 回调 signatures before processing. See 认证与安全 for details.

​
回调 Message Structure

All 回调 contain the following top-level fields:
字段类型说明
biz类型string通知 category (see biz类型 Enumeration)
bizIdstringOrder ID or business ID
biz状态stringBusiness status (varies by biz类型)
client_idstring商户 client_id
datastringBusiness payload as a JSON string; structure varies by biz类型
Example 回调: 
{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cdhu-fgrfg44-5ggd-cdvsa",
  "data": "{\"merchantTradeNo\":\"M202603120001\",\"orderAmount\":\"100.00\"}"
}

​
回调 Acknowledgement 响应

Return the following JSON response with HTTP 200: 
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
HTTP 200 status is recommended to indicate successful receipt.

​
biz类型 Enumeration

Value说明
PAY状态 change for non-address payment 订单s
PAY_REFUND状态 change for re资金 订单s
PAY_BATCH状态 change for batch reward 订单s
PAY_GIFT_BATCH状态 change for batch gift-card payments
PAY_ADDRESS状态 change for address payment 订单s
TRANSFER_ADDRESSFunds-flow 通知 for address payments
PAY_FIXED_ADDRESSStatic-address collection 通知
WITHDRAWWithdrawal / 出款 status change
INSTITUTION机构 API account-related 通知

​
托管收银台 Payment 通知

Hosted checkout payments follow the general PAY 回调 model. For non-address payments, interpret the payment amount using orderAmount. For more details on payment integrations, see 支付.

​
Address Payment 通知

​
PAY_ADDRESS 状态 Enumeration

状态Applicable Mode说明
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 字段

字段Applicable Mode说明
商户TradeNoNon-convert / Convert商户 订单 number
product类型Non-convert / ConvertProduct type
productNameNon-convert / ConvertProduct name
goodsNameNon-convert / ConvertGoods name
trade类型Non-convert / ConvertTransaction type
terminal类型Non-convert / ConvertTerminal type
currencyNon-convert / ConvertPricing currency
订单AmountNon-convert / ConvertOrder amount
payerIdNon-convert / ConvertPayer identifier
createTimeNon-convert / ConvertCreation time
交易IdNon-convert / ConvertPlatform 交易 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 / Convert收款 address
fromAddressNon-convert / ConvertPayer address
pay币种ConvertPayment currency used for conversion
payAmountConvertPayment amount used for conversion
rateConvertExchange rate
overPayConvertOverpayment amount

​
TRANSFER_ADDRESS 状态 Enumeration

状态说明
TRANSFERRED_ADDRESS_IN_TERMCredited within the validity period
TRANSFERRED_ADDRESS_DELAYCredited after the validity period
CONVERT_ADDRESS_PAY_DELAYConvert delayed-payment 通知 only; no credit
TRANSFERRED_ADDRESS_BLOCKRisk-controlled 资金; not credited

​
TRANSFER_ADDRESS data 字段

字段说明
商户TradeNo商户 订单 number
currency币种
订单AmountOrder amount
createTimeCreation time
交易IdPlatform 交易 ID
transferAmountOn-chain transfer amount
txHashBlockchain 交易 hash
chainChain name
addressAddress
channelIdChannel identifier

​
Static Address 收款 通知

biz类型: PAY_FIXED_ADDRESS biz状态: PAY_SUCCESS (credit succeeded) or PAY_BLOCK (risk 资金, not credited)

​
data 字段

字段类型必填说明
channelIdstringYesChannel identifier
currencystringYes币种
订单AmountstringNoOrder amount
amountstringYesActual credited amount
createTimenumberYesCreation time (milliseconds)
交易IdstringYesPlatform 交易 ID
交易TimenumberYesTransaction time (milliseconds)
chainstringYesChain name
addressstringYes收款 address
Success 响应: 
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

​
Withdrawal / 出款 回调

For 提现 and 出款 operations, see 出款 for detailed 回调 structures and field descriptions. biz类型: WITHDRAW

​
Main Order 字段

字段必填说明
batch_idYesBatch ID
商户_idYes商户 ID
statusYesINIT / PROCESSING / PARTIAL / FAIL / SUCCESS
client_idYesclient_id used to create the batch
pay_back_statusYesRollback status
channel_idYesChannel identifier

​
Sub-订单 字段

字段必填说明
sub订单_idYesSub-订单 ID
chainYesChain
addressYesAddress
currencyYes币种
amountYesAmount
feeYesFee
txHashYesTransaction hash
statusYesDONE / FAIL
商户_withdraw_idYes商户 提现 ID
fee_typeYes0=internal deduction; 1=external deduction
finish_timeYesCompletion time
sub_amountYesTotal sub-订单 amount
done_amountYesActually completed amount

​
机构 API 回调

biz类型: INSTITUTION biz状态: INSTITUTION_ACCOUNT_SUCCESS or INSTITUTION_ACCOUNT_FAIL For institution account-related 通知, see Institutional API.

​
data 字段 (JSON string)

字段说明
request_id请求 identifier
account_idAccount ID
customer_idCustomer ID
display_nameAccount display name
statusACTIVE or FAIL
createdTimestamp in milliseconds

​
回调 Integration Guide

​
Integration Requirements

ItemRecommendation
接口Use a dedicated path such as /webhook/gatepay
ProtocolHTTPS with TLS 1.2+
Processing StrategyVerify signature → store idempotently → process business 异步ly → return SUCCESS
Signature VerificationNever return SUCCESS if signature verification fails
data ParsingThe data field is a JSON string and requires secondary parsing
Duplicate 处理方式Support duplicate 通知 using idempotent processing
  1. Receive the 回调 request
  2. Verify the signature using the 商户 secret key (see 认证与安全)
  3. Extract and parse the data field (JSON string → object)
  4. Check 幂等性 key (e.g., 交易Id or 商户TradeNo)
  5. Store the 通知 durably before processing
  6. Process the business logic 异步ly
  7. Return {"returnCode": "SUCCESS", "returnMessage": ""} with HTTP 200
This design ensures reliability and prevents duplicate processing.