支付扣款通知

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

{
  "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 将按通知概览中的间隔重试
扣款单详情可结合扣款订单详情做兜底查询

消息结构

字段名	类型	说明
`bizType`	string	`SUBSCRIPTION_PAYMENT` 或 `ACCOUNT_AUTH_DEDUCTION`
`bizId`	string	扣款单 ID（`SUBSCRIPTION_PAYMENT` 时通常为 `paymentOrderNo`）
`bizStatus`	string	见下表
`data`	string	扣款明细 JSON 字符串，字段因 `bizType` 而异

bizStatus 说明

bizType	bizStatus	说明
`SUBSCRIPTION_PAYMENT`	`SUCCESS`	订阅扣款成功
`SUBSCRIPTION_PAYMENT`	`BLOCKED`	订阅扣款阻塞
`ACCOUNT_AUTH_DEDUCTION`	`DEDUCT_SUCCESS`	授权中心化账户授权扣款成功
`ACCOUNT_AUTH_DEDUCTION`	`DEDUCT_FAILED`	授权中心化账户授权扣款失败
`ACCOUNT_AUTH_DEDUCTION`	`SUCCESS`	授权 Web3 扣款成功
`ACCOUNT_AUTH_DEDUCTION`	`BLOCKED`	授权 Web3 扣款阻塞
`ACCOUNT_AUTH_DEDUCTION`	`FAILED`	授权 Web3 扣款失败
`ACCOUNT_AUTH_DEDUCTION`	`DEDUCT_FAILED_REQUIRES_ACTION`	授权中心化扣除待验证

data 字段说明（`bizType=SUBSCRIPTION_PAYMENT`）

字段名	类型	说明
`subscriptionOrderNo`	string	订阅订单编号
`merchantSubscriptionOrderNo`	string	商户订阅订单编号
`planNo`	string	订阅计划编号
`paymentOrderNo`	string	本次扣款订单号
`merchantId`	string	商户编号
`cryptoCurrency`	string	加密货币币种
`chain`	string	加密货币网络
`cryptoAmount`	string	单次扣款金额
`userAddress`	string	用户授权地址
`authorizedAddress`	string	用户授权地址（与 `userAddress` 同义，以实际返回为准）
`merchantAddress`	string	平台接收扣款的地址
`txHash`	string	链上交易 Hash
`payStatus`	string	扣款状态：`SUCCESS` / `FAILED`
`payTime`	int64	扣款时间（毫秒）
`paymentChannel`	string	支付渠道，Web3 场景通常为 `WEB3`、GatePay 场景为 `GATEPAY`、法币场景为 `FIAT`

data 字段说明（`bizType=ACCOUNT_AUTH_DEDUCTION`）

字段名	类型	说明
`subscriptionOrderNo`	string	订阅订单编号
`merchantSubscriptionOrderNo`	string	商户订阅订单编号
`merchantId`	string	商户编号
`deductOrderNo`	string	平台扣款单号
`merchantDeductNo`	string	商户扣款单号
`currency`	string	扣款币种
`amount`	number	本次扣款金额
`totalDeducted`	number	累计已扣款金额
`remainingAmount`	number	剩余可扣款额度
`deductStatus`	string	扣款状态：`SUCCESS` / `FAILED`
`deductTime`	int64	扣款时间（毫秒）
`paymentChannel`	string	支付渠道，Web3 场景通常为 `WEB3`、GatePay 场景为 `GATEPAY`、法币场景为 `FIAT`

回调示例

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

成功/阻塞时为 SUCCESS/BLOCKED；ACCOUNT_AUTH_DEDUCTION 中心化成功/失败时为 DEDUCT_SUCCESS / DEDUCT_FAILED， Web3 成功/阻塞/失败为 SUCCESS / BLOCKED/ FAILED。

data

string

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

bizId

string

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

响应

200 - application/json

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

returnCode

string

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

returnMessage

string

响应描述，成功时为空

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

概述

说明

触发情形

消息结构

bizStatus 说明

data 字段说明（`bizType=SUBSCRIPTION_PAYMENT`）

data 字段说明（`bizType=ACCOUNT_AUTH_DEDUCTION`）

回调示例

Web3 扣款成功（`bizType=SUBSCRIPTION_PAYMENT`）

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

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

请求体

响应

​概述

​说明

​触发情形

​消息结构

​bizStatus 说明

​data 字段说明（bizType=SUBSCRIPTION_PAYMENT）

​data 字段说明（bizType=ACCOUNT_AUTH_DEDUCTION）

​回调示例

​Web3 扣款成功（bizType=SUBSCRIPTION_PAYMENT）

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

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

请求体

响应

概述

说明

触发情形

消息结构

bizStatus 说明

data 字段说明（`bizType=SUBSCRIPTION_PAYMENT`）

data 字段说明（`bizType=ACCOUNT_AUTH_DEDUCTION`）

回调示例

Web3 扣款成功（`bizType=SUBSCRIPTION_PAYMENT`）

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

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