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

# Payment Deduction Notification

## Overview

This page documents `webhook subscriptionOrderPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above.

After a subscription billing cycle completes, GatePay sends an asynchronous notification to the merchant-configured callback URL. Depending on the payment channel, `bizType` may be `SUBSCRIPTION_PAYMENT` (Web3 on-chain deduction) or `ACCOUNT_AUTH_DEDUCTION` (Gate account authorized deduction).

## Notes

* Use `bizId`, `paymentOrderNo`, or `deductOrderNo` for idempotency after parsing `data`.
* Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules.

## When notifications are sent

* GatePay sends a notification after each subscription billing cycle completes (success or failure)
* If delivery fails, GatePay retries according to [Notifications overview](/global/api-reference/version/100/en/common/asyncNotification)
* Use [Deduction order detail](/global/api-reference/version/100/en/endpoint/subscription/deductionOrderDetail) as a query fallback when needed

## Message structure

| Field | Type | Description |
| - | - | - |
| `bizType` | string | `SUBSCRIPTION_PAYMENT` or `ACCOUNT_AUTH_DEDUCTION` |
| `bizId` | string | Deduction order ID (for `SUBSCRIPTION_PAYMENT`, usually `paymentOrderNo`) |
| `bizStatus` | string | See table below |
| `data` | string | Deduction details as a JSON string; fields vary by `bizType` |

### bizStatus values

| bizType | bizStatus | Description |
| - | - | - |
| `SUBSCRIPTION_PAYMENT` | `SUCCESS` | Web3 on-chain deduction succeeded |
| `ACCOUNT_AUTH_DEDUCTION` | `DEDUCT_SUCCESS` | Gate account authorized deduction succeeded |
| `ACCOUNT_AUTH_DEDUCTION` | `DEDUCT_FAILED` | Gate account authorized deduction failed |

## data fields (`bizType=SUBSCRIPTION_PAYMENT`)

| Field | Type | Description |
| - | - | - |
| `subscriptionOrderNo` | string | Subscription order number |
| `merchantSubscriptionOrderNo` | string | Merchant subscription order number |
| `planNo` | string | Subscription plan number |
| `paymentOrderNo` | string | Deduction order number for this cycle |
| `merchantId` | string | Merchant ID |
| `cryptoCurrency` | string | Cryptocurrency |
| `chain` | string | Blockchain network |
| `cryptoAmount` | string | Single deduction amount |
| `userAddress` | string | User authorized address |
| `authorizedAddress` | string | User authorized address (same as `userAddress` in some payloads) |
| `merchantAddress` | string | Platform address that receives the deduction |
| `txHash` | string | On-chain transaction hash |
| `payStatus` | string | Deduction status: `SUCCESS` / `FAILED` |
| `payTime` | int64 | Deduction time in ms |
| `paymentChannel` | string | Payment channel; Web3 scenarios typically use `WEB3` |

## data fields (`bizType=ACCOUNT_AUTH_DEDUCTION`)

| Field | Type | Description |
| - | - | - |
| `subscriptionOrderNo` | string | Subscription order number |
| `merchantSubscriptionOrderNo` | string | Merchant subscription order number |
| `merchantId` | string | Merchant ID |
| `deductOrderNo` | string | Platform deduction order number |
| `merchantDeductNo` | string | Merchant deduction order number |
| `currency` | string | Deduction currency |
| `amount` | number | Amount deducted in this cycle |
| `totalDeducted` | number | Cumulative deducted amount |
| `remainingAmount` | number | Remaining authorized balance |
| `deductStatus` | string | Deduction status: `SUCCESS` / `FAILED` |
| `deductTime` | int64 | Deduction time in ms |
| `paymentChannel` | string | Payment channel; authorized deduction typically uses `GATEPAY` |

## Callback examples

### Web3 deduction success (`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\"}"
}
```

### Authorized payment deduction success (`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}"
}
```

### Authorized payment deduction failed (`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}"
}
```


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