Create Plan API

Merchant can create Plan from PayU’s dashboard or by calling “Create Plan” API. Here are essentials of the plan -

  • Amount - Recurring amount which needs to be charged to the customer.
  • Billing Cycle - Frequency with which amount needs to be charged like Daily, Weekly, Monthly, Yearly or Once
  • Billing Interval - How often customer needs to be charged for defined Billing Cycle and Amount

Environment

HTTP Method: POST

Path: {base_url}/api/sub/v1/merchant/plans

Request parameters

Header

ParameterDescripption
Content-Type
mandatory
application/json
X-PayU-Subscription- Signature
mandatory
SHA512 Signature generated by encrypting request parameters in body by Merchant Key, Merchant Salt, Billing Amount, Billing Cycle and Billing Interval.

Body

ParameterDescription
merchantId
mandatory
merchant key received from PayU’s team during on- boarding process.
Example: Ysr1r
planNameName of the Plan. This name will be reflected on PayU’s panel for further reference.

Sample value – Premium Plan
planDescription
optional
Description of the plan if wanted to be associated with plan creation.

Sample value – “Premium plan for 5 sessions per user”
amount
mandatory
Amount node to capture value and currency as described in below parameters
value
mandatory
Billing amount in XX.XX format

Sample value – 200.00 or 125.24 or 1000.50
currency
mandatory
Billing currency

Currently supported only as INR
billingCycle
mandatory
Billing Cycle

Whether customer needs to be charged over Daily basis, Weekly basis, Monthly basis, Yearly basis or one time.

Sample Values –

_ DAILY
_ WEEKLY
_ MONTHLY
_ YEARLY
* ONCE
billingInterval
mandatory
Billing Interval Closely coupled with value of “billingCycle” and denotes at what frequency, the subscription plan needs to be executed.

For example, if we want to run a bi weekly charge on customer’s card then value will be billingCycle = WEEKLY and billingInterval = 2

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

Similarly, by keeping value of billingInterval = 6 and billingCycle = MOHTHLY, customer will be charged once in every 6 months.

For monthly subscriptions, value to be used as billingCycle = MOHTHLY and billingInterval = 1

Sample value = X
customParameter
optional
Key value pair if we want to associate some specific information with the plan

Sample value –

"language": "English", “region”: “Goa”

Sample request

POST** – [_https://subscriptiontest.citruspay.com/api/sub/v1/merchant/plans_](https://subscriptiontest.citruspay.com/api/sub/v1/merchant/plans)
Content-Type** – _application/json_
X-PayU-Subscription-Signature** – _5356d1e622f9cbf6a9fe60f073ac4f4a73aeb684212d5dfe19ed704e918e225cb500a4fe4 e5428f42b653c7d36ccf4d0cb7888d0759cd4e8c76ef5684e655e22_

Request body

{
  "merchantId": "Ysr1r",
  "planName": "Premium",
  "planDescription": "This is premium plan for region Goa",
  "amount": {
    "value": "200.00",
    "currency": "INR"
  },
  "billingInterval": 2,
  "billingCycle": "WEEKLY",
  "customParameter": {
    "language": "English",
    "region": "Goa"
  }
}

Sample response

On posting valid request body, Zion creates a plan at the back-end and generates unique plan id which is returned to merchant over same API connection. Here is sample response.

{
  "merchantId": "Ysr1r",
  "planId": "5aa26aa1fbea353c71802577",
  "planDescription": "This is premium plan for region Goa",
  "planName": "Premium",
  "amount": {
    "value": 200,
    "currency": "INR"
  },
  "billingInterval": 2,
  "billingCycle": "WEEKLY",
  "createdDate": "2018-08-14T11:24:19.020Z",
  "status": "ACTIVE",
  "customParameter": {
    "language": "English",
    "region": "Goa"
  },
  "possibleActions": [
    {
      "action": "GetPlan",
      "href": "{base_url}/v1/merchant/plans/{planId}",
      "method": "GET"
    },
    {
      "action": "DeletePlan",
      "href": "{base_url}/v1/merchant/plans/{planId}",
      "method": "DELETE"
    }
  ]
}

Response parameters

ParameterDescription
merchantIdMerchant key echoed back in the response


 

Sample value – Ysr1r
planIdUnique plan id generated by Zion and needs to be Stored by merchant for given plan. This plan id will be used as a reference all the other APIs.
Example: 5aa26aa1fbea353c71802577
planDescriptionDescription of the plan echoed back in the response
planNameName of the plan echoed back in the response
amountAmount associated with the plan echoed back in the response
valueAmount value associated with the plan echoed back in the response
currencyAmount currency associated with the plan echoed back in the response
billingIntervalBilling Interval associated with the plan echoed back in the response
billingCycleBilling Cycle associated with the plan echoed back in the response
createdDateCreated Date of the plan returned from Zion. It is in by default UTC time zone.
Example: 2018-08-14T11:24:19.020Z_
statusStatus of the plan which is returned as “ACTIVE” once plan is successfully created.
Example: ACTIVE
customParameterValue of custom parameters echoed back in the response.
possibleActionsPossible actions help merchants to identify what is allowed on created plan. So, in given example, GetPlan and DeletePlan interfaces can be supported over generated plan id.
  • On successful processing from PayU end for captured transactions, the HTTP Status Code is similar to the following:
HTTP Status CodeDescription
201Plan is created successfully
403Forbidden request
400Request is malformed
404Merchant not found
422Request has invalid values
500Interval Server Error