Webhooks for Zion

Subscription

During on-boarding process of Zion, PayU team will request you to provide a HTTPS URL or Webhook from where different events of subscription are posted over server to server call. You 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

Parameter	Description
merchantId	Merchant key echoed back in the notification
subscriptionId	Subscription id of the customer echoed back in the notification
planId	Plan Ids associated with the subscription against which invoices are generated and customer account is getting charged
authRefId	This 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”
status	Status of the customer as explained in the life cycle of subscription. Possible values are: - Defined - Enabled - Completed - Cancelled
subscriberEmail	Email id of the subscriber echoed back in the notification
subscriberMobile	Mobile id of the subscriber echoed back in the notification
notificationType	Notification 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
customParameter	Key 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"
  }
}

Invoice

During on-boarding process of Zion, PayU team will request you to
provide a HTTPS URL or Webhook from where different events of Invoice
are posted over server to server call. You 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 Invoice life cycle
which is directly related to every event.

Whenever Invoice is created manual or through the schedular into
Zion system invoice id is generated and status of the invoice is set
as DUE . This step triggers an event denoted as
INVOICE_DUE_HTTP in Zion terminology.
Once the invoice is charged by the zion system INVOICEFAILED_HTTP
(_INVOICE_FAILED_HTTP_V2) or INVOICEPAID_HTTP
(_INVOICE_PAID_HTTP_V2) event will get trigger based on the
transaction response and event setup of merchant.

Invoice notification response parameters

Parameter	Description
merchantId	Merchant key echoed back in the notification
subscriptionId	Subscription id of the customer echoed back in the notification
invoiceId	Invoice id generated against the subscription
authRefId	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”
paymentStatus	Status of the customer as explained in the life cycle of subscription. Possible values are:`"value": "10.00", The transaction amount` `"currency": "INR", The transaction Currency type Paid Initiated - Failed
subscriberEmail	Email id of the subscriber echoed back in the notification
subscriberMobile	Mobile id of the subscriber echoed back in the notification
notificationType	Notification type denotes different events triggered by Zion at different stages of Invoice life cycle. Possible values are: 'INVOICE_DUE_HTTP' `INVOICE\_PAID\_HTTP or INVOICE\_PAID\_HTTP\_V2` `INVOICE_FAILED_HTTP or INVOICE_FAILED_HTTP_V2\CONSENT_TXN_REFUND_HTTP'
customParameter	Key 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.
refId	Contains the reference ID
transactionId	Contains the Invoice number
authorized	Contains the flag if the transaction authorized
captured	Contains the flag if the transaction realized
reason	Contains the transaction message
issuerAuthId	Contains the issuer auth ID.
authDate	Contains the invoice charge date
errorCode	Contains the failure response code

Sample notification response format for INVOICE_DUE_HTTP

{
  "merchantId": "vikram-zion",
  "subscriptionId": "662f915e206aac3ea4e12589",
  "invoiceId": "662f9323206aac3ea4e1258e",
  "planId": "ZION171439343854812",
  "authRefId": "2104202400011",
  "amount": {
    "value": "10.00",
    "currency": "INR"
  },
  "paymentStatus": "Due",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "8859111744",
  "notificationType": "INVOICE_DUE_HTTP",
  "customParameter": null,
  "refId": ""
}

Sample notification response format for INVOICE_PAID_HTTP

{
  "merchantId": "vikram-zion",
  "subscriptionId": "662f915e206aac3ea4e12589",
  "invoiceId": "662f9323206aac3ea4e1258e",
  "planId": "ZION171439343854812",
  "authRefId": "2104202400011",
  "amount": {
    "value": "10.00",
    "currency": "INR"
  },
  "paymentStatus": "Paid",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "8859111744",
  "notificationType": "INVOICE_PAID_HTTP",
  "customParameter": null,
  "refId": ""
}

Sample notification response format for INVOICE_FAILED_HTTP

{
  "merchantId": "vikram-zion",
  "subscriptionId": "662f353d594a4707197830b4",
  "invoiceId": "662f3544594a4707197830b6",
  "planId": "ZION17143698538721",
  "authRefId": "2104202400006",
  "amount": {
    "value": "10.00",
    "currency": "INR"
  },
  "paymentStatus": "Failed",
  "subscriberEmail": "[[email protected]](mailto:[email protected])",
  "subscriberMobile": "8859111744",
  "notificationType": "INVOICE_FAILED_HTTP",
  "customParameter": null,
  "refId": ""
}

Sample notification response format for INVOICE_PAID_HTTP_V2

{
  "merchantId": "vikram-zion",
  "subscriptionId": "662f353d594a4707197830b4",
  "invoiceId": "662f3544594a4707197830b6",
  "planId": "ZION17143698538721",
  "authRefId": "2104202400006",
  "amount": {
    "value": "10.00",
    "currency": "INR"
  },
  "paymentStatus": "Paid",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "8859111744",
  "notificationType": "INVOICE_PAID_HTTP_V2",
  "customParameter": null,
  "refId": "",
  "transactionReceipt": {
    "transactionId": "66215f83322e9a39a66035e2",
    "authorized": "true",
    "captured": "",
    "reason": "Succssfully Completed",
    "acquirerId": "19705009727",
    "acquirerAuthId": "",
    "issuerAuthId": "",
    "authDate": "2024-04-29T05:55:02.420Z",
    "errorCode": "0"
  }
}

Sample notification response format for INVOICE_ FAILED_HTTP_V2

{
  "merchantId": "vikram-zion",
  "subscriptionId": "662f353d594a4707197830b4",
  "invoiceId": "662f3544594a4707197830b6",
  "planId": "ZION17143698538721",
  "authRefId": "2104202400006",
  "amount": {
    "value": "10.00",
    "currency": "INR"
  },
  "paymentStatus": "Failed",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "8859111744",
  "notificationType": "INVOICE_FAILED_HTTP_V2",
  "customParameter": null,
  "refId": "",
  "transactionReceipt": {
    "transactionId": "66215f83322e9a39a66035e2",
    "authorized": "true",
    "captured": "",
    "reason": "Failed",
    "acquirerId": "19705009727",
    "acquirerAuthId": "",
    "issuerAuthId": "",
    "authDate": "2024-04-29T05:55:02.420Z",
    "errorCode": "0"
  }
}

Updated 8 months ago