After the Subscription is created, Zion generates a unique subscription ID and returns it to you over the server-to-server connection. This Subscription ID needs to be sent in the payment request of the Consent transaction so that the PayU can associate the customer’s card information with the subscription created and start charging automatically over a recurring basis without your or customer’s intervention.
Post Method: POST
Path: {base_url}/api/sub/v1/merchant/subscriptions/{subscriptionId}
Environment
Request parameters
Header
| Content-Type (mandatory) | application/json |
| X-PayU-Subscription- Signature (mandatory) | SHA512 Signature generated by encrypting request parameters in the body by Merchant Key, Merchant Salt and Plan ID. For more information on how to create this signature, refer to X-PayU-Subscription-Signature Generation Method. |
Body
The request body parameters to create a subscription request are:
| Parameter | Value |
|---|---|
| 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. |
Notes:
For using Define Subscription API, authRefId is not mandatory. This is because, merchant can define subscription and receives Subscription Id which can be sent in the Consent transaction so that Zion automatically associates authRefId with Subscription Id in the background. We will see this in detail during Consent transaction integration.
Without authRefId, subscription cannot be Enabled because as represents which card / bank account needs to be charged during billing cycle of various plans. So, it needs to be associated with Subscription in either of the following:
- During define Subscription call with assumption that consent transaction is already completed
- By defining subscription without it but then passing Subscription Id in Consent transaction request
- Using Update Subscription API
Sample plan
For a yearly plan starting from 1st Jan 2019, having monthly subscription of 100 Rs, the plan details look similar to the following:
- planName = MONEY SAVER
- billingCycle = MONTHLY
- billingInterval = 1
- amount
- value = 100.00
- currency = INR
- startDate = 2019-01-01T00:00:00.000Z
- totalCount = 12
Zion will start charging customer from 1 Jan 2019 till 1 Dec 2019, 1st of every month with total charge requests will be 12 and then will stop automatically****
X-PayU-Subscription-Signature Generation Method
signatureData = SHA512("merchantId:" + merchantId + "|subscriptionPlanIds:" + subscriptionPlanIds + "|" + merchantSalt)
where, subscriptionPlanIds = “[” + planId1 + “|” + planId2 + “]” if you have more than one plan to be associated with the given subscription.
Example:
SignatureData = merchantId:smsplus|subscriptionPlanIds:[5acb64a8070c9406b0928207|5acb64a8070c 9406b0928208]|abcdef
Here for the merchant key is smsplus, plan IDs 5acb64a8070c9406b0928207 and 5acb64a8070c9406b0928208 are associated for given subscription having abcdef as merchant salt.
Sample request
{
"merchantId": "YQeVda",
"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"
}
}
]
}
Sample response
{
"subscriptionId": "5c972a35652d405ed9834f52",
"merchantId": " YQeVda",
"subscriberEmail": "[email protected]",
"subscriberMobile": "9999999999",
"authRefId": "7375340021",
"subscriptionPlans": [
{
"planId": "ZION155341061387133",
"startDate": "2019-03-26T11:00:00.000Z",
"totalCount": 5,
"numberOfPaidInvoices": 0,
"numberOfInvoiceGenerated": 0,
"status": "Active",
"deleted": false,
"nextBillingDates": "2019-03-26T11:00:00Z",
"lastPaymentDates": null,
"billingInterval": 1,
"billingCycle": "DAILY",
"planName": "Premium",
"amount": {
"value": 2,
"currency": "INR"
}
}
],
"createdDate": "2019-03-24T06:56:53.871Z",
"modifiedDate": "2019-03-24T06:56:53.878Z",
"status": "Enabled",
"customParameter": {
"Policynumber": "12743123111",
"Policytype": "Life Insurance"
},
"possibleActions": [
{
"action": "Update Subscription",
"href": "{{base-url}}/api/sub/v1/subscription/5c972a35652d405ed9834f52",
"httpMethod": "PATCH"
},
{
"action": "Fetch Subscription",
"href": "{{base-url}}/api/sub/v1/subscription/5c972a35652d405ed9834f52",
"httpMethod": "GET"
},
{
"action": "Delete Subscription",
"href": "{{base- url}}/api/sub/v1/subscription/5c972a35652d405ed9834f52",
"httpMethod": "DELETE"
}
]
}
Response parameters
| Parameter | Description |
|---|---|
| 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” |
HTTP response codes
| HTTP Status Code | Description |
| 201 | Subscription defined successfully |
| 403 | Forbidden request invalid Signature |
| 400 | Request is malformed |
| 404 | Merchant or Plan Id not found |
| 422 | Request has invalid values |
| 500 | Interval Server Error |
Sample response
| Request body | Subscription Status | Plan Status |
|---|---|---|
| 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 |