Cashfree Payments Developer Documentation

Cashfree’s RESTful Payment Gateway API provides a robust and flexible interface for integrating payment solutions into your applications. The API uses predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and supports standard HTTP response codes and authentication. SDKs in popular programming languages help you integrate faster with pre-built handling for authentication, request or response formatting, and error handling.

We strongly recommend using SDKs to streamline the integration process and ensure optimal performance and security.

What’s new in v2026-01-01

Cashfree Payments API v2026-01-01 is now available. This release includes the following changes:

A new Order Pay Authorise Only endpoint for authorising card payments without immediate capture.
A new controlled subscription payment flow for UPI mandates, with six dedicated APIs for pre-debit notification and charge execution.
New fields and parameters on Create Order, Order Pay, Create Payment Link, and Get All Settlements.
A restructured Create Subscription request body, two new fields, and one removed field.
Breaking response schema changes to settlement endpoints and a removed field on Create Order. Review your integration before upgrading.
A new NuGet package ID for the .NET SDK: cashfree-dotnet-pg from v6.0.7. The previous cashfree_pg package is no longer updated.

Expand the sections below for more details:

New endpoint: Order Pay Authorise Only

A new endpoint, Order Pay Authorise Only, is available for merchants with the AUTHORIZE_ONLY flag enabled on their account. Use it to authorise a card payment without capturing it immediately.The request requires a payment_session_id and an authorization_data object containing the following 3DS authentication fields:

Field	Description
`authentication_token`	3DS authentication token
`directory_server_transaction_id`	Directory server transaction ID from the 3DS flow
`three_ds_server_transaction_id`	3DS server transaction ID
`eci`	Electronic Commerce Indicator value
`token_number`	Network token number
`token_expiry_year`	Token expiry year
`token_expiry_month`	Token expiry month
`token_cryptogram`	Cryptogram for the token
`transaction_type`	One of `ALT_ID`, `TOKEN`, or `APPLE_PAY`

The endpoint returns a PaymentEntity on success and requires no authentication (security: []).

New: controlled subscription payment flow

v2026-01-01 introduces a controlled payment flow for UPI mandate subscriptions, giving you explicit control over when your customers are notified and when the debit is executed. This is a significant change if you need to comply with NPCI pre-debit notification rules.

The controlled flow supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.

How it worksThe controlled flow replaces the automatic charge trigger with a two-step process you drive:

Send a pre-debit notification: notify your customer of the upcoming charge amount before the debit window opens.
Execute the charge: trigger the mandate debit after the compliance window elapses. The debit amount must exactly match the notified amount; a mismatch causes the issuing bank to decline the transaction.

APIs

API	Method	Description
Create Controlled Notification	`POST /subscriptions/pay/controlled/notify-mandate`	Send a pre-debit notification to the customer
Fetch Controlled Notification	`GET /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}`	Retrieve a single notification
Fetch All Controlled Notifications	`GET /subscriptions/payments/{payment_id}/controlled/notifications`	List all notifications for a payment
Create Controlled Execution	`POST /subscriptions/pay/controlled/execute-mandate`	Trigger the mandate debit after the notification window
Fetch Controlled Execution	`GET /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}`	Retrieve a single execution
Fetch All Controlled Executions	`GET /subscriptions/payments/{payment_id}/controlled/executions`	List all execution attempts for a payment

New features on existing endpoints

Client environment headers: Order Pay and Get Eligible Payment MethodsOrder Pay and Get Eligible Payment Methods now formally accept four optional device-context headers required for NPCI compliance. These headers were required in practice; they are now part of the spec with full validation.

Header	Accepted values	Requirement
`x-client-device`	`mobile`, `desktop`, `tablet`	Required
`x-client-os`	`android`, `ios`, `windows`, `macos`, `linux`, `others`	Required
`x-client-browser`	`safari`, `chrome`, `firefox`, `edge`, `others`	Required
`x-client-rendering-type`	`mweb`, `webview`, `native`	Required when `x-client-device` is `mobile`

Offer filters and UPI app priority: Create OrderTwo new optional fields are available on order_meta in Create Order:

offer_filters: explicitly allow or deny specific offers for an order. Set action to ALLOW or DENY and provide a list of up to 25 offer values.
upi_app_priority: control the display order of UPI apps on your checkout page. Accepted values: gpay, phonepe, paytm, navi, cred, supermoney, amazonpay, bhim, mobikwik, airtel, popclub, kiwi.

Settlement status filter: Get All SettlementsGet All Settlements now accepts a new optional filter field filters.settlement_status. Pass an array of one or more of the following values to retrieve settlements by processing state:

SUCCESS
PENDING
PENDING_WITH_CASHFREE
PENDING_WITH_BANK
FAILED

Subscription support: Payment LinksCreate Payment Link now accepts an optional subscription field to create recurring payment links backed by a plan. The plan is defined inline with the following fields:

Field	Required	Description
`plan_id`	Yes	Unique identifier for the plan
`plan_name`	Yes	Display name of the plan
`plan_type`	Yes	Type of plan
`plan_max_amount`	Yes	Maximum charge amount per cycle
`plan_currency`	No	Currency code (default: INR)
`plan_amount`	No	Fixed amount per cycle
`plan_max_cycles`	No	Maximum number of billing cycles
`plan_intervals`	No	Number of intervals per cycle
`plan_interval_type`	No	Interval unit (day, week, month, year)
`plan_note`	No	Internal note for the plan

Additional subscription-level fields: authorization_amount, authorization_amount_refund (boolean), subscription_expiry_time, and subscription_first_charge_time.

PAR field: card paymentsPayOrderRequest.payment_method.card now accepts a par field (Payment Account Reference received from the card network). This is relevant for token-based and network-tokenised card flows.

Breaking changes: response schema updates

The following endpoints return a different response schema in v2026-01-01. Review and update your integration before switching to this version.

These are breaking changes. Existing code that reads from the previous response structure will fail silently or throw errors after upgrading to x-api-version: 2026-01-01.

Get Settlements by Order ID: nested response objectPreviously returned a flat SettlementEntity object. Now returns OrderSettlementEntity, a nested object structured as follows:

Sub-object	Key fields
`order_details`	`order_id`, `order_amount`, `order_currency`
`payment_details`	`cf_payment_id`, `payment_amount`, `service_charge`, `service_tax`, `charge_type`, `charged_to`
`customer_details`	`customer_id`, `customer_email`, `customer_phone`
`settlement_details`	`cf_settlement_id`, `settlement_amount`, `settlement_utr`, `settlement_status`, `settled_on`

Update any code that reads cf_payment_id, service_charge, settlement_amount, or other fields directly from the response root.

Get All Settlements: paginated responsePreviously returned a single flat settlement record. Now returns a paginated GetAllSettlementsResponse:

{
  "cursor": "string",
  "limit": 10,
  "data": [
    {
      "cf_settlement_id": "string",
      "status": "SUCCESS | PENDING | PENDING_WITH_CASHFREE | PENDING_WITH_BANK | FAILED",
      "settlement_utr": "string",
      "payment_from": "date",
      "payment_till": "date",
      "settlement_initiated_on": "date",
      "settlement_processed_on": "date",
      "payment_amount": 0,
      "pg_service_charge": 0,
      "pg_service_tax": 0,
      "adjustment": 0,
      "settlement_charge": 0,
      "settlement_tax": 0,
      "split_service_charge": 0,
      "split_service_tax": 0,
      "vendor_commission": 0,
      "amount_settled": 0,
      "charge_type": "PREPAID | POSTPAID | SURCHARGE | PREPAID_SURCHARGE | POSTPAID_SURCHARGE",
      "settlement_type": "string"
    }
  ]
}

Update any code that reads from the flat settlement response to iterate over data and handle pagination using cursor.

Mark Order for Settlement: HTTP status code and response body changedPreviously returned HTTP 202 with an empty {} body. Now returns HTTP 200 with the following body:

{
  "order_id": "string",
  "meta_data": {
    "cbriks_id": "string",
    "settlement_date": "date"
  }
}

Update any code that checks for a 202 status or expects an empty response body.

Get Order Extended: offer renamed to offers (array)The offer field (a single object of type OfferExtendedDetails) in OrderExtendedDataEntity is now offers (an array of OfferExtendedDetails objects). Update field references from offer to offers and handle the array structure.

Removed fields

The following fields have been removed in v2026-01-01. Requests that include these fields will either be ignored or return a validation error.

Field	Endpoint	Reason
`CreateOrderRequest.bbps`	Create Order	The BBPS-specific fields `bill_fetch_ref_id`, `biller_id`, and `agent_id` are no longer accepted on the Create Order request body.

.NET SDK: new NuGet package

The .NET SDK is now published under a new NuGet package ID starting from version 6.0.7.Install the new package:

dotnet add package cashfree-dotnet-pg

	Package	Version
New	`cashfree-dotnet-pg`	6.0.7 and above
Previous	`cashfree_pg`	Final version: 5.0.6 (no longer updated)

No code changes are required beyond updating the package reference. All future .NET SDK releases will be published only under cashfree-dotnet-pg. For the full version history, see the .NET SDK changelog.

Updates to Subscription APIs

The Subscription APIs in v2026-01-01 include a restructured request body, two new request fields, and one removed field on Create Subscription.Restructured request bodyThe CreateSubscriptionRequest previously used a flat structure where all fields were at the top level. In v2026-01-01, fields are grouped into four nested objects for clarity and consistency:

Object	Fields
`customer_details`	`customer_name`, `customer_email`, `customer_phone`, bank account fields
`plan_details`	`plan_id`, `plan_name`, `plan_type`, `plan_amount`, `plan_max_amount`, `plan_currency`, and related plan configuration
`authorization_details`	`authorization_amount`, `authorization_amount_refund`, `payment_methods`
`subscription_meta`	`return_url`, `notification_channel`, `session_id_expiry`

This is a breaking change. Update your Create Subscription integration to use the new nested structure before switching to x-api-version: 2026-01-01.

New field: subscription_tagsCreateSubscriptionRequest now accepts subscription_tags, a free-form object for attaching up to 10 custom key-value string entries to a subscription. A commonly used key is psp_note, which sets the note displayed to the customer in their payment service provider app or on their bank statement. When using psp_note, the value must be between 1 and 255 characters.

New field: subscription_payment_splitsCreateSubscriptionRequest now accepts subscription_payment_splits, an array of vendor split items. Each item specifies a vendor_id and a percentage, allowing subscription charges to be distributed across multiple vendors at the time of collection.

Removed field: customer_bank_account_holder_nameThe customer_bank_account_holder_name field has been removed from CreateSubscriptionRequest. This field is no longer accepted in v2026-01-01.

New: webhook signature verificationA dedicated Signature Verification page is now available for subscription webhooks, covering how to validate the x-webhook-signature header to confirm event authenticity before processing.For the controlled subscription payment flow, see the New: controlled subscription payment flow section above.

To use this version, set x-api-version: 2026-01-01 in all request headers. If you are using the previous version, see the v2025-01-01 API reference.

Orders and payments
Links and refunds
Vault and offers
Split and settlements

Orders

Create Order

Create an order to collect payments from your customers.

Get Order

Get status and details of an order.

Terminate Order

Terminate an order that’s no longer needed.

Get Order Extended

Fetch extended data for an order.

Update Order Extended

Update extended data for an order.

Customers

Create Customer

Create a customer for Token Vault and saved instruments.

Payments

Pay

Initiate a payment for an order using the chosen payment method.

Authenticate

Submit or resend OTP in the native OTP flow for card payments.

Authorise

Capture or void a pre-authorised transaction.

Get Payment

Get status and details of a single payment.

Get Payments for Order

Get status and details of all payments for an order.

The videos below walk through testing Payment Gateway APIs in Postman and using this API reference.

Testing APIs in Postman

Documentation Walkthrough

Getting started

Use the following resources to begin implementing Payment Gateway APIs:

Payment SDK

Integrate the Payment Gateway with web, mobile, and server SDKs for orders, checkout, and tokenisation

API rate limits

View default limits per minute, monitor usage on the dashboard, and request higher limits when needed

Payments API

v2026-01-01

Other Versions

Overview

What’s new in v2026-01-01

Orders

Customers

Payments

Payment links

Refunds

Token Vault

Eligibility and offers

Easy-Split

Settlements and more

Getting started

Payment SDK

API rate limits

​What’s new in v2026-01-01

​Orders

​Customers

​Payments

​Payment links

​Refunds

​Token Vault

​Eligibility and offers

​Easy-Split

​Settlements and more

​Getting started

Payment SDK

API rate limits

What’s new in v2026-01-01

Orders

Customers

Payments

Payment links

Refunds

Token Vault

Eligibility and offers

Easy-Split

Settlements and more

Getting started