Payment Deduction Notification

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

subscriptionOrderPaymentWebhook

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

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; see Security and Signature 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
Use Deduction order detail 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`)

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

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

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

Body

application/json

Subscription order deduction notification parameters POST method

bizType

string

Business type: SUBSCRIPTION_PAYMENT — subscription payment deduction notification; ACCOUNT_AUTH_DEDUCTION — authorized payment deduction notification.

bizStatus

string

Business status: SUCCESS for successful SUBSCRIPTION_PAYMENT; DEDUCT_SUCCESS / DEDUCT_FAILED for ACCOUNT_AUTH_DEDUCTION.

data

string

Deduction details as a JSON string; fields vary by bizType.

bizId

string

Deduction order ID (for SUBSCRIPTION_PAYMENT, usually paymentOrderNo).

Response

200 - application/json

Return HTTP 200 to indicate callback notification has been received.

returnCode

string

Response code, SUCCESS indicates success, FAIL indicates failure

returnMessage

string

Response description, empty when successful

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Payment Deduction Notification

Overview

Notes

When notifications are sent

Message structure

bizStatus values

data fields (`bizType=SUBSCRIPTION_PAYMENT`)

data fields (`bizType=ACCOUNT_AUTH_DEDUCTION`)

Callback examples

Web3 deduction success (`bizType=SUBSCRIPTION_PAYMENT`)

Authorized payment deduction success (`bizType=ACCOUNT_AUTH_DEDUCTION`)

Authorized payment deduction failed (`bizType=ACCOUNT_AUTH_DEDUCTION`)

Body

Response

​Overview

​Notes

​When notifications are sent

​Message structure

​bizStatus values

​data fields (bizType=SUBSCRIPTION_PAYMENT)

​data fields (bizType=ACCOUNT_AUTH_DEDUCTION)

​Callback examples

​Web3 deduction success (bizType=SUBSCRIPTION_PAYMENT)

​Authorized payment deduction success (bizType=ACCOUNT_AUTH_DEDUCTION)

​Authorized payment deduction failed (bizType=ACCOUNT_AUTH_DEDUCTION)

Body

Response

Overview

Notes

When notifications are sent

Message structure

bizStatus values

data fields (`bizType=SUBSCRIPTION_PAYMENT`)

data fields (`bizType=ACCOUNT_AUTH_DEDUCTION`)

Callback examples

Web3 deduction success (`bizType=SUBSCRIPTION_PAYMENT`)

Authorized payment deduction success (`bizType=ACCOUNT_AUTH_DEDUCTION`)

Authorized payment deduction failed (`bizType=ACCOUNT_AUTH_DEDUCTION`)