Create Invoice API

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


Request parameters


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.


The request body parameters to create a subscription request are:

Merchant key received from PayU’s team during the onboarding process.
Example: smsplus
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.
Unique subscription ID generated by Zion for given customer and needs to be stored by merchant in his system.
Example: 5b7a4ab8652d403c088fdeef
Unique transaction id generated by merchant for given charge request. This must be unique for every request
Email address of the subscriber. Mandatory for selected issuers in case of Debit card SI
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.
Amount in XX.XX format
Example: 200.00 or 125.24 or 1000.50
Billing currency. Include INR for Indian currency.
Note: Currently, only supported INR.
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)


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

subscriptionIdUnique subscription id echoed back by Zion
merchantIdMerchant Key echoed back by Zion
invoiceIdUnique Invoice Id generated by Zion for given Invoice Id. This needs to be stored by merchant in his system for further reference
refIdUnique transaction Id generated by merchant echoed back by Zion
amountInvoice amount and currency echoed back by Zion

HTTP Codes

HTTP Status CodeDescription
201Invoice defined successfully
403Forbidden request invalid Signature
400Request is malformed
404Merchant or Plan Id not found
422Request has invalid values
500Interval Server Error
409Invalid Amount scenario
412refId is not unique



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.