Subscriptions API

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials. X-Client-Id is your appID, and X-Client-Secret is your secretKey. You can view these details here.

All API responses are in JSON format. POST requests should include ContentType: application/json

Endpoints

Environment

URL

Test

https://test.cashfree.com/

Production

https://api.cashfree.com/

Postman Collection

Get started quickly with Cashfree Subscription APIs by downloading the following collection and importing it in Postman.

Quick Reference

URL

HTTP Verb

Functionality

/api/v2/subscription-plans

POST

To create plans

/api/v2/subscriptions

POST

To create subscriptions

/api/v2/subscriptions

POST

To create seamless subscriptions

/api/v2/subscriptions/:subReferenceId

GET

To get subscription details

/api/v2/subscriptions/:subReferenceId/payments?lastId=:lastId&count=:count

GET

To get all subscription payments

/api/v2/subscriptions/:subReferenceId/payments/:paymentId

GET

To get single subscription payment

/api/v2/subscriptions/:subReferenceId/cancel

POST

To cancel subscriptions

/api/v2/subscriptions/:subReferenceId/charge

POST

To charge on-demand subscriptions

<Post> Create Plan

To create a new plan on Cashfree, send a POST request to the class URL containing the contents of the plan.

/api/v2/subscription-plans

Request Parameters

Parameter

Required

Description

planId

Yes

Unique identifier for the plan (Alphanumeric)

planName

Yes

Specify plan name for easy reference (Alphanumeric)

type

Yes

The type can be PERIODIC or ON_DEMAND. For more details refer to Appendix 1 for description (Alphanumeric)

maxCycles

Optional

Maximum number of debits set for the plan. The subscription will automatically change to COMPLETED status once this limit is reached (Numeric)

amount

Optional

The amount to be charged for PERIODIC plan (Numeric)

maxAmount

Optional

The maximum amount to be charged for ON_DEMAND plan (Numeric)

intervalType

Optional

The type of interval for a PERIODIC plan like daily, weekly, monthly, yearly (Alphanumeric)

intervals

Optional

Number of intervals of intervalType between every subscription payment. For example for charging a customer bi-weekly use intervalType as “week” and intervals as 2. Required for PERIODIC plan (Numeric)

description

Optional

A brief note for the plan (Alphanumeric)

Request and Response Sample

Request

For POST requests, Content-Type header should be set to application/json.

Authentication is done via parameters. The appId parameter identifies which merchant account you are accessing, and the secretKey parameter authenticates the endpoint.

curl -XPOST -H 'cache-control: no-cache' -H 'content-type: application/json' -H
'X-Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876' -d '{
"planId":"BASIC", "planName":"Basic subscription plan", "amount":12,
"intervalType":"week", "intervals":2,"description":"This is the standard plan
for our services"}' 'https://test.cashfree.com/api/v2/subscription-plans'

Response

The response format for all requests is a JSON object.

{
"status":"OK",
"message":"Subscription Plan created successfully"
}

<Post> Create Subscription

You can now easily create a subscription as per the plan created in the previous step.

The Auth Link will be redirected to a link hosted on cashfree.com. Once the authorization is complete, your customer will be redirected to returnUrl. Store the subReferenceId as this is the unique id generated by Cashfree for the subscription and will be required for subsequent operations.

/api/v2/subscriptions

Request Parameters

Below are the Post Parameters.

Parameter

Required

Description

subscriptionId

Yes

A unique id generated for subscription (Alphanumeric)

planId

Yes

Id of a valid plan created earlier (Alphanumeric)

customerName

Optional

Name of the customer (Alphanumeric)

customerEmail

Yes

Email of the customer (Alphanumeric)

customerPhone

Yes

Contact number of the customer (Numeric)

firstChargeDelay

Optional

Number of Days after which the first debit for subscription will occur.Applicable for periodic subscriptions only (Numeric)

authAmount

Optional

The amount that will be charged to authenticate the payment. The default amount is Re. 1 (Numeric)

expiresOn

Required

The last date till which the subscription stands valid. The status of subscription will be COMPLETED. Default value is 2 years from date of subscription creation. Format is “yyyy-mm-dd hr:min:sec” (Alphanumeric)

returnUrl

Yes

A valid url to which customer will be redirected to after the subscription is done. Refer “Payment Response” section (Alphanumeric)

subscriptionNote

Optional

A brief note about the subscription (Alphanumeric)

Request and Response Sample

Request

curl -XPOST -H 'cache-control: no-cache' -H 'content-type: application/json' -H
'X-Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876' -d
'{"subscriptionId":"sub1", "planId":"BASIC", "customerEmail":"test@gmail.com",
"customerPhone":"9900012345"}' 'https://test.cashfree.com/api/v2/subscriptions'

Response

{
"status":"OK",
"message":"Subscription created successfully",
"subReferenceId": 123,
"authLink":"https://bit.ly/1234qwer"
}

<Post> Create Seamless Subscription

You can also create a subscription in a seamless manner. This allows you to provide your own payment experience to your customers. With this, you can collect all payment details on your webpage and safely send them to Cashfree for processing. The authLink here will redirect the customer to the 2FA page of the issuer/destination bank.

/api/v2/subscriptions

General Pointers

Store the subReferenceId as this is the unique id generated by Cashfree for the subscription. It will be required for subsequent operations.

It is recommended that the checkout page showcases all the subscription and payment details so that the customer can make an informed decision. For e-mandates, the NPCI guidelines state that the checkout information should include but are not limited to the following

  • First ordered list item

  • Account type - Savings or Current

  • Bank Name

  • Customer Name

  • Recurring payment details: This should include the following information

    a. Frequency of the subscription

    b. Recurring amount/Maximum amount

    c. Last Payment date

    d. Purpose of the Subscription

Mapping for BankId

Bank ID

Bank Name

ANDB

ANDHRA BANK

BARB

BANK OF BARODA

CBIN

CENTRAL BANK OF INDIA

CIUB

CITY UNION BANK LTD

CNRB

CANARA BANK

COSB

Cosmos Bank

DEUT

DEUTSCHE BANK AG

DLXB

DHANALAXMI BANK

ESFB

EQUITAS SMALL FINANCE BANK LTD

FDRL

FEDERAL BANK

HDFC

HDFC BANK LTD

IBKL

IDBI BANK LTD

ICIC

ICICI BANK LTD

IDFB

IDFC Bank

INDB

INDUSIND BANK

IOBA

INDIAN OVERSEAS BANK

KARB

KARNATAKA BANK LTD

KKBK

KOTAK MAHINDRA BANK LTD

MAHB

BANK OF MAHARASHTRA

ORBC

ORIENTAL BANK OF COMMERCE

PUNB

PUNJAB NATIONAL BANK

PYTM

PAYTM PAYMENTS BANK LTD

RATN

RBL BANK LIMITED

SBIN

STATE BANK OF INDIA

SCBL

STANDARD CHARTERED BANK

TMBL

TAMILNAD MERCANTILE BANK LTD

UBIN

UNION BANK OF INDIA

USFB

UJJIVAN SMALL FINANCE BANK LTD

UTIB

AXIS BANK

YESB

YES BANK

SIBL

SOUTH INDIAN BANK

DBSS

DBS BANK INDIA LTD

JSFB

JANA SMALL FINANCE BANK LTD

HSBC

THE HONGKONG AND SHANGHAI BANKING CORPORATION LTD

SYNB

SYNDICATE BANK

PSIB

PUNJAB AND SIND BANK

KVBL

KARUR VYSA BANK

Request Parameters

Below are the Post Parameters.

Parameter

Required

Description

subscriptionId

Yes

A unique id generated for subscription (Alphanumeric)

planId

Yes

Id of a valid plan created earlier (Alphanumeric)

customerName

Optional

Name of the customer (Alphanumeric)

customerEmail

Yes

Email of the customer (Alphanumeric)

customerPhone

Yes

Contact number of the customer (Numeric)

firstChargeDelay

Optional

Number of Days after which the first debit for subscription will occur.Applicable for periodic subscriptions only (Numeric)

authAmount

Optional

The amount that will be charged to authenticate the payment. The default amount is Re. 1 (Numeric)

expiresOn

Optional

The last date till which the subscription stands valid. The status of subscription will be COMPLETED. Default value is 2 years from date of subscription creation. Format is “yyyy-mm-dd hr:min:sec” (Alphanumeric)

returnUrl

Yes

A valid url to which customer will be redirected to after the subscription is done. Refer “Payment Response” section (Alphanumeric)

subscriptionNote

Optional

A brief note about the subscription (Alphanumeric)

paymentOption

Optional

Use “emandate/card”. This is the only valid option currently (Alphanumeric)

card_number

Optional

16 digit long valid card number (Numeric)

card_expiryMonth

Optional

Month of expiration of card in MM format (Numeric)

card_expiryYear

Optional

Year of expiration of card in YYYY format (Numeric)

card_cvv

Optional

The CVV of the card (Numeric)

card_holder

Optional

The name on the card (Alphanumeric)

emandate_accountHolder

Optional

Account Holder’s name

emandate_accountNumber

Optional

Account Number

emandate_bankId

Optional

The bank with the account is held. Check reference for the possible values

emandate_authMode

(optional)

Possible values - debitCard/netbanking.

Default is netbanking.

emandate_accountType

(optional)

Possible values - SAVINGS/CURRENT.

Default is SAVINGS.

Possible Values for Bank ID

If emandate_authMode is NetBanking:

If emandate_authMode is debitCard:

ANDB, BARB, CBIN, CIUB, CNRB, COSB, DEUT, DLXB, ESFB, FDRL, HDFC, IBKL, ICIC, IDFB, INDB, IOBA, KARB, KKBK, MAHB, ORBC, PUNB, PYTM, RATN, SBIN, SCBL, TMBL, UBIN, USFB, UTIB, YESB, SIBL, DBSS, JSFB, HSBC, SYNB, PSIB, KVBL

ANDB, AUBL, CITI, DCBL, DEUT, DLXB, ESFB, FDRL, HDFC, ICIC, IDFB, INDB, KARB, KKBK, MAHB, PUNB, PYTM, RATN, SBIN, SIBL, USFB, YESB, DBSS, TMBL, UTIB, BARB, JSFB

Request and Response Sample

Request

curl -XPOST -H 'cache-control: no-cache' -H 'content-type: application/json' -H
'X-Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876' -d
'{"subscriptionId":"sub1", "planId":"ON_DEMAND",
"customerEmail":"test@gmail.com", "customerPhone":"9900012345",
"paymentOption":"card", "card_number": "4434260000000008", "card_expiryMonth" :
"05", "card_expiryYear" : "2021", "card_cvv":"123", "card_holder": "Nafey"}'
'https://test.cashfree.com/api/v2/subscriptions'

Response

{
"status":"OK",
"message":"Subscription created successfully",
"subReferenceId": 123,
"authLink":"https://bit.ly/1234qwer"
}

<Get> Fetch Subscription Details

You can extract the details of the subscription when required.

/api/v2/subscriptions/:subReferenceId

Request Parameters

Below is the URL Parameter.

Parameter

Required

Description

subReferenceId

Yes

A unique Id which was generated when the subscription was created (Numeric)

Request and Response Sample

Request

curl -i -H 'cache-control: no-cache' -H 'content-type: application/json' -H 'X-
Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876'
'https://test.cashfree.com/api/v2/subscriptions/123'

Response

{
"status":"OK",
"message":"Subscription Details",
"subscription": {
"subscriptionId": "sub1",
"subReferenceId": "123",
"planId": "BASIC",
"customerName": "",
"customerEmail": "test@gmail.com",
"customerPhone": "9900012345",
"mode": "CREDIT_CARD",
"cardNumber":"411111XXXXXX1111",
"status": "INITIALIZED",
"addedOn": "2018-01-01 12:23:34",
"scheduledOn": "2018-02-01 09:00:00",
"currentCycle": 14
}
}
  • Card Number is available only when payment is done by credit card.

  • Status values and their description are listed in Appendix 1a.

  • Current cycle shows how many payments have been initiated for the subscription.

  • scheduledOn will be null for ON_DEMAND type subscriptions.

<Get> Fetch All Subscription Payments

You can fetch all the payment details for a subscription with just one request.

/api/v2/subscriptions/:subReferenceId/payments?lastId=:lastId&count=:count

Request Parameters

Below are the URL Parameters.

Parameter

Required

Description

subReferenceId

Yes

A unique Id which was generated when the subscription was created (Numeric)

lastId

Optional

The pagination counter to return results from (Numeric)

count

Optional

The total number of payments to be shown in a paginated query (Numeric)

Request and Response Sample

Request

curl -i -H 'cache-control: no-cache' -H 'content-type: application/json' -H 'X- Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876' 'https://test.cashfree.com/api/v2/subscriptions/123/payments?last=114&count=2'

Response

{
"status":"OK",
"message":"Subscription Payments",
"payments":
[{
"paymentId": 113,
"cycle": 15,
"amount": 12,
"status": "SUCCESS",
"addedOn": "2018-01-20 12:23:34"
},{
"paymentId": 112,
"cycle": 14,
"amount": 12,
"status": "SUCCESS",
"addedOn": "2018-01-19 12:23:34"
}],
"lastId": 112
}
  • lastId and count help in paginating queries for ease of use. Every query returns "count" number of payments. To fetch next page set lastId of the previous page. To get first page do not include lastId in the request

  • Cycle indicates after how many intervals was this payment processed.

  • Payment status field values are described in Appendix 1b.

<Get> Fetch Single Subscription Payment

You can fetch the details of a particular payment of the subscription.

/api/v2/subscriptions/:subReferenceId/payments/:paymentId

Request Parameters

Below are the URL Parameters.

Parameter

Required

Description

subReferenceId

Yes

A unique Id which was generated when the subscription was created (Numeric)

paymentId

Yes

A unique Id for the payment (Numeric)

Request and Response Sample

Request

curl -i -H 'cache-control: no-cache' -H 'content-type: application/json' -H 'X- Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876' 'https://test.cashfree.com/api/v2/subscriptions/123/payments/113'

Response

{
"status":"OK",
"message":"Subscription Payments",
"payment":
{
"paymentId": 113,
"cycle": 15,
"amount": 12,
"status": "SUCCESS",
"addedOn": "2018-01-20 12:23:34"
}
}
  • Payment Id is generated at every payment.

  • Cycle indicates after how many intervals was this payment processed.

  • Payment status field values are described in Appendix 1b.

<Post> Cancel Subscription

You can cancel the subscription at any point so that the subscription will no longer be charged to your customer. Subscription once cancelled cannot be reactivated. The status of the subscription will be CANCELLED.

/api/v2/subscriptions/:subReferenceId/cancel

Request Parameters

Below is the URL Parameter.

Parameter

Required

Description

subReferenceId

Yes

A unique Id which was generated when the subscription was created (Numeric)

Request and Response Sample

Request

curl -XPOST -H 'cache-control: no-cache' -H 'content-type: application/json' -H
'X-Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876'
'https://test.cashfree.com/api/v2/subscriptions/123/cancel'

Response

{
"status":"OK",
"message":"Subscription Cancelled"
}

<Post> Charge Subscription

For an ON-DEMAND plan, you will have to explicitly debit customers account. The customer will receive a notification from their respective bank regarding the payment.

/api/v2/subscriptions/:subReferenceId/charge

Request Parameters

Below is the URL Parameter.

Parameter

Required

Description

subReferenceId

Yes

A unique Id which was generated when the subscription was created (Numeric)

Below are the Post Parameters.

Parameter

Required

Description

amount

Yes

The amount which will be debited from the customer (Numeric)

remarks

Optional

Details of this payment (Alphanumeric)

Request and Response Sample

Request

curl -XPOST -H 'cache-control: no-cache' -H 'content-type: application/json' -H
'X-Client-Id: asdf1234' -H 'X-Client-Secret: qwer9876' -d '{"amount":"12"}'
'https://test.cashfree.com/api/v2/subscriptions/123/charge'

Response

{
"status":"OK",
"message":"Subscription charged",
"payment": {
"paymentId": 113,
"amount": 12,
"status": "SUCCESS",
"addedOn": "2018-01-20 12:23:34"
}
}

Payment Response

When a subscription is created a returnUrl is provided as a part of the request. When the customer authorizes the payment, he will be redirected to the returnURL. This redirection is done a POST request with the following parameters.

Request Configuration

Method

URL

cf_subReferenceId

Unique Id which was generated when the subscription was created (Numeric)

cf_subscriptionId

Checksum used to authenticate the transaction (Alphanumeric)

cf_authAmount

The money that was charged to authorize the subscription (Numeric)

cf_orderId

The PG Order created for authorization (Alphanumeric)

cf_referenceId

The referenceId/transactionId of authorization in PG (Numeric)

cf_status

Status of the subscription. In the returnUrl, the response should be ACTIVE if the authorization was successful or INITIALIZED if the authorization failed (Alphanumeric)

cf_message

A brief note about the payment (Alphanumeric)

signature

The hash of all parameters in request generated using secretKey. Refer Appendix 2 for details (Alphanumeric)

Webhook Support

  • Contact care@cashfree.com to configure your Webhook endpoint.

  • Make sure that you don’t process duplicate events. For instance, if you have already received a success response the Subscription API call. Discard any identical Subscription success events for the corresponding API.

  • Please note that there might be new events added in the future.

Webhook will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type. Here are the various events that can be sent to your webhook endpoint:

SUBSCRIPTION_STATUS_CHANGE

Parameter

Description

cf_event

The event for which the subscription was authorized. The value for this event is SUBSCRIPTION_STATUS_CHANGE( Alphanumeric)

cf_subReferenceId

A unique Id which was generated when the subscription was created (Numeric)

cf_status

The new status of the subscription. Refer Appendix 1 for more subscription status values (Alphanumeric)

cf_lastStatus

The old status of the subscription. Refer Appendix 1 for the description of different subscription status values (Alphanumeric)

cf_eventTime

The time when the event was dispatched (Alphanumeric)

signature

The hash of all parameters in request generated using secretKey. Refer Appendix 2 for details (Alphanumeric)

SUBSCRIPTION_NEW_PAYMENT

Parameter

Description

cf_event

The event for which the subscription was authorized. The value for this event is SUBSCRIPTION_NEW_PAYMENT (Alphanumeric)

cf_subReferenceId

A unique Id which was generated when the subscription was created (Numeric)

cf_paymentId

The unique paymentId for the payment (Alphanumeric)

cf_amount

The amount of money charged for payment (Numeric)

cf_eventTime

The time when the event was dispatched (Alphanumeric)

signature

The hash of all parameters in request generated using secretKey. Refer Appendix 2 for details (Alphanumeric)

SUBSCRIPTION_PAYMENT_DECLINED

Parameter

Description

cf_event

The event for which the subscription was authorized. The value for this event is SUBSCRIPTION_PAYMENT_DECLINED (Alphanumeric)

cf_subReferenceId

A unique Id which was generated when the subscription was created (Numeric)

cf_paymentId

The unique paymentId for the payment (Alphanumeric)

cf_amount

The amount of money charged for payment (Numeric)

cf_reasons

A possible reason for failure (Alphanumeric)

cf_eventTime

The time when the event was dispatched (Alphanumeric)

signature

The hash of all parameters in request generated using secretKey. Refer Appendix 2 for details (Alphanumeric)

Appendix 1

Subscription Status

For subscriptions through e-mandates (bank accounts), it takes 1 to 2 working days to activate the subscription. For subscriptions through cards, it is activated instantly.

A description of all possible status for a subscription.

Status

Description

INITIALIZED

The subscription has just been created and is ready to be authorized by the customer.

BANK_APPROVAL_PENDING

E-Mandate has been authorised and registration is pending at the Bank. This status is specific for e-mandates.

ACTIVE

The customer has authorized the subscription and will be debited accordingly.

ON_HOLD

The subscription failed due to insufficient funds, expiration of payment method, and so on.

CANCELLED

The subscription was cancelled by the merchant and can no longer be activated.

COMPLETED

The subscription has completed its total active period.

Payment Status

It takes 1 to 2 working days for the transactions to be complete through e-mandates, and through cards it is instant.

A description of all possible status for a subscription payment.

Status

Description

SUCCESS

Payment for subscription was processed successfully.

PENDING

Payment for subscription was attempted but not yet marked successful. This status is specific for e-mandates.

FAILED

Payment failed for subscription.

Plan Types

A description of all the various different subscription plan types that are available currently and their operation model.

Status

Description

PERIODIC

Payments are triggered automatically at fixed intervals defined by the merchant

ON_DEMAND

Merchant needs to trigger /charge the customer explicitly with the required amount.

Appendix 2

Use the following examples as illustrations for how to generate a signature. If the language you are using is not mentioned here, contact us at care@cashfree.com.

Do not go live without signature verification.

Pseudo Code
PHP
JAVA
Pseudo Code
data = "";
iterate keys as key in POST request alphabetically:
if (key starts with "cf_"):
data = data + key + POST[key]
computedSignature = base64 of (hash of (data) with secretKey as hashKey)
if (computedSignature != POST["signature"]):
// An invalid/fraud request do not mark subscription as successfull
PHP
<?php
$data = "";
$postData = $_POST;
ksort($postData);
foreach ($postData as $key => $value) {
if (substr($key, 0, 3) == "cf_") {
$data .= $key . $value;
} }
$hash_hmac = hash_hmac('sha256', $data, $secretkey, true) ;
$computedSignature = base64_encode($hash_hmac);
if ($postData["signature"] != $computedSignature) {
// An invalid/fraud request do not mark subscription as successfull
}
?>
JAVA
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;
import java.util.*;
public class ChecksumServlet extends HttpServlet {
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
try {
String secretKey = "ac7960e7995536f0177fd210f3b3937fc2d974a4";
Map<String, String[]> postData = request.getParameterMap();
// ensuring appId gets initialized
String data = "";
SortedSet<String> keys = new TreeSet<String>(postData.keySet());
for (String key : keys) {
if ((key.length() > 3) && (key.substring(0, 3).equals("cf_"))) {
data = data + key + ((String[])postData.get(key))[0];
}
}
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key_spec = new
SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
sha256_HMAC.init(secret_key_spec);
String computedSignature =
Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
if (!computedSignature.equals(postData.get("signature"))) {
// An invalid/fraud request do not mark subscription as successfull
} }
catch (Exception ex) {
// handle
} }
}