Skip to main content
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

FieldTypeDescription
bizTypestringSUBSCRIPTION_PAYMENT or ACCOUNT_AUTH_DEDUCTION
bizIdstringDeduction order ID (for SUBSCRIPTION_PAYMENT, usually paymentOrderNo)
bizStatusstringSee table below
datastringDeduction details as a JSON string; fields vary by bizType

​
bizStatus values

bizTypebizStatusDescription
SUBSCRIPTION_PAYMENTSUCCESSWeb3 on-chain deduction succeeded
ACCOUNT_AUTH_DEDUCTIONDEDUCT_SUCCESSGate account authorized deduction succeeded
ACCOUNT_AUTH_DEDUCTIONDEDUCT_FAILEDGate account authorized deduction failed

​
data fields (bizType=SUBSCRIPTION_PAYMENT)

FieldTypeDescription
subscriptionOrderNostringSubscription order number
merchantSubscriptionOrderNostringMerchant subscription order number
planNostringSubscription plan number
paymentOrderNostringDeduction order number for this cycle
merchantIdstringMerchant ID
cryptoCurrencystringCryptocurrency
chainstringBlockchain network
cryptoAmountstringSingle deduction amount
userAddressstringUser authorized address
authorizedAddressstringUser authorized address (same as userAddress in some payloads)
merchantAddressstringPlatform address that receives the deduction
txHashstringOn-chain transaction hash
payStatusstringDeduction status: SUCCESS / FAILED
payTimeint64Deduction time in ms
paymentChannelstringPayment channel; Web3 scenarios typically use WEB3

​
data fields (bizType=ACCOUNT_AUTH_DEDUCTION)

FieldTypeDescription
subscriptionOrderNostringSubscription order number
merchantSubscriptionOrderNostringMerchant subscription order number
merchantIdstringMerchant ID
deductOrderNostringPlatform deduction order number
merchantDeductNostringMerchant deduction order number
currencystringDeduction currency
amountnumberAmount deducted in this cycle
totalDeductednumberCumulative deducted amount
remainingAmountnumberRemaining authorized balance
deductStatusstringDeduction status: SUCCESS / FAILED
deductTimeint64Deduction time in ms
paymentChannelstringPayment 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