Skip to main content
WEBHOOK
subscriptionOrderWebhook
{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "CANCELLED",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

​
Overview

This page documents webhook subscriptionOrderWebhook. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. When a subscription order status changes, GatePay sends an asynchronous notification to the merchant-configured callback URL (bizType is SUBSCRIPTION_ORDER_STATUS).

​
Notes

  • Use bizId or data.subscriptionOrderNo 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 to the merchant callback URL when the subscription order status changes (created, authorized, running, cancelled, closed, etc.)
  • Top-level bizStatus matches orderStatus inside parsed data
  • If delivery fails, GatePay retries after 15 seconds (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice); you can also call Subscription order detail to fetch the latest state

​
Message structure

FieldTypeDescription
bizTypestringAlways SUBSCRIPTION_ORDER_STATUS
bizIdstringSubscription order number (usually matches data.subscriptionOrderNo)
bizStatusstringSubscription order status; see table below
datastringSubscription order details as a JSON string

​
Structure example

{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "CANCELLED",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}

​
bizStatus / orderStatus values

ValueDescription
CREATEDCreated
AUTHORIZEDAuthorized
CONFIRMINGConfirming
TRIALIn trial
RUNNINGRunning
UNPAIDUnpaid
COMPLETEDCompleted
CANCELLEDCancelled
CLOSEDClosed
BLOCKEDBlocked

​
data fields

After parsing the data JSON string, common fields include:
FieldTypeDescription
subscriptionOrderNostringSubscription order number
merchantSubscriptionOrderNostringMerchant subscription order number
planNostringPlatform subscription plan number
planNamestringSubscription plan name
planDescstringSubscription plan description
merchantIdstringMerchant ID that created the plan
productNostringProduct number
productNamestringProduct name
cryptoCurrencystringCryptocurrency
chainstringBlockchain network (may be empty when no on-chain authorization)
userAddressstringUser authorized address
authorizedAmountstringAuthorized amount
cryptoAmountstringSingle deduction amount
paidCountintegerNumber of completed deductions
totalPaidAmountstringTotal deducted amount
paymentChannelstringPayment channel, e.g. GATEPAY, WEB3 (may be empty)
periodstringBilling period, e.g. MONTH, NONE
intervalintegerBilling interval
totalPayCountintegerTotal number of deductions required
trialDaysintegerTrial days
endTimeint64Subscription end time in ms (0 if not set)
lastPayTimeint64Last deduction time in ms (0 if none)
orderStatusstringOrder status; matches top-level bizStatus
createTimeint64Order creation time in ms
updateTimeint64Order update time in ms

​
Callback example

​
Running (bizStatus=RUNNING)

{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "RUNNING",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"RUNNING\",\"paidCount\":2,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0.2\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}

​
Order cancelled (bizStatus=CANCELLED)

{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "CANCELLED",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}

Body

application/json

Subscription order status update notification POST method

​
bizType
string

Business type: SUBSCRIPTION_ORDER_STATUS

​
bizStatus
enum<string>

Business status: subscription order status code; same values as data.orderStatus.

Available options:
CREATED,
AUTHORIZED,
CONFIRMING,
TRIAL,
RUNNING,
UNPAID,
COMPLETED,
CANCELLED,
CLOSED,
BLOCKED
​
data
string

Subscription order details as a JSON string.

​
bizId
string

Subscription order number (usually matches data.subscriptionOrderNo).

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