Subscription Life Cycle and role of Webhooks

During on-boarding process of Zion, PayU team request merchant to provide a HTTPS URL or Webhook from where different events of subscription are posted over server to server call. Merchant needs to consume these events and update its

system so that customer should receive un-interrupted service from merchant’s end.

Before understanding every event, let’s understand subscription life cycle which is directly related to every event.

  • Whenever subscription is created into Zion system subscription id is generated and status of the subscription is set as Defined. This step triggers an event denoted as SUBSCRIPTION_DEFINED_HTTP in Zion terminology.

  • On passing subscription id in the request of consent transaction and performing successful payment, customer’s card details gets associated with given subscription (internally subscription Id) by Zion. At this step, status of the subscription gets changed to Enabled and event is triggered as SUBSCRIPTION_ENABLED_HTTP in Zion terminology. This event will be also triggered if authRefId is getting associated during Defined Subscription interface itself

  • Once all the invoices are attempted on customer’s card associated with all the plans, an event is triggered by Zion denoted as SUBSCRIPTION_COMPLETED_HTTP. At this step, event subscription status is changed from Enabled to Completed

  • At any given moment, customer can request merchant to stop the active subscription opted during sign-up. In this case, merchant calls “Cancel

Subscription” interface or uses PayU’s dashboard to do the same. In this step, subscription status gets changing from Enabled to Cancelled and event is triggered as SUBSCRIPTION_CANCELLED_HTTP as per Zion terminology.

Subscription notification response parameters

ParameterDescription
merchantIdMerchant key echoed back in the notification
subscriptionIdSubscription id of the customer echoed back in the notification
planIdPlan Ids associated with the subscription against which invoices are generated and customer account is getting charged
authRefIdThis is nothing but mihpayId or consent transaction id

generated by PayU and returned to merchant as a part of success response of the consent transaction. Will be blank in case of subscription “status = Defined”
statusStatus of the customer as explained in the life cycle of subscription. Possible values are:
- Defined
- Enabled
- Completed
- Cancelled
subscriberEmailEmail id of the subscriber echoed back in the notification
subscriberMobileMobile id of the subscriber echoed back in the notification
notificationTypeNotification type denotes different events triggered by Zion at different stages of Subscription life cycle. Possible values are:
- SUBSCRIPTION_DEFINED_HTTP
- SUBSCRIPTION_ENABLED_HTTP
- SUBSCRIPTION_COMPLETED_HTTP
- SUBSCRIPTION_CANCELLED_HTTP
customParameterKey value pairs associated for extra information with subscription. These details will be returned to merchant in webhook notification against every payment executed from Zion so that merchant can effectively map payment response with its own system.

Sample notification response format for SUBSCRIPTION_DEFINED_HTTP

{
  "merchantId": "YQeVda",
  "subscriptionId": "5c99ef2e3114ad37b5193add",
  "planIds": "ZION155359211050420|ZION155359211050420",
  "authRefId": "",
  "status": "Defined",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "9999999999",
  "notificationType": "SUBSCRIPTION_DEFINED_HTTP",
  "customParameter": {
    "Policynumber": "50112312313123"
  }
}

Sample notification response format for SUBSCRIPTION_ENABLED_HTTP

{
  "merchantId": "YQeVda",
  "subscriptionId": "5c99ef2e3114ad37b5193add",
  "planIds": "ZION155359211050420|ZION155359211050420",
  "authRefId": "75461212",
  "status": "Enabled",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "9999999999",
  "notificationType": "SUBSCRIPTION_ENABLED_HTTP",
  "customParameter": {
    "Policynumber": "50112312313123"
  }
}

Sample notification response format for SUBSCRIPTION_COMPLETED_HTTP

{
  "merchantId": "YQeVda",
  "subscriptionId": "5c99ef2e3114ad37b5193add",
  "planIds": "ZION155359211050420|ZION155359211050420",
  "authRefId": "75461212",
  "status": "Completed",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "9999999999",
  "notificationType": "SUBSCRIPTION_COMPLETED_HTTP",
  "customParameter": {
    "Policynumber": "50112312313123"
  }
}

Sample notification response format for SUBSCRIPTION_CANCELLED_HTTP

{
  "merchantId": "YQeVda",
  "subscriptionId": "5c99ef2e3114ad37b5193add",
  "planIds": "ZION155359211050420|ZION155359211050420",
  "authRefId": "75461212",
  "status": "Cancelled",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "9999999999",
  "notificationType": "SUBSCRIPTION_CANCELLED_HTTP",
  "customParameter": {
    "Policynumber": "50112312313123"
  }
}