# Subscription Notification
When the subscription status changes (such as subscription creation success, periodic deduction success, deduction failure, subscription cancellation, etc.), the payment gateway will initiate a callback notification to the merchant system. If the merchant system does not return correctly, the payment gateway will delay and notify again.
# Notification
Notification
Request URL: This link is set via the notifyUrl parameter submitted through the Unified Order API. If the link cannot be accessed, the merchant system will not receive notifications from the payment center.
Request Method: POST
Request Type: application/x-www-form-urlencoded
- * Security: For the production environment, strict source verification is performed on notifications. Production environment traffic export "Production Environment Traffic Export"
# Notification Parameters
| Field Name | Variable Name | Type | Example Value | Description |
|---|---|---|---|---|
| Notification ID | logId | String | L_20210618001 | Unique identifier for this notification (corresponds to Subscription Log ID) |
| Subscription ID | subscriptionId | String | SUB_20210618001 | Payment system subscription ID |
| Merchant No | mchNo | String | M1621873433953 | Merchant Number |
| App ID | appId | String | 60cc09bce4b0f1c0b83761c9 | App ID |
| Merchant Order No | mchOrderNo | String | sub1624005107281 | Merchant passed order number |
| Plan ID | planId | String | PLAN_001 | Subscription Plan ID |
| Plan Code | planCode | String | VIP_MONTH | Subscription Plan Code |
| Pending Plan ID | pendingPlanId | String | PLAN_002 | Pending subscription plan ID (populated after next-period change confirmation) |
| Pending Plan Code | pendingPlanCode | String | PRO_MONTH | Pending subscription plan code (populated after next-period change confirmation) |
| Subscription cycle | cycleIndex | integer | 1 | Subscription cycle |
| Merchant User ID | mchUserId | String | user_001 | Merchant User ID |
| Payment Order ID | payOrderId | String | P202106181642329900002 | Payment Order ID (Optional) for refund |
| State | state | Byte | 1 | 0-Init, 1-Pending, 2-Active, 3-Paused, 4-Overdue, 5-Canceled, 6-Completed, 7-Invalid |
| Current Period Start | currentPeriodStart | Long | 1624005107281 | Current billing cycle start timestamp (Optional) |
| Current Period End | currentPeriodEnd | Long | 1626597107281 | Current cycle end/next billing timestamp (Optional) |
| Cancel At Period End | cancelAtPeriodEnd | Boolean | false | Whether to cancel at the end of the period |
| Currency | currency | String | USD | Currency |
| Current Period Amount | currentPeriodAmount | Integer | 100 | Current Period Amount,in cents |
| Is Active | isActive | Boolean | true | Whether currently valid based on state and time |
| Request Time | reqTime | Long | 1622016572190 | Notification send time, 13-digit timestamp |
| Event Type | eventType | String | SUBSCRIPTION_CREATED | Event Type, see table below |
| Change ID | changeId | String | CHG_20210618164201 | Change record ID (populated for change-related events, for reconciliation with the changeId returned at creation) |
| Sign | sign | String | CCD9083A6DAD9A2DA9F668C3D4517A84 | Signature value |
# Event Type (eventType)
| Event Type | Description | Trigger Scenario | currentPeriodAmount |
|---|---|---|---|
SUBSCRIPTION_CREATED | Subscription Created | First payment successful, state becomes Active | Current Period Amount |
SUBSCRIPTION_RENEWED | Subscription Renewed | Subsequent cycle auto/manual deduction successful | Current Period Amount |
SUBSCRIPTION_CANCELED | Subscription Canceled | User proactively cancels or auto-cancels upon expiration | None |
SUBSCRIPTION_PAY_FAILED | Payment Failed | Periodic deduction failed | Current Period Amount |
SUBSCRIPTION_COMPLETED | Subscription Completed | Reached maximum cycles, subscription ends naturally | None |
SUBSCRIPTION_OVERDUE | Subscription Overdue | Multiple deduction failures leading to overdue state | None |
SUBSCRIPTION_UPGRADE_SCHEDULED | Upgrade Scheduled | Next-period upgrade confirmed; plan will switch at the next renewal | None |
SUBSCRIPTION_DOWNGRADE_SCHEDULED | Downgrade Scheduled | Next-period downgrade confirmed; plan will switch at the next renewal | None |
SUBSCRIPTION_PLAN_CHANGED | Plan Changed | Immediate change supplement payment succeeded and plan switched | Current Period Amount |
SUBSCRIPTION_RENEWED_WITH_PLAN_CHANGE | Renewed with Plan Change | Next-period change merged with renewal deduction success and plan switched | Current Period Amount |
SUBSCRIPTION_CHANGE_CANCELED | Change Canceled | Change reservation canceled (manual cancel / auto-replace / expiry cleanup / subscription cancel linkage) | None |
# Return Result
After processing, the business system currently returns the handling result to the payment center synchronously. Returning the string success indicates processed (*success only means the notification has been received, unrelated to order status). If an exception occurs during processing and a non-success is returned, it indicates failure, and the payment center will notify the business system again. (Notification frequency is configured as 15s/3m/10m/30m/30m/1h/2h/6h/15h)
| State | state | Business System Response |
|---|---|---|
| 1 | Active/Paid | success |
| 2 | Paused/Failed | success |
| 3 | Canceled | success |
| 4 | Overdue | success |
| 5 | Completed | success |
Note
The returned string must be lowercase, and there must be no spaces or newlines before or after.
# Notification Example Data
subscriptionId=SUB_20210618001&mchOrderNo=sub1624005107281&state=1&isActive=true&sign=4210976D520A0FC7F4E951549E8F087C&reqTime=1701825776788&logId=L_20210618001