Cashfree Payments Developer Documentation

Customers won’t be notified about plan changes. The charge amount can’t exceed the maximum amount defined in the original plan.
The CHANGE_PLAN and PAUSE actions aren’t supported for On-Demand Subscriptions.

Authorizations

x-client-id

string

header

required

Client app ID. You can find your app id in the Merchant Dashboard.

x-client-secret

string

header

required

Client secret key. You can find your secret key in the Merchant Dashboard.

Headers

x-api-version

string

default:2025-01-01

required

API version to be used. Format is in YYYY-MM-DD. API version to be used

x-request-id

string

Request ID for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to Cashfree.

x-idempotency-key

string<UUID>

An idempotency key is a unique identifier you include with your API call. If the request fails or times out, you can safely retry it using the same key to avoid duplicate actions.

Path Parameters

subscription_id

string

required

Provide the SubscriptionId using which the subscription was created.

Body

application/json

Request body to manage a subscription.

subscription_id

string

required

The unique ID which was used to create subscription.

action

string

required

Action to be performed on the subscription. Possible values - CANCEL, PAUSE, ACTIVATE, CHANGE_PLAN.

action_details

object

Details of the action to be performed.

Show child attributes

action_details.next_scheduled_time

string

Next scheduled time for the action. Required for ACTIVATE action.

Please note that only the date component is considered. Any time value provided will be ignored.

action_details.plan_id

string

Plan ID to update. Required for CHANGE_PLAN action.

Response

Success response for managing a subscription.

authorisation_details

AuthorizationDetails · object

Details of the authorization done for the subscription. Returned in Get subscription and payments.

Show child attributes

authorisation_details.authorization_amount

number<float64>

Authorization amount for the auth payment. Please note that authorization_amount will always be 0 for ENACH.

authorisation_details.authorization_amount_refund

boolean

Indicates whether the authorization amount should be refunded to the customer automatically. Merchants can use this field to specify if the authorized funds should be returned to the customer after authorization of the subscription.

authorisation_details.authorization_reference

string

Authorization reference. UMN for UPI, UMRN for EMandate/Physical Mandate and Enrollment ID for cards.

authorisation_details.authorization_time

string<ISO8601>

Authorization time. Cashfree stores timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

authorisation_details.authorization_status

string

Status of the authorization.

authorisation_details.payment_id

string

A unique ID passed by merchant for identifying the transaction.

authorisation_details.payment_group

string

Payment group used for the authorization.

authorisation_details.payment_method

object

Show child attributes

authorisation_details.payment_method.upi

Upi Auth Response · object

Payment method upi.

Show child attributes

authorisation_details.payment_method.upi.channel

string

Can be link, qrcode, or collect.

authorisation_details.payment_method.upi.upi_id

string

Virtual payment address (UPI ID) of the user.

authorisation_details.payment_method.upi.upi_instrument

string

UPI instrument used for payment.

authorisation_details.payment_method.upi.upi_instrument_number

string

Unique number representing the UPI instrument.

authorisation_details.payment_method.upi.upi_payer_account_number

string

Account number of the UPI payer.

authorisation_details.payment_method.upi.upi_payer_ifsc

string

IFSC code of the UPI payer's bank.

authorisation_details.payment_method.enach

Enach Auth Response · object

Payment method enach.

Show child attributes

authorisation_details.payment_method.enach.channel

string

Channel. Can be link.

authorisation_details.payment_method.enach.auth_mode

string

Auth mode. Can be debit_card, aadhaar, or net_banking.

authorisation_details.payment_method.enach.account_type

string

Type of the bank account.

authorisation_details.payment_method.enach.account_number

string

Bank account number.

authorisation_details.payment_method.enach.account_ifsc

string

IFSC code of the bank account.

authorisation_details.payment_method.enach.account_holder_name

string

Name of the account holder.

authorisation_details.payment_method.enach.account_bank_code

string

Bank code of the account-holding bank.

authorisation_details.payment_method.pnach

Pnach Auth Response · object

Payment method pnach.

Show child attributes

authorisation_details.payment_method.pnach.channel

string

Channel. Can be post.

authorisation_details.payment_method.pnach.mandate_creation_date

string<ISO8601>

Date on which the mandate was created. Cashfree stores timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

authorisation_details.payment_method.pnach.mandate_start_date

string<ISO8601>

Start date of the mandate. Cashfree stores timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

authorisation_details.payment_method.pnach.account_type

string

Type of the bank account.

authorisation_details.payment_method.pnach.account_number

string

Bank account number.

authorisation_details.payment_method.pnach.account_ifsc

string

IFSC code of the bank account.

authorisation_details.payment_method.pnach.account_holder_name

string

Name of the account holder.

authorisation_details.payment_method.pnach.account_bank_code

string

Bank code of the account-holding bank.

authorisation_details.payment_method.card

Card Auth Response · object

Payment method card.

Show child attributes

authorisation_details.payment_method.card.channel

string

Can be link.

authorisation_details.payment_method.card.card_number

string

Card number.

authorisation_details.payment_method.card.card_network

string

Card network (e.g., VISA, Mastercard).

authorisation_details.payment_method.card.card_type

string

Card type (e.g., credit_card).

authorisation_details.payment_method.card.card_sub_type

string

Card subtype (e.g., R).

authorisation_details.payment_method.card.card_country

string

Country of the card (e.g., IN).

authorisation_details.payment_method.card.card_bank_name

string

Bank name on card.

authorisation_details.payment_method.card.card_network_reference_id

string

Network reference ID.

authorisation_details.payment_method.card.instrument_id

string

Unique identifier for card instrument.

Example:

{
  "authorization_amount": 1,
  "authorization_amount_refund": false,
  "authorization_reference": "",
  "authorization_time": "2025-06-01T23:47:52+05:30",
  "authorization_status": "INITIALIZED",
  "payment_id": "97877",
  "payment_group": "upi",
  "payment_method": {
    "upi": {
      "channel": "collect",
      "upi_id": "test@upi",
      "upi_instrument": "upiInstrument",
      "upi_instrument_number": "1234567890",
      "upi_payer_account_number": "039861903074",
      "upi_payer_ifsc": "SBIN0001234"
    }
  }
}

cf_subscription_id

string

Cashfree subscription reference number

customer_details

CustomerDetails · object

Subscription customer details.

Show child attributes

customer_details.customer_email

string

required

Email of the customer.

customer_details.customer_phone

string

required

Phone number of the customer.

customer_details.customer_name

string

Name of the customer.

customer_details.customer_bank_account_holder_name

string

Bank holder name of the customer. Account holder name is mandatory for TPV transaction. Max character allowed is 40.

customer_details.customer_bank_account_number

string

Bank account number of the customer. Conditional Parameter. Max character allowed is 35.

customer_details.customer_bank_ifsc

string

IFSC code of the customer. For a TPV transaction, send at least one out of customer_bank_code or customer_bank_ifsc.

customer_details.customer_bank_code

string

Bank code of the customer. Refer to the list of Live Banks in API E-Mandate on the NPCI website. For a TPV transactions, include at least one of customer_bank_code or customer_bank_ifsc.

customer_details.customer_bank_account_type

enum<string>

Bank account type of the customer.

Available options:

SAVINGS,

CURRENT

Example:

{
  "customer_name": "Test Cust",
  "customer_email": "[email protected]",
  "customer_phone": "9900755700",
  "customer_bank_account_holder_name": "",
  "customer_bank_account_number": "",
  "customer_bank_ifsc": "",
  "customer_bank_code": "",
  "customer_bank_account_type": ""
}

plan_details

PlanEntity · object

Show child attributes

plan_details.plan_currency

string

Currency for the plan.

plan_details.plan_id

string

Plan ID provided by merchant.

plan_details.plan_interval_type

string

Interval type for the plan.

plan_details.plan_intervals

integer

Number of intervals for the plan.

plan_details.plan_max_amount

number<float64>

Maximum amount for the plan.

plan_details.plan_max_cycles

integer

Maximum number of payment cycles for the plan.

plan_details.plan_name

string

Name of the plan.

plan_details.plan_note

string

Note for the plan.

plan_details.plan_recurring_amount

number<float64>

Recurring amount for the plan.

plan_details.plan_status

string

Status of the plan.

plan_details.plan_type

string

Type of the plan.

Example:

{
  "plan_currency": "INR",
  "plan_id": "144436-03471-JD_TEST",
  "plan_interval_type": "WEEK",
  "plan_intervals": 1,
  "plan_max_amount": 1,
  "plan_max_cycles": 4,
  "plan_name": "abscede",
  "plan_note": "lsdkdn",
  "plan_recurring_amount": 1,
  "plan_status": "ACTIVE",
  "plan_type": "PERIODIC"
}

subscription_expiry_time

string<ISO8601>

Time at which the subscription will expire. We store timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

subscription_first_charge_time

string<ISO8601>

Time at which the first charge will be made for the subscription. Applicable only for PERIODIC plans. Cashfree stores timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

subscription_id

string

A unique ID passed by merchant for identifying the subscription.

subscription_meta

object

Subscription metadata.

Show child attributes

subscription_meta.return_url

string

Return URL for the subscription.

subscription_note

string

Note for the subscription.

subscription_session_id

string

Subscription Session Id.

subscription_payment_splits

SubscriptionPaymentSplitItem · object[]

Payment splits for the subscription.

Show child attributes

subscription_payment_splits.vendor_id

string

Vendor ID

subscription_payment_splits.percentage

number<float64>

Percentage of the payment to be split to vendor

subscription_status

string

Status of the subscription. For more details, see Subscription Lifecycle.

subscription_tags

object

Tags for the subscription.

next_schedule_date

string<ISO8601>

The date on which the next payment is scheduled to be processed. Cashfree stores timestamps in IST. For ON_DEMAND plans this will be null .

Example:

"2025-06-01T10:20:12+05:30"

Payments API

v2025-01-01

Other Versions

Manage Subscription

Authorizations

Headers

Path Parameters

Body

Response