Getting Started

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

See the screenshots for each step below :

Step 1

Creating Subscription Plans in Cashfree Merchant Dashboard

Under Subscriptions -> Plans -> Use the New Plan button to get started.

The New Plan dialog allows you to create a new subscription plan. Here are the details you need to fill out to create a new subscription plan:

The Create a Plan section has all subscription plan information Cashfree needs, to create a new subscription plan including Plan Id, Plan Name, Description, Plan Type, Interval Type & Amount.

The Plan ID field is used to uniquely identify the subscription plan. (Refer to our API for more details)[https://docs.cashfree.com/docs/sbc/guide/#create-plan].

The Subscription Plan section captures information related to the plan you would like to subscribe the customer to:

  • Plan Id & Plan Name fields are used to set a unique plan Id as well as name for the subscription plan. These fields are mandatory.
  • The Amount field allow you to set the price of the plan.

Step 2

Creating Subscriptions in Cashfree Merchant Dashboard

Under Subscriptions -> View Subscriptions -> Use the New Subscription button to create a new Subscription.

The Create a Subscription dialog allows you to create a new subscription. Here are the details you need to fill out to create a new subscription:

The Subscription Id is a unique identifier for the subscription. (Refer to our API for more details)[https://docs.cashfree.com/docs/sbc/guide/#create-subscription].

The Subscription section captures information related to the plan you would like to subscribe the customer to:

  • Subscription Id & Plan fields are used to set a unique subscription Id as well as select the subscription plan (which was created on Step 1). These fields are mandatory.
  • The Customer Email & Customer Phone fields allow you to set the email and phone number of the customer.

Step 3

Once you click on Create in Step 2, you will see a new dialog (like below screenshot).

Step 4

If you visit the Authorization Link you will see the Authorization page for the Subscription (like below screenshot).


Create Plan

Allows you to create plan which can be later attached to subscriptions.

Request Configuration

Type Value
HTTP Method POST
URL /api/v2/subscription-plans
Content-Type application/json

Headers

Type Value
X-Client-Id appId
X-Client-Secret secretKey

Post Params

Parameter Required Description
planId Yes Alphanumeric. A merchant supplied identifier for this plan.
planName Yes Alphanumeric. A human readable plan name
type Yes Alphanumeric. The type of plan. Refer to Appendix 1C for description.
maxCycles Optional Numeric. Maximum number of debits that are possible for this plan. The subscription will automatically change to COMPLETED status once this limit is reached.
amount Optional Numeric. The amount to be charged at every interval. Required for PERIODIC plan.
maxAmount Optional Numeric. The maximum amount to be charged on ON_DEMAND. Required for ON_DEMAND plan.
intervalType Optional Alphanumeric. The type of interval for a PERIODIC plan. Can be “week”, “month”, “day”, “year”. Required for PERIODIC plan.
intervals Optional Numeric. Number of intervals of intervalType between every subscription payment. For example for charging customer bi weekly use intervalType as “week” and intervals as 2. Required for PERIODIC plan.
description Optional Alphanumeric. A description of the plan.

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 '{
"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'

Sample Response

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

Create Subscription

Allows you to create subscription.

Request Configuration for Create Subscription

Type Value
HTTP Method POST
URL /api/v2/subscriptions
Content-Type application/json

Headers for Create Subscription

Type Value
X-Client-Id appId
X-Client-Secret secretKey

Post Params for Create Subscription

Parameter Required Description
subscriptionId Yes Alphanumeric. A unique merchant generated id for subscription.
planId Yes Alphanumeric. planId of a valid plan.
customerName Optional Alphanumeric. Name of the customer.
customerEmail Yes Alphanumeric. Email of the customer.
customerPhone Yes Numeric. Mobile number of the customer.
firstChargeDelay Optional Numeric. Applicable for periodic subscriptions only. Number of Days when the first charge for subscription will happen.
authAmount Optional Numeric. The amount that will be charged to authenticate the payment. This amount will be default to Rs. 1 if not provided
expiresOn Required Alphanumeric. Date after which this subscription should expire. The subscription will subsequently be in a COMPLETED status. Default value is 2 years from date of subscription creation.
returnUrl Yes Alphanumeric. A valid url to which customer will be redirected to after the subscription is done. See “Payment Response” section.
subscriptionNote Optional Alphanumeric. A short note for this subscription.

Sample Request for Create Subscription

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'

Sample Response for Create Subscription

{
  "status":"OK",
  "message":"Subscription created successfully",
  "subReferenceId": 123,
  "authLink":"https://bit.ly/1234qwer"
}
  • Auth Link will redirect to a link hosted on cashfree.com. Once the authorization is completed the customer will be redirected to returnUrl.
  • Please store the subReferenceId on your end. This is the Cashfree generated unique id for this subscription and will be used in subsequent operations

Create Subscription (Seamless)

Allows you to create payment links for seamless subscription authentication. Provide the card details while creating subscription. The authLink will directly redirect customer to bank 2FA page.

Request Configuration for Seamless Create Subscription

Type Value
HTTP Method POST
URL /api/v2/subscriptions
Content-Type application/json

Headers for Seamless Create Subscription

Type Value
X-Client-Id appId
X-Client-Secret secretKey

Post Params for Seamless Create Subscription

Parameter Required Description
subscriptionId Yes Alphanumeric. A unique merchant generated id for subscription.
planId Yes Alphanumeric. planId of a valid plan.
customerName Optional Alphanumeric. Name of the customer.
customerEmail Yes Alphanumeric. Email of the customer.
customerPhone Yes Numeric. Mobile number of the customer.
firstChargeDelay Optional Numeric. Applicable for periodic subscriptions only. Number of Days when the first charge for subscription will happen.
authAmount Optional Numeric. The amount that will be charged to authenticate the payment. This amount will be default to Rs. 1 if not provided
expiresOn Optional Alphanumeric. Date after which this subscription should expire. The subscription will subsequently be in a COMPLETED status.
returnUrl Yes Alphanumeric. A valid url to which customer will be redirected to after the subscription is done. See “Payment Response” section.
subscriptionNote Optional Alphanumeric. A short note for this subscription.
subscriptionNote Optional Alphanumeric. A short note for this subscription.
paymentOption Optional Alphanumeric. Use “card”. This is the only valid option currently
card_number Optional Numeric. 16 digit long valid card number.
card_expiryMonth Optional Numeric. Month of expiration of card in MM format.
card_expiryYear Optional Numeric. Year of expiration of card in YYYY format.
card_cvv Optional Numeric. The CVV of the card
card_holder Optional Alphanumeric. The name on the card.

Sample Request for Seamless Create Subscription

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'

Sample Response for Seamless Create Subscription

{
  "status":"OK",
  "message":"Subscription created successfully",
  "subReferenceId": 123,
  "authLink":"https://bit.ly/1234qwer"
}
  • Auth Link will redirect to a 2FA link of the card issuer bank. Once the authorization is completed the customer will be redirected to returnUrl.
  • Please store the subReferenceId on your end. This is the Cashfree generated unique id for this subscription and will be used in subsequent operations

Get Subscription Details

Get the details of a subscription.

Request Configuration for Subscription Details

Type Value
HTTP Method POST
URL /api/v2/subscriptions/:subReferenceId
Content-Type application/json

Headers for Subscription Details

Type Value
X-Client-Id appId
X-Client-Secret secretKey

URL Params for Subscription Details

Parameter Required Description
subReferenceId Yes Numeric. A unique Id for this subscription which was generated on its creation.

Sample Request for Subscription Details

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'

Sample Response for Subscription Details

{
  "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
	}
}
  • Mode can only be CREDIT_CARD currently
  • cardNumber only available when payment done by credit card.
  • Status values and their description are listed in Appendix 1a.
  • Current cycle shows how many payments have been initiated for this subscription.
  • scheduledOn will be null for ON_DEMAND type subscriptions

Get All Subscription Payments

Get the details of all payments for a subscription.

Request Configuration for Subscription Payments

Type Value
HTTP Method POST
URL /api/v2/subscriptions/:subReferenceId/payments?lastId=:lastId&count=:count
Content-Type application/json

Headers for Subscription Payments

Type Value
X-Client-Id appId
X-Client-Secret secretKey

URL Params for Subscription Payments

Parameter Required Description
subReferenceId Yes Numeric. A unique Id for this subscription which was generated on its creation.
lastId Optional Numeric. The pagination counter to return results from.
count Optional Numeric. The total number of payments to be shown in a paginated query.

Sample Request for Subscription Payments

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'

Sample Response for Subscription Payments

{
  "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 Single Subscription Payment

Get the details of individual payment.

Request Configuration for a Subscription Payment

Type Value
HTTP Method POST
URL /api/v2/subscriptions/:subReferenceId/payments/:paymentId
Content-Type application/json

Headers for a Subscription Payment

Type Value
X-Client-Id appId
X-Client-Secret secretKey

URL Params for a Subscription Payment

Parameter Required Description
subReferenceId Yes Numeric. A unique Id for this subscription which was generated on its creation.
paymentId Yes Numeric. A unique Id for this payment.

Sample Request for a Subscription Payment

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'

Sample Response for a Subscription Payment

{
  "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.

Cancel Subscription

Cancel a subscription. The subscription will no longer be charged to customer. A cancelled subscription can not be reverted to active.

Request Configuration for Cancel Subscription

Type Value
HTTP Method POST
URL /api/v2/subscriptions/:subReferenceId/cancel
Content-Type application/json

Headers for Cancel Subscription

Type Value
X-Client-Id appId
X-Client-Secret secretKey

URL Params for Cancel Subscription

Parameter Required Description
subReferenceId Yes Alphanumeric. A unique Id for this subscription which was generated on its creation.

Sample Request for Cancel Subscription

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'

Sample Response for Cancel Subscription

{
  "status":"OK",
  "message":"Subscription Cancelled"
}
  • Once cancelled the subscription will be in CANCELLED status(Appendix 1a).

Charge Subscription

Debit customer on demand. Only possible for subscriptions with plan type ON_DEMAND.

Request Configuration for Charge Subscription

Type Value
HTTP Method POST
URL /api/v2/subscriptions/:subReferenceId/charge
Content-Type application/json

URL Params for Charge Subscription

Parameter Required Description
subReferenceId Yes Numeric. A unique Id for this subscription which was generated on its creation.

Post Params for Charge Subscription

Parameter Required Description
amount Yes Numeric. The amount to be debited from the customer.
remarks Optional Alphanumeric. Details of this payment.

Sample Request for Charge Subscription

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'

Sample Response for Charge Subscription

{
  "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 the returnUrl is provided as part of that request. The returnUrl is the place where customer will be redirected to after authorizing their payment. This redirection is done as POST request with the following parameters.

Request Configuration for Cancel Subscription

Method URL
cf_subReferenceId Numeric. A unique Id for this subscription which was generated on its creation.
cf_subscriptionId Alphanumeric. A merchant generated checksum used to authenticated this transaction.
cf_authAmount Numeric. The money that was charged to authorize the subscription.
cf_orderId Alphanumeric. The PG Order created for authorization.
cf_referenceId Numeric. The referenceId/transactionId of the authorization in PG.
cf_status Alphanumeric. Status of the subscription. In returnUrl response it should be ACTIVE if authorization was successful. If authorization failed the status will be INITIALIZED
cf_message Alphanumeric. A short message about payment.
signature Alphanumeric. The hash of all parameters in request generated using secretKey. Look at Appendix 2 for more info.

Webhook Support

  1. Contact support@cashfree.com to configure your Webhook endpoint.
  2. Make sure that you don’t process duplicate events. For instance, if you have already received a success response for Subscription API call. Discard any identical Subscription success events for the corresponding API.
  3. 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 body containing various parameters which detail what this event corresponds to. Each request contains an event parameter that identifies its type. Here are the various different events that can be sent to your webhook endpoint:

Post Parameters

SUBSCRIPTION_STATUS_CHANGE

Parameter URL
cf_event Alphanumeric. The event for which the subscription was authorized. Always SUBSCRIPTION_STATUS_CHANGE for this event.
cf_subReferenceId Numeric. A unique Id for this subscription which was generated on its creation.
cf_status Alphanumeric. The new status of the subscription. Look at Appendix 1 for a description of different subscription status values.
cf_lastStatus Alphanumeric. The old status of the subscription. Look at Appendix 1 for a description of different subscription status values.
cf_eventTime Alphanumeric. The time when event was dispatched.
signature Alphanumeric. The hash of all parameters in request generated using secretKey. Look at Appendix 2 for more info.

SUBSCRIPTION_NEW_PAYMENT

Parameter URL
cf_event Alphanumeric. The event for which the subscription was authorized. Always SUBSCRIPTION_NEW_PAYMENT for this event.
cf_subReferenceId Numeric. A unique Id for this subscription which was generated on its creation.
cf_paymentId Alphanumeric. The unique paymentId for this payment.
cf_amount Numeric. The amount of money charged for payment.
cf_eventTime Alphanumeric. The time when event was dispatched.
signature Alphanumeric. The hash of all parameters in request generated using secretKey. Look at Appendix 2 for more info.

SUBSCRIPTION_PAYMENT_DECLINED

Parameter URL
cf_event Alphanumeric. The event for which the subscription was authorized. Always SUBSCRIPTION_PAYMENT_DECLINED for this event.
cf_subReferenceId Numeric. A unique Id for this subscription which was generated on its creation.
cf_paymentId Alphanumeric. The unique paymentId for this payment.
cf_amount Numeric. The amount of money charged for payment.
cf_reasons Alphanumeric. A description of possible reason for failure.
cf_eventTime Alphanumeric. The time when event was dispatched.
signature Alphanumeric. The hash of all parameters in request generated using secretKey. Look at Appendix 2 for more info.

Appendix 1

Subscription Status

A description of all possible status for subscription.

Status Description
INITIALIZED The subscription has just been created and is ready to be authorized by the customer.
ACTIVE The customer has authorized the subscription and subscription will continue to debit customer accordingly.
ON_HOLD The subscription failed due to a deauthorization of payment, expiration of payment method, insufficient funds at payment method.
CANCELLED A subscription that was cancelled by the merchant. Subscription in cancelled state can no longer be activated.
COMPLETED A subscription that completed its total active period.

Payment Status

A description of all possible status for subscription payment.

Status Description
SUCCESS Payment for subscription was processed successfully.
PENDING Payment for subscription was attempted but not yet marked successful.
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 request with required amount.

Appendix 2

Please use the following examples as illustrations for how to generate signature. If the language you are using is not mentioned here please contact us at support@gocashfree.com.

Pseudo Code

data = "";
iterate keys as key in POST request alphabetically:
  if (key starts with "cf_"):
    data = data + 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;
} }
  $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
} }
}