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

> Callback when a subscription deduction attempt completes (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](/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/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](/api-reference/version/100/en/common/asyncNotification)
* Use [Deduction order detail](/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}"
}
```


## OpenAPI

````yaml /api-reference/version/100/en/openapi/subscription/paymentNotify-openapi.json webhook subscriptionOrderPaymentWebhook
openapi: 3.1.0
info:
  title: GatePay API
  version: 1.0.0
  description: GatePay Payment Platform API Documentation
servers: []
security: []
paths: {}

````