跳转到主要内容
WEBHOOK
subscriptionOrderPaymentNotify
{ "bizType": "SUBSCRIPTION_PAYMENT", "bizId": "84670588016525429", "bizStatus": "SUCCESS", "data": "{\"authorizedAddress\":\"0x6ae9fb5258fb35d681f087dc343caf9d6e3d2cdc\",\"chain\":\"ARBEVM\",\"cryptoAmount\":\"0.1\",\"cryptoCurrency\":\"USDT\",\"merchantAddress\":\"0x26fd0b0898E235B996F8cBf184e97f6F8cd40676\",\"merchantId\":\"1627288\",\"merchantSubscriptionOrderNo\":\"2701761230\",\"payStatus\":\"SUCCESS\",\"payTime\":1776754665363,\"paymentChannel\":\"WEB3\",\"paymentOrderNo\":\"84670588016525429\",\"planNo\":\"84670588016525317\",\"subscriptionOrderNo\":\"84670588016525427\",\"txHash\":\"0xf82e60be5a922620e26a0e677a9b57a0daa527f0927940bde37bc4d9b57900c4\",\"userAddress\":\"0x20C58Cdf410Ac436D8c60c5163C47B7A5D91C91f\"}" }
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

​
概述

本页说明 webhook subscriptionOrderPaymentNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 订阅周期扣款完成后，GatePay 向商户配置的 callback URL 发送异步通知。根据支付渠道不同，bizType 可能为 SUBSCRIPTION_PAYMENT（Web3 链上扣款）或 ACCOUNT_AUTH_DEDUCTION（Gate 账户授权扣款）。

​
说明

  • 建议基于 bizId、paymentOrderNo 或 deductOrderNo 做幂等处理。
  • 验签、重试、data 解析与成功应答见 通知概览；签名规则见 安全与签名。

​
触发情形

  • 订阅周期扣款完成（成功或失败）后，GatePay 向商户配置的 callback URL 发送通知
  • 若通知投递失败，GatePay 将按 通知概览 中的间隔重试
  • 扣款单详情可结合 扣款订单详情 做兜底查询

​
消息结构

字段名类型说明
bizTypestringSUBSCRIPTION_PAYMENT 或 ACCOUNT_AUTH_DEDUCTION
bizIdstring扣款单 ID（SUBSCRIPTION_PAYMENT 时通常为 paymentOrderNo）
bizStatusstring见下表
datastring扣款明细 JSON 字符串，字段因 bizType 而异

​
bizStatus 说明

bizTypebizStatus说明
SUBSCRIPTION_PAYMENTSUCCESSWeb3 链上扣款成功
ACCOUNT_AUTH_DEDUCTIONDEDUCT_SUCCESSGate 账户授权扣款成功
ACCOUNT_AUTH_DEDUCTIONDEDUCT_FAILEDGate 账户授权扣款失败

​
data 字段说明（bizType=SUBSCRIPTION_PAYMENT）

字段名类型说明
subscriptionOrderNostring订阅订单编号
merchantSubscriptionOrderNostring商户订阅订单编号
planNostring订阅计划编号
paymentOrderNostring本次扣款订单号
merchantIdstring商户编号
cryptoCurrencystring加密货币币种
chainstring加密货币网络
cryptoAmountstring单次扣款金额
userAddressstring用户授权地址
authorizedAddressstring用户授权地址（与 userAddress 同义，以实际返回为准）
merchantAddressstring平台接收扣款的地址
txHashstring链上交易 Hash
payStatusstring扣款状态：SUCCESS / FAILED
payTimeint64扣款时间（毫秒）
paymentChannelstring支付渠道，Web3 场景通常为 WEB3

​
data 字段说明（bizType=ACCOUNT_AUTH_DEDUCTION）

字段名类型说明
subscriptionOrderNostring订阅订单编号
merchantSubscriptionOrderNostring商户订阅订单编号
merchantIdstring商户编号
deductOrderNostring平台扣款单号
merchantDeductNostring商户扣款单号
currencystring扣款币种
amountnumber本次扣款金额
totalDeductednumber累计已扣款金额
remainingAmountnumber剩余可扣款额度
deductStatusstring扣款状态：SUCCESS / FAILED
deductTimeint64扣款时间（毫秒）
paymentChannelstring支付渠道，授权扣款场景通常为 GATEPAY

​
回调示例

​
Web3 扣款成功（bizType=SUBSCRIPTION_PAYMENT）

{
  "bizType": "SUBSCRIPTION_PAYMENT",
  "bizId": "84670588016525429",
  "bizStatus": "SUCCESS",
  "data": "{\"authorizedAddress\":\"0x6ae9fb5258fb35d681f087dc343caf9d6e3d2cdc\",\"chain\":\"ARBEVM\",\"cryptoAmount\":\"0.1\",\"cryptoCurrency\":\"USDT\",\"merchantAddress\":\"0x26fd0b0898E235B996F8cBf184e97f6F8cd40676\",\"merchantId\":\"1627288\",\"merchantSubscriptionOrderNo\":\"2701761230\",\"payStatus\":\"SUCCESS\",\"payTime\":1776754665363,\"paymentChannel\":\"WEB3\",\"paymentOrderNo\":\"84670588016525429\",\"planNo\":\"84670588016525317\",\"subscriptionOrderNo\":\"84670588016525427\",\"txHash\":\"0xf82e60be5a922620e26a0e677a9b57a0daa527f0927940bde37bc4d9b57900c4\",\"userAddress\":\"0x20C58Cdf410Ac436D8c60c5163C47B7A5D91C91f\"}"
}

​
授权支付扣款成功（bizType=ACCOUNT_AUTH_DEDUCTION）

{
  "bizType": "ACCOUNT_AUTH_DEDUCTION",
  "bizId": "79411443511329070",
  "bizStatus": "DEDUCT_SUCCESS",
  "data": "{\"amount\":0.079105,\"currency\":\"USDT\",\"deductOrderNo\":\"79547802280788015\",\"deductStatus\":\"SUCCESS\",\"deductTime\":1780017431027,\"merchantDeductNo\":\"8065258f169b683f5d742c06ac1ca547-f367d789274fa47e\",\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1776078867177_2039617990602551296\",\"paymentChannel\":\"GATEPAY\",\"remainingAmount\":196.830553,\"subscriptionOrderNo\":\"79411443511329070\",\"totalDeducted\":3.169447}"
}

​
授权支付扣款失败（bizType=ACCOUNT_AUTH_DEDUCTION）

{
  "bizType": "ACCOUNT_AUTH_DEDUCTION",
  "bizId": "79411443511329070",
  "bizStatus": "DEDUCT_FAILED",
  "data": "{\"amount\":0.079105,\"currency\":\"USDT\",\"deductOrderNo\":\"79547802280788016\",\"deductStatus\":\"FAILED\",\"deductTime\":1780017431027,\"merchantDeductNo\":\"8065258f169b683f5d742c06ac1ca547-f367d789274fa47e\",\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1776078867177_2039617990602551296\",\"paymentChannel\":\"GATEPAY\",\"remainingAmount\":196.830553,\"subscriptionOrderNo\":\"79411443511329070\",\"totalDeducted\":3.169447}"
}

请求体

application/json

订阅扣款通知入参 POST方式

​
bizType
string

业务类型：SUBSCRIPTION_PAYMENT 订阅支付扣款通知；ACCOUNT_AUTH_DEDUCTION 授权支付扣款通知。

​
bizStatus
string

业务状态：SUBSCRIPTION_PAYMENT 成功时为 SUCCESS；ACCOUNT_AUTH_DEDUCTION 成功/失败时为 DEDUCT_SUCCESS / DEDUCT_FAILED。

​
data
string

扣款明细 JSON 字符串，字段因 bizType 不同而异。

​
bizId
string

扣款单 ID（SUBSCRIPTION_PAYMENT 时通常为 paymentOrderNo）。

响应

200 - application/json

返回 HTTP 200 表示已收到回调通知。

​
returnCode
string

响应码，SUCCESS表示成功 FAIL标识失败

​
returnMessage
string

响应描述，成功时为空