Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This integration allows you to integrate with a Cashfree hosted payment page. Below is a step-by-step guide for each part of the integration process.

​
Requirements

  1. Create a Cashfree Merchant Account.
  2. Log in to the Merchant Dashboard and go to Payment Gateway > Developers > API Keys to generate test keys.
  3. Generate API Keys - Client ID & Secret Key.

​
Step 1: Create a plan

API Documentation: Create Plan 
curl --request POST \
  --url https://sandbox.cashfree.com/pg/plans \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-08-01' \
  --header 'x-client-id: xyz' \
  --header 'x-client-secret: abc' \
  --data '{
	"plan_id": "plan_cashfree_sbox",
	"plan_name": "Premium_10",
	"plan_type": "ON_DEMAND",
	"plan_currency": "INR",
	"plan_max_amount": 100,
	"plan_note": "Test Plan Cashfree"
}'

​
Response

Once the request is successful, you will receive a response as shown below: 
{
	"plan_currency": "INR",
	"plan_id": "plan_cashfree_sbox",
	"plan_interval_type": null,
	"plan_intervals": null,
	"plan_max_amount": 100,
	"plan_max_cycles": null,
	"plan_name": "Premium_10",
	"plan_note": "Test Plan Cashfree",
	"plan_recurring_amount": 0,
	"plan_status": "ACTIVE",
	"plan_type": "ON_DEMAND"
}

​
Step 2: Create subscription

API Documentation: Create Subscription 
curl --request POST \
  --url https://sandbox.cashfree.com/pg/subscriptions \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-client-id: xyz' \
  --header 'x-client-secret: abc' \
  --data '{
	"customer_details": {
		"customer_name": "Sushane Yadav",
		"customer_email": "sushane.yadav@abc.com",
		"customer_phone": "9999999999",
		"customer_bank_account_holder_name": "Sushane Yadav",
		"customer_bank_account_number": "010080198715",
		"customer_bank_ifsc": "ICIC0001008",
		"customer_bank_code": "ICIC",
		"customer_bank_account_type": "SAVINGS"
	},
	"plan_details": {
		"plan_id": "plan_cashfree_sbox",
		"plan_name": "Premium_09",
		"plan_type": "ON_DEMAND"
	},
	"authorization_details": {
		"authorization_amount": 1,
		"authorization_amount_refund": true,
		"authorization_time": 1
	},
	"subscription_tags": {
		"subscription_note": "test create subs"
	},
	"subscription_meta": {
		"return_url": "https://wa.me/8473222?textPayment%20Successfull",
		"notification_channel": [
			"EMAIL",
			"SMS"
		]
	},
	"subscription_id": "create-ondemand-subs-12",
	"subscription_expiry_time": "2028-12-24T14:15:22Z"
}'

​
Response

Once the request is successful, you will receive a response as shown below: 
{
	"authorization_details": {
		"authorization_amount": 1,
		"authorization_amount_refund": true,
		"authorization_reference": null,
		"authorization_time": null,
		"authorization_status": null,
		"payment_id": null,
		"payment_method": null,
		"instrument_id": null
	},
	"cf_subscription_id": "604456",
	"customer_details": {
		"customer_name": "Sushane Yadav",
		"customer_email": "sushane.yadav@abc.com",
		"customer_phone": "9999999999",
		"customer_bank_account_holder_name": "Sushane Yadav",
		"customer_bank_account_number": "010080198715",
		"customer_bank_ifsc": "ICIC0001008",
		"customer_bank_code": "ICIC",
		"customer_bank_account_type": "SAVINGS"
	},
	"plan_details": {
		"plan_id": "plan_cashfree_sbox",
		"plan_name": "Premium_10",
		"plan_type": "ON_DEMAND",
		"plan_max_cycles": null,
		"plan_recurring_amount": 0,
		"plan_max_amount": 100,
		"plan_interval_type": null,
		"plan_intervals": null,
		"plan_currency": "INR",
		"plan_note": null,
		"plan_status": null
	},
	"subscription_expiry_time": "2028-12-25T01:15:22+05:30",
	"subscription_first_charge_time": null,
	"subscription_id": "create-ondemand-subs-12",
	"subscription_meta": {
		"return_url": "https://wa.me/8473222?textPayment%20Successfull"
	},
	"subscription_payment_splits": null,
	"subscription_session_id": "sub_session_0KnQeY5a63YSnrlk-unL2CuQHV1n4ghoo-laNrHiEL1qgWiytwC_ELZOxjl1AmRm53vh8XT9iTyBECN5KgjAnsu9L9cfzfbCG96rM4T_rZs02q6vsopg3RFXstNZppmlhOytuNMpayment",
	"subscription_status": "INITIALIZED",
	"subscription_tags": {
		"subscription_note": "test create subs"
	}
}

​
Step 3: Initiate an auth

Use the subscription_session_id received in the response of create subscription to initiate the subscription auth checkout. Refer to below code module to integrate :- 
const paymentMessage = document.getElementById("paymentMessage");

const cashfree = Cashfree({
  mode: "sandbox" // or production
});

document.getElementById("subsCheckout").addEventListener("click", function(){
  paymentMessage.innerText = "";
  paymentMessage.classList.remove("alert-danger");
  paymentMessage.classList.remove("alert-success");

  cashfree.subscriptionsCheckout({
    subsSessionId: document.getElementById("subsSessionId").value,
    redirectTarget: "_blank"
  }).then(function(result){
    if(result.error){
      document.getElementById("paymentMessage").innerHTML = (result.error.message)
    }
  })
})
Try out here: codepen
  1. Take the subscription_session_id and paste it in the codepen link and click on submit.
  1. You will be redirected to the subscription checkout page.
  1. Choose the payment mode you want to setup the subscription and submit. In case of sandbox you will be asked to simulate the payment.
  1. You will be redirected to the return url post the transaction is completed.

​
Step 4: Get subscription details

Use this API to check the subscription status and auth details post completion of the payment. API Documentation: Get Subscription 
curl --request GET \
  --url https://sandbox.cashfree.com/pg/subscriptions/{subscription_id} \
  --header 'accept: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-client-id: xyz' \
  --header 'x-client-secret: abc'

​
Response

Once the request is successful, you will receive a response as shown below: 
{
	"authorization_details": {
		"authorization_amount": 1,
		"authorization_amount_refund": true,
		"authorization_reference": "J7iuqUTKXxoNS17u5oBq4n24jYFAV5@upi",
		"authorization_time": "2024-11-25T22:05:25+05:30",
		"authorization_status": "ACTIVE",
		"payment_id": "513463",
		"payment_method": "upi",
		"instrument_id": null
	},
	"cf_subscription_id": "604456",
	"customer_details": {
		"customer_name": "Sushane Yadav",
		"customer_email": "sushane.yadav@abc.com",
		"customer_phone": "9999999999",
		"customer_bank_account_holder_name": "Sushane Yadav",
		"customer_bank_account_number": "010080198715",
		"customer_bank_ifsc": "ICIC0001008",
		"customer_bank_code": "ICIC",
		"customer_bank_account_type": "SAVINGS"
	},
	"plan_details": {
		"plan_id": "plan_cashfree_sbox",
		"plan_name": "Premium_10",
		"plan_type": "ON_DEMAND",
		"plan_max_cycles": null,
		"plan_recurring_amount": 0,
		"plan_max_amount": 100,
		"plan_interval_type": null,
		"plan_intervals": null,
		"plan_currency": "INR",
		"plan_note": null,
		"plan_status": null
	},
	"subscription_expiry_time": "2028-12-25T01:15:22+05:30",
	"subscription_first_charge_time": null,
	"subscription_id": "create-ondemand-subs-12",
	"subscription_meta": {
		"return_url": "https://wa.me/8473222?textPayment%20Successfull"
	},
	"subscription_payment_splits": null,
	"subscription_session_id": "sub_session_8NDk6JTfSb9elrakgfn8VE_1j_pJ7zEWdWJefDha68ddBjapy6AjlxLLYoObqxLvDYF1nysfWCbu11wPeJmQbub00dadRUs7rPIf1nc33-4F85BNjZV0_3uOdt7rDMkPUesto0wpayment",
	"subscription_status": "ACTIVE",
	"subscription_tags": {
		"subscription_note": "test create subs"
	}
}

​
Step 5: Raise a charge on subscription

API Documentation: Raise a charge
Use the simulate payment API to simulate a charge status in the sandbox environment.
curl --request POST \
  --url https://sandbox.cashfree.com/pg/subscriptions/pay \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-client-id: xyz' \
  --header 'x-client-secret: abc' \
  --data '{
	"subscription_id": "create-ondemand-subs-12",
	"payment_id": "test-payment-subs-07",
	"payment_type": "CHARGE",
	"payment_amount": 10,
	"payment_remarks": "first payment",
	"payment_schedule_date": "2024-11-30T14:15:22Z"
}'

​
Response

Once the request is successful, you will receive a response as shown below: 
{
	"action": null,
	"cf_payment_id": "513474",
	"channel": null,
	"data": null,
	"payment_amount": 10,
	"payment_id": "test-payment-subs-07",
	"payment_method": null,
	"payment_status": "INITIALIZED",
	"payment_type": "CHARGE",
	"subscription_id": "create-ondemand-subs-12"
}