We discussed a use case of ADHOC plan during Subscription understanding where not fixed billing interval and amount is available. A classic use case for this is Postpaid Billing where bill is generated as per consumption. The sample plan is similar to the following:
{
"planId": "ZION155345026687548",
"startDate": null,
"totalCount": 0,
"numberOfPaidInvoices": 0,
"numberOfInvoiceGenerated": 0,
"status": "Inactive",
"deleted": false,
"nextBillingDates": null,
"lastPaymentDates": null,
"billingInterval": 0,
"billingCycle": "ADHOC",
"planName": "Premium",
"amount": {
"value": 200,
"currency": "INR"
}
}
Zion handles this use cases where merchant must trigger Invoice API to charge the customer and keeps adding value by providing set of features like -
- Smart retries
- Multiple plan association
- Comprehensive Subscription management panel
- Change of payment instrument
- Payment link generation
Post Method: POST
Path: {base_url}/api/sub/v1/merchant/invoices/createInvoice
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 guidelines. |
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 |
| planId mandatory | 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. Example: 5b7a4ab8652d403c088fdeef. |
| subscriptionId mandatory | Unique subscription ID generated by Zion for given customer and needs to be stored by merchant in his system. Example: 5b7a4ab8652d403c088fdeef |
| refId mandatory | Unique transaction id generated by merchant for given charge request. This must be unique for every request |
| subscriberEmail mandatory | Email address of the subscriber. Mandatory for selected issuers in case of Debit card SI |
| amount mandatory | Invoice amount object which needs to be charged to customer. This should be either equal or lesser than amount which is defined during plan association. |
| value mandatory | Amount in XX.XX format Example: 200.00 or 125.24 or 1000.50 |
| currency mandatory | Billing currency. Include INR for Indian currency. Note: Currently, only supported INR. |
| customParameter mandatory | Key-value pairs to associate any extra info with customer’s subscription. |
X-PayU-Subscription-Signature generation guidelines
X-PayU-Subscription-Signature is SHA 512 signature used to provide security layer over existing APIs. Every API will have its own logic to generate X-PayU-Subscription- Signature logic. Let’s look at how it is calculated for Define Subscription API
Signature = SHA512(“merchantId:” + merchantId + "|subscriptionId:" + subscriptionId + "|planId:" + planId + "|refId:" + refId + "|amount:" + amount + "|currency:" + currency + "|" + merchantSalt)
Example
SHA512(merchantId:YQeVda|subscriptionId: 5bc071183114ad6d943ef053|planId:ZION15393385191|refId:IN123123123|amount:20. 00|currency:INR|1v9b1)
The response is similar to the following:
471f00cd693f6222649c57550cf9881ae6c1d9ad46a757e917db8a4c88ce5d675ed2029a 5bb9582bd451fd51e90b5cffb6870718bae79e15538afe0d1d640cea
Sample request
{
"merchantId": "YQeVda",
"planId": "ZION15393385191",
"refId": "IN123123123",
"subscriptionId": "5bc071183114ad6d943ef053",
"amount": {
"value": "20.00",
"currency": "INR"
}
}
Sample response
{
"merchantId": "YQeVda",
"subscriptionId": "5bc071183114ad6d943ef053",
"invoiceId": "5c9a16acba83015afcd967a7",
"amount": {
"value": 20,
"currency": "INR"
},
"refId": " IN123123123"
}
Response parameters
| Parameter | Description |
|---|---|
| subscriptionId | Unique subscription id echoed back by Zion |
| merchantId | Merchant Key echoed back by Zion |
| invoiceId | Unique Invoice Id generated by Zion for given Invoice Id. This needs to be stored by merchant in his system for further reference |
| refId | Unique transaction Id generated by merchant echoed back by Zion |
| amount | Invoice amount and currency echoed back by Zion |
HTTP Codes
| HTTP Status Code | Description |
|---|---|
| 201 | Invoice 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 |
| 409 | Invalid Amount scenario |
| 412 | refId is not unique |
Note:
Zion Invoices comes with default retry of three days, merchant can contact customer once all the retry attempts are exhausted and invoice failed notification is triggered by Zion.
After invoiceId is returned by Zion, that invoice is now scheduled for charging customer account and it follows similar process of notification which is explained earlier. So, merchant will get response of the invoice as either of the following notification type:
- INVOICE_DUE_HTTP – When invoiceId is generated and request is registered by Zion
- INVOICE_PAID_HTTP – When generated invoiceId is paid successfully
- INVOICE_FAILED_HTTP – When generated invoiceId is failed after 3 retry attempts till next 3 days
For sample of the above listed notification, refer to Manage Invoice APIs.