> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 支付扣款通知

> Callback when a subscription deduction attempt completes (payment / deduction notification).

## 概述

本页说明 `webhook subscriptionOrderPaymentNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

订阅周期扣款完成后，GatePay 向商户配置的 callback URL 发送异步通知。根据支付渠道不同，`bizType` 可能为 `SUBSCRIPTION_PAYMENT`（Web3 链上扣款）或 `ACCOUNT_AUTH_DEDUCTION`（Gate 账户授权扣款）。

## 说明

* 建议基于 `bizId`、`paymentOrderNo` 或 `deductOrderNo` 做幂等处理。
* 验签、重试、`data` 解析与成功应答见 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/global/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

* 订阅周期扣款完成（成功或失败）后，GatePay 向商户配置的 **callback URL** 发送通知
* 若通知投递失败，GatePay 将按 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试
* 扣款单详情可结合 [扣款订单详情](/global/api-reference/version/100/cn/endpoint/subscription/deductionOrderDetail) 做兜底查询

## 消息结构

| 字段名 | 类型 | 说明 |
| - | - | - |
| `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`）

```json theme={null}
{
  "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`）

```json theme={null}
{
  "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`）

```json theme={null}
{
  "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}"
}
```


## OpenAPI

````yaml global/api-reference/version/100/cn/openapi/subscription/paymentNotify-openapi.json webhook subscriptionOrderPaymentNotify
openapi: 3.1.0
info:
  title: GatePay 订阅 API
  version: 1.0.0
  description: 订阅业务相关 Webhook 定义。
servers: []
security: []
paths: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.