Subscription Status & Notifications
This page helps you understand Subscription status changes and notification results. For the main integration flow, read the Subscription Integration Guide first.
Subscription State Diagram
The diagram below is recommended as a shared reference for merchant-side joint debugging, product rule design and customer-service alignment. It describes subscription plan status changes and which webhook event each transition fires (the edge labels are the notifyType values):
PENDING -> IN_TRIAL: with a trial, the first authorization succeeds and the subscription enters the trial.PENDING -> ACTIVE: without a trial, the first payment succeeds and the subscription takes effect directly.IN_TRIAL -> ACTIVE: the trial ends and the conversion charge succeeds.IN_TRIAL -> PAST_DUE: the trial ends and the conversion charge fails.ACTIVE -> PAST_DUE: a renewal charge time arrives but the charge fails.PAST_DUE -> ACTIVE: an automatic recovery charge succeeds and the subscription returns to normal.PENDING / ACTIVE / PAST_DUE -> CANCELLED: cancelled after creation, cancelled by user/merchant, ended at term, or automatic retries exhausted.
Common subscription status recommendations:
PENDING: the subscription is created but has not entered the formal effective stage; service activation is not recommended.IN_TRIAL: the subscription is in trial; the service is currently usable.ACTIVE: the subscription is in good standing; the user is entitled to keep using the service.PAST_DUE: this renewal charge failed and the subscription is in arrears or automatic recovery; whether to keep serving is a merchant-side decision.CANCELLED: the subscription is terminated and will not renew automatically.
A consistent way to read currentPeriod:
| Value | Meaning | Recommended action |
|---|---|---|
0 | Trial period | Normally this should coincide with status=IN_TRIAL and a valid trial configuration; treat conflicting field combinations as abnormal data |
1 | The first formal billing period | The first formal activation has completed |
2 and above | Subsequent renewal periods | Continue fulfillment based on renewal records, status and entitlement rules |
Subscription Notification Event Types
It is recommended to handle subscription notifications by notifyType (event type) + status (current status) together, rather than watching status changes alone:
Payment results and the subscription status changes they cause may be delivered through payment notifications and subscription notifications respectively. Verify and deduplicate the two kinds of notifications independently; do not make your integration depend on the arrival order or spacing of webhooks. When notifications are missing, duplicated or inconsistent, confirm via the query APIs as compensation.
| notifyType | status | Typical meaning | What the merchant should do | Keep serving? |
|---|---|---|---|---|
SUBSCRIPTION_CREATED | PENDING | Subscription created and pending effect (future startAt, no immediate charge) | Record the creation; wait for the later charge result | No |
SUBSCRIPTION_IN_TRIAL | IN_TRIAL | Entered the trial period | Activate trial entitlements; record currentPeriod=0 | Yes |
SUBSCRIPTION_ACTIVATED | ACTIVE | First/conversion charge succeeded; subscription activated | Activate formal subscription entitlements | Yes |
SUBSCRIPTION_PAST_DUE | PAST_DUE | Renewal failed; entered grace period | Enter grace period / downgrade / remind top-up per business rules | Business decision |
SUBSCRIPTION_RECOVERED | ACTIVE | Recovery charge succeeded within the grace period | Restore formal service | Yes |
SUBSCRIPTION_PLAN_CHANGED | ACTIVE | Plan change effective (price/cycle change) | Update local plan, amount, cycle and entitlement version; diff the change with previousAttributes | Yes |
SUBSCRIPTION_PLAN_CHANGE_SCHEDULED | ACTIVE | A next-cycle change is registered | Record the scheduled change (pendingUpdate); handle it at the effective date | Yes |
SUBSCRIPTION_PLAN_CHANGE_FAILED | ACTIVE | Plan change failed (change fully rolled back) | Record the failure reason; prompt the user to retry the change | Yes |
SUBSCRIPTION_CANCELLATION_SCHEDULED | ACTIVE | Period-end cancellation marked | Record cancelAt (period end time); keep fulfilling this period | Yes |
SUBSCRIPTION_CANCELLATION_REVOKED | ACTIVE | Period-end cancellation mark revoked | Clear the local "cancellation scheduled" mark | Yes |
SUBSCRIPTION_CANCELLED | CANCELLED | Subscription cancelled | Turn off auto-renewal; stop or adjust service per the cancel reason | No |
When status=CANCELLED, it is recommended to differentiate actions by cancelReason:
| cancelReason | Scenario | Recommended merchant action |
|---|---|---|
user_requested | The user cancelled proactively | Stop service at the cancellation effective moment; no further auto-renewal |
merchant_requested | The merchant cancelled proactively | Handle per merchant-side cancellation policy; sync membership end time if needed |
payment_retry_exhausted | Automatic recovery attempts exhausted | Turn off auto-renewal; decide whether to suspend immediately or end the grace period |
plan_ended | The subscription ended naturally at term | Treat as plan expiry; no further renewal |
Subscription Notification Payload Structure
All bizContent fields of subscription notifications are camelCase, and time fields are second-level numeric timestamps:
| Field | Type | Description |
|---|---|---|
notifyType | String | Event type (see the table above) |
merchantSubscriptionId | String | Merchant-side unique subscription plan ID |
subscriptionId | String | PingPong subscription number |
requestId | String | The merchant request number that triggered this event |
status | String | Current subscription plan status |
flatPrice | Object | Current effective per-period charge amount and currency |
period | Object | Billing cycle {count, unit} |
totalPeriodCount | Integer | Total number of billing periods (excluding the trial) |
currentPeriod | Integer | Current period number (0 = trial) |
currentPeriodStartAt | Long | Start of the current billing period, second-level timestamp |
currentPeriodEndAt | Long | End of the current billing period, second-level timestamp |
startAt | Long | Subscription start time, second-level timestamp |
endAt | Long | Subscription end time, second-level timestamp |
updateAt | Long | Generation time of this notification, second-level timestamp |
cancelAtPeriodEnd | Boolean | Whether period-end cancellation is scheduled |
previousAttributes | Object | Snapshot of fields before the change (returned only for change-type events, e.g. flatPrice, endAt, status); can be diffed against current values |
paymentRecords | Array | Payment record summary (returned for fund-type events such as renewal charges) |
refundRecords | Array | Refund records (returned for refund-type events) |
action | Object | PAST_DUE recovery action (returned only in SUBSCRIPTION_PAST_DUE notifications when the recovery checkout is available): redirectUrl is the recovery checkout URL; actionExpiredAt is its expiry (second-level timestamp, min(72 hours, remaining retry window) from generation) |
discount | Object | Currently effective discount configuration (returned when a discount is configured) |
Future-effective creation notification example (SUBSCRIPTION_CREATED, future startAt, no immediate charge):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_SESSION_202607150001",
"notifyType": "SUBSCRIPTION_CREATED",
"status": "PENDING",
"currentPeriod": 0,
"currentPeriodStartAt": 1786692039,
"currentPeriodEndAt": 1789370439,
"startAt": 1786692039,
"endAt": 1789370439,
"updateAt": 1784013639,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "PENDING"
}
}Trial entry notification example (SUBSCRIPTION_IN_TRIAL):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_SESSION_202607150001",
"notifyType": "SUBSCRIPTION_IN_TRIAL",
"status": "IN_TRIAL",
"currentPeriod": 0,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1784017239,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784013639,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"trial": {
"startAt": 1784013639,
"endAt": 1784017239,
"periodDays": 7
},
"previousAttributes": {
"status": "PENDING"
}
}Subscription activation notification example (SUBSCRIPTION_ACTIVATED, showing bizContent only):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_SESSION_202607150001",
"notifyType": "SUBSCRIPTION_ACTIVATED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784013662,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "PENDING"
}
}Renewal failure entering grace period notification example (SUBSCRIPTION_PAST_DUE):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_RENEW_202607160001",
"notifyType": "SUBSCRIPTION_PAST_DUE",
"status": "PAST_DUE",
"currentPeriod": 2,
"currentPeriodStartAt": 1785153662,
"currentPeriodEndAt": 1787832062,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1785153662,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"autoRecovery": {
"enabled": true,
"attemptCount": 1,
"maxAttempts": 1,
"status": "ACTIVE"
},
"action": {
"redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"actionExpiredAt": 1792200000
}
}
actionis the PAST_DUE recovery checkout URL. See Renewal & Auto-Recovery · PAST_DUE recovery checkout.
Grace period recovery notification example (SUBSCRIPTION_RECOVERED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_RECOVER_202607170001",
"notifyType": "SUBSCRIPTION_RECOVERED",
"status": "ACTIVE",
"currentPeriod": 2,
"currentPeriodStartAt": 1785153662,
"currentPeriodEndAt": 1787832062,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1785240000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "PAST_DUE"
}
}Plan change notification example (SUBSCRIPTION_PLAN_CHANGED, with previousAttributes diff):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607160001",
"notifyType": "SUBSCRIPTION_PLAN_CHANGED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "15.00",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"flatPrice": {
"amount": "9.99",
"currency": "USD"
}
}
}Next-cycle change scheduled notification example (SUBSCRIPTION_PLAN_CHANGE_SCHEDULED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607160001",
"notifyType": "SUBSCRIPTION_PLAN_CHANGE_SCHEDULED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"pendingUpdate": {
"effectiveMode": "NEXT_CYCLE",
"flatPrice": {
"amount": "15.00",
"currency": "USD"
}
}
}
statusstaysACTIVEand the top-levelflatPriceremains the current period's price; the scheduled change content is inpendingUpdate, and aSUBSCRIPTION_PLAN_CHANGEDwill be pushed after it takes effect at the next cycle.
Plan change failed notification example (SUBSCRIPTION_PLAN_CHANGE_FAILED, change fully rolled back):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607160001",
"notifyType": "SUBSCRIPTION_PLAN_CHANGE_FAILED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"pendingUpdate": {
"effectiveMode": "IMMEDIATE",
"flatPrice": {
"amount": "15.00",
"currency": "USD"
}
},
"resultCode": "system_internal_gateway_error",
"resultMessage": "Internal gateway error"
}The failed intent stays in
pendingUpdate; the subscription price and status roll back as a whole (price still 9.99, still ACTIVE).
Period-end cancellation scheduled notification example (SUBSCRIPTION_CANCELLATION_SCHEDULED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_CANCEL_202607160001",
"notifyType": "SUBSCRIPTION_CANCELLATION_SCHEDULED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": true,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12
}
statusstaysACTIVE;cancelAtPeriodEnd=truemeans period-end cancellation is marked.
Period-end cancellation revoked notification example (SUBSCRIPTION_CANCELLATION_REVOKED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607170001",
"notifyType": "SUBSCRIPTION_CANCELLATION_REVOKED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784100000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"cancelAtPeriodEnd": true
}
}
cancelAtPeriodEndchanged back fromtruetofalse, meaning the period-end cancellation mark was revoked.
Subscription cancelled notification example (SUBSCRIPTION_CANCELLED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_CANCEL_202607160001",
"notifyType": "SUBSCRIPTION_CANCELLED",
"status": "CANCELLED",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1784100000,
"updateAt": 1784100000,
"cancelAtPeriodEnd": false,
"cancelReason": "merchant_requested",
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "ACTIVE"
}
}
statusbecomesCANCELLED;cancelReasonis the cancellation reason (lowercase enum:merchant_requested/user_requested/payment_retry_exhausted/plan_ended).
Payment and Refund Notifications
Subscription payment result in a payment notification example (showing bizContent only):
{
"transactionId": "26071400000051156949",
"merchantTransactionId": "SUB_PLAN_202607150001_P1",
"requestId": "074dbbe1-bb21-4bbd-8223-8dd6757d69b1",
"status": "SUCCESS",
"amount": "100.000000",
"currency": "USD",
"invoiceId": "INV-2610161210100000008200011522",
"paymentMethod": {
"type": "VISA"
},
"subscriptionDetail": {
"subscriptionId": "SUB-2607140846100000000900111522",
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"currentPeriod": 1,
"autoRecovery": {
"enabled": true,
"attemptCount": 0,
"maxAttempts": 1,
"status": "ACTIVE"
}
}
}This example usually means:
- This period's payment has succeeded;
- The success corresponds to the formal billing period
currentPeriod=1; invoiceIdis the key field linking to Invoice reconciliation (use it to call the Invoice Details API);- Use
merchantTransactionId/transactionIdfor payment reconciliation; - Use
subscriptionDetail.subscriptionIdto link back to the subscription master record.
Subscription refund notification example (showing bizContent only):
{
"amount": "4.840000",
"refundTime": "1785293461000",
"remark": "subscription update refund, taskId=517",
"transactionId": "26072900000151333315",
"notifyType": "REFUND",
"merchantTransactionId": "SUB-2607290250100000032300111522_P1",
"currency": "USD",
"merchantRefundId": "SREF-2607290251100000004100151522",
"refundEndingTime": "1785293463485",
"refundId": "26072900010451333317",
"status": "SUCCESS"
}This example usually means:
- This refund has succeeded;
merchantRefundId/refundIdcan be used for refund-level idempotency and reconciliation;merchantTransactionIdis the original payment's merchant transaction number associated with the refund;- A successful refund does not mean the subscription is cancelled or a plan has taken effect — the subscription-level status should still come from subscription notifications or the Query Subscription API.
Query subscription payments response example (showing bizContent only):
{
"merchantSubscriptionId": "SUB_MER_001",
"subscriptionId": "SUB-1234567890abcdef",
"requestId": "REQ_SUB_PAYMENT_QUERY_001",
"paymentRecords": [
{
"period": 1,
"merchantTransactionId": "SUB-1234567890abcdef_P1",
"transactionId": "PAY-ORDER-1234567890",
"requestId": "SPAY-1234567890",
"amount": "9.99",
"currency": "USD",
"status": "SUCCESS",
"transactionTime": "1785152760000",
"transactionEndingTime": "1785152860000",
"paymentMethod": {
"type": "VISA"
}
}
],
"resultCode": "000000",
"resultMessage": "SUCCESS"
}To answer "can this subscription keep receiving service right now", look at the subscription result first; to answer "was this period actually charged, how much, and with which payment method", look at the payment result first.
Note
statusat the top level of the subscription query and in subscription notifications is the subscription plan status;paymentRecords[].statusin payment notifications is the single-payment status.currentPeriodsits at the top level of the notificationbizContent;0means the trial period. Normally this should coincide withstatus=IN_TRIALand a validtrialconfiguration.- If you receive both payment and subscription notifications, apply idempotency to each independently — do not treat them as the same notification.
- If an Update or Cancel triggers a refund but the refund notification is delayed, missing, or lacks a linkable refund number, use Query Subscription Payments and Query Subscription for compensation confirmation.
Time field compatibility
In API requests, startAt and endAt are 10-digit second-level timestamp strings per the interface definition. In API responses (query/update/cancel), startAt, endAt, cancelAt, transactionTime, transactionEndingTime etc. are 13-digit millisecond timestamp strings. In subscription notifications (webhooks), startAt, endAt, updateAt, currentPeriodStartAt and currentPeriodEndAt are second-level numeric timestamps. Parse per channel, and avoid integer types that can only hold 32 bits.
