Define Subscription API

merchantId
mandatory

Merchant key received from PayU’s team during the onboarding process.
Example: smsplus

subscriberEmail
mandatory

Email address of the subscriber. Mandatory for selected issuers in case of Debit card SI

subscriberMobile
mandatory

Mobile number of the subscriber. Mandatory for selected issuers in case of Debit card SI.

authRefId
mandatory

Auth Reference Id represents preferred payment instrument chosen by customer during Consent transaction. It is nothing but mihpayId returned in the response of successful Consent transaction along with payment source as “sist” or “sinst”. So, merchants can call Define subscription API post successful Consent transaction and associate authRefId = mihpayIdto setup subscriptions. Also, it provides convenience for creating subscriptions of users for whom Consent
transaction is already taken in past.

customParameter
optional

Key value pairs to associate any 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.
Example: "Policynumber": "12743123133", “Policytype”: “Terms Insurance”

subscriptionPlans
mandatory

Subscription Plan object is used to define billing details for the customer while defining the subscription. This object associates to add one or more plans to same subscription and provides great flexibility to run them independently with different amount, billing cycles and timelines.
It consists of following important parameters - planName, billingCycle, billingInterval, amount, startDate and totalCount.

planName
mandatory

Plan Name can be any merchant defined value which is easier for merchant to map with its system. This name is visible on PayU’s Subscription panel as well.
Sample value – Premium

billingCycle
mandatory

Billing Cycle defines whether customer needs to be charged over Daily basis, Weekly basis, Monthly basis, Yearly basis or one time. The value can be any of the following:

• DAILY
• WEEKLY
• MONTHLY
• YEARLY
• ONCE
• ADHOC

billingInterval
mandatory

Billing Interval is closely coupled with value of “billingCycle” and denotes at what frequency, the subscription plan needs to be executed.

For example, if merchant wants to run a bi-weekly subscription then values will be as below

• billingCycle = WEEKLY
• billingInterval = 2

So, customer will be charged once in every 2 weeks.

For monthly subscriptions, parameter values need to be sent in request are -

• billingCycle = MOHTHLY
• billingInterval = 1

Similarly, by keeping below values customer will be charged once in every 3 days -

• billingCycle = DAILY
• billingInterval = 3

In some use cases if, billingCycle is required to be used as ONCE or ADHOC, then billingInterval needs to be always passed as “1” as shown in below example -

• billingCycle = ONCE

• billingInterval = 1

• billingCycle = ADHOC

• billingInterval = 1

amount
mandatory

Billing amount object to capture value and currency as described in below parameters
Note: In use cases where billingCylce = ADHOC, then amount passed during define subscription call is treated as maximum amount since here billing amount and billing cycle varies as per usage of the subscription service. In this case, merchant is free to charge any amount for customer up to amount specified in defined subscription call

value
mandatory

Amount in XX.XX format
Sample value – 200.00 or 125.24 or 1000.50

currency
mandatory

Billing currency. Include INR for Indian currency.
Note: Currently, only supported INR.

startDate
mandatory

Start Date of the subscription. Note: Zion will not start charging the customer until this date has arrived. The format of this value should be in UNIX time format and it is specified in UTC (5:30 hours behind IST).
Example: 2018-08-14T11:24:19.020Z.

totalCount
mandatory

Total count defines the number of instances when the associated plan needs to be charged for the given subscription. For example, there is a monthly plan of 200 INR/per month. If totalCount = 5, then Zion will auto-debit the customer’s card for 5 instances once every month and then will automatically stop.
Example: 12.

planId
mandatory

Plan ID/IDs returned as a response of Create Plan interface, and that is/are opted by the customer for a given subscription. Every plan associated with a given subscription has its start date, total count, billing amount, billing cycle and interval. Depending upon these values, the number of invoices will be generated that are equal to the totalCount parameter. After all the invoices are attempted, that plan is marked as “Inactive” in the given subscription. However, another plan can continue to work as per its schedule and will generate specific Invoices as per the totalCount value specified against it. After all the invoices from all the Plans associated with the subscription are attempted, then the Status of the subscription is marked as Completed.
Example: 5b7a4ab8652d403c088fdeef.

customParameter
mandatory

Key-value pairs to associate any extra info with customer’s subscription.

subscriptionId

Unique subscription id generated by Zion for given customer and needs to be stored by merchant in their system.
This is reference point for all the further APIs related to subscription like update, cancel, add new billing plans etc..
Alternately this can be passed as one of the request parameters in the Consent transaction if define subscription is called before executing consent transaction i.e. authRefId is not present upfront.
Example: 5506a7c959b256e1a3c58b22

merchantId

Merchant key echoed back in the response

createdDate

Date of creation of Subscription

Sample Value - 2018-08-14T11:24:19.020Z

modifiedDate

Date of modification of Subscription

Sample Value - 2018-08-14T11:24:19.020Z

subscriberEmail

Email id of the subscriber echoed back in the response

subscriberMobile

Mobile number of the subscriber echoed back in the response

authRefId

Auth Reference id echoed back in the response. In case it has been not passed in the request, then it will be returned as null.

Sample Value - 7675320121

status

Status of the Subscription. Do NOT get this confused with status parameter inside ‘subscriptionPlans’ node.


 

The status is set as “Enabled” once subscription is having at least one active plan as well as authRefId associated. Otherwise it will remain in “Defined” state.


 

Once all the invoices for given subscription and respective plans are executed, then it will be marked as “Completed” and further charging on customer’s card will be stopped.


 

If merchant calls cancel subscription interface, then status of the subscription will be marked as “Cancelled” and further charging on customer’s card will be stopped immediately. Please note that once subscription is Cancelled, then there is no way to resume it.


 

Sample Values –

_ Defined
_ Enabled
_ Completed
_ Cancelled

subscriptionPlans

Plan object which returns all the plans associated with given subscription.


 

Every plan associated with given subscription have its own start date, total count, billing amount, billing cycle and interval. Depending upon these values, plan specific invoices will be generated which are equal to totalCount parameter of each plan.

Once all the invoices for the plan are attempted, that plan is marked as “Inactive” in given subscription.


 

However other plan can continue to work as per its schedule and will generate specific Invoices up to totalCount value specified against it.


 

Once invoices from all the plans associated with the subscription are attempted, then Status of the subscription is marked as “Completed”

planId

Plan Id which represents plan chosen by customer and sent in the define subscription request. This is generated uniquely by Zion and needs to be stored by merchant as it provides reference point for all the APIs related to plan update.


 

Sample Value - 5b7a4ab8652d403c088fdeef

startDate

Date of the payment from where subscription will start charging customer’s account in UTC time format (5:30 hours behind IST)


 

It can be different for different plans if more than one plan is associated with subscription


 

Sample Value - 2018-08-14T11:24:19.020Z

totalCount

Total count defines number of iterations when associated plan needs to be charged for given subscription

For example, there is monthly plan of 200 Rs / per month. If totalCount = 5, then Zion will auto debit customer’s card for 5 instances, once every month and then will automatically stop.

Sample Value – 12

status

Status of the plan associated with given subscription. Returned as “Active” when given plan is active.


 

Status is returned as “Inactive” in either of conditions -


 

_ all the invoices associated with given plan are executed completely

or

_ startDate and totalCount is not yet associated with plan

or

* Given planId is deleted from subscription

deleted

This is returned as false by default. It is returned as true only when plan is deleted from given subscription by calling delete plan with subcription method

Sample value – false

numberOfPaidInvoices

Number of paid invoices for given plan id.

numberOfInvoiceGenerated

Number of Invoices generated for given plan id.

nextBillingDate

Next billing date for given plan id when customer will be charged

lastPaymentDate

Last payment date for given plan id when customer was already charged

billingInterval

Billing Interval for given plan id

billingCycle

Billing Cycle for given plan id

planName

Name of the plan for given plan id

amount

Amount node associated with given plan id. Invoices will be generated with this amount for given plan id and subscription combination.


 

For plan having billingCyle = ADHOC, value against amount acts as maximum limit.

value

Billing Amount for given plan id

currency

Billing Currency for given Plan id

customParameter

Key value pair echoed back as part of response

possibleActions

Possible action helps merchant to identify what will be further action applicable on given subscription id.


 

In this case allowed actions will be “Patch Subscription”, “Get Subscription” and “Delete Subscription”

All the mandatory details are present in the request of define subscription.
{
"merchantId": "rY1eWa",
"authRefId": "7375340021",
"subscriberEmail": "[email protected]",
"subscriberMobile": "9999999999",
"customParameter": {
"Policynumber": "12743123111",
"Policytype": "Life Insurance"
},
"subscriptionPlans": [
{
"planName": "Premium",
"startDate": "2019-03-26T11:00:00.000Z",
"totalCount": 5,
"billingInterval": 1,
"billingCycle": "DAILY",
"amount": {
"value": 2,
"currency": "INR"
}
}
]
}

Enabled

Active

Start date &total count is not passed in plan object but rest

of the details are present:
{
"merchantId": "aY1eW1",
"authRefId": "7375340021",
"subscriberEmail": "[email protected]",
"subscriberMobile": "9999999999",
"customParameter": {
"Policynumber": "12743123111",
"Policytype": "Life Insurance"
},
"subscriptionPlans": [
{
"planName": "Premium",
"billingInterval": 1,
"billingCycle": "DAILY",
"amount": {
"value": 2,
"currency": "INR"
}
}
]
}

Defined

Inactive

authRefId is not passed but rest of the details are present.
{
"merchantId": "aY1eW1",
"subscriberEmail": "[email protected]",
"subscriberMobile": "9999999999",
"customParameter": {
"Policynumber": "12743123111",
"Policytype": "Life Insurance"
},
"subscriptionPlans": [
{
"planName": "Premium",
"startDate": "2019-03-26T11:00:00.000Z",
"totalCount": 5,
"billingInterval": 1,
"billingCycle": "DAILY",
"amount": {
"value": 2,
"currency": "INR"
}
}
]
}

Defined

Inactive