Cashfree Payments Developer Documentation

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.

Body

application/json

Request body to create an order at Cashfree.

order_amount

number<double>

required

Bill amount for the order. Provide upto two decimals. 10.15 means Rs 10 and 15 paisa. For orders in non-INR currency, please refer to supported amounts per currency.

Required range: x >= 1

Example:

10.15

order_currency

string

required

Currency for the order. INR if left empty. For support currency list, refer here. Submit Support Form to enable new currencies.

Example:

"INR"

customer_details

CustomerDetails · object

required

The customer details that are necessary. Note that you can pass dummy details if your use case does not require the customer details.

Show child attributes

customer_details.customer_id

string

required

A unique identifier for the customer. Use alphanumeric values only.

Required string length: 3 - 50

customer_details.customer_phone

string

required

Customer phone number. To accommodate international phone numbers, ensure the number is prefixed with a '+' to override the 10-digit limitation.

Required string length: 10

customer_details.customer_email

string

Customer email address.

Required string length: 3 - 100

customer_details.customer_name

string

Name of the customer.

Required string length: 3 - 100

customer_details.customer_bank_account_number

string

Customer bank account. Required if you want to do a bank account check (TPV)

Required string length: 3 - 20

customer_details.customer_bank_ifsc

string

Customer bank IFSC. Required if you want to do a bank account check (TPV)

customer_details.customer_bank_code

number

Customer bank code. Required for net banking payments, if you want to do a bank account check (TPV)

customer_details.customer_uid

string

Customer identifier at Cashfree. You will get this when you create/get customer

Example:

{
  "customer_id": "7112AAA812234",
  "customer_email": "[email protected]",
  "customer_phone": "9908734801",
  "customer_name": "John Doe",
  "customer_bank_account_number": "1518121112",
  "customer_bank_ifsc": "XITI0000001",
  "customer_bank_code": 3333,
  "customer_uid": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10"
}

order_id

string

Order identifier present in your system. Alphanumeric, '_' and '-' only

Required string length: 3 - 45

Example:

"your-order-id"

cart_details

CartDetails · object

The cart details that are necessary like shipping address, billing address and more.

Show child attributes

cart_details.customer_note

string

cart_details.shipping_charge

number<double>

cart_details.cart_name

string

Name of the cart.

cart_details.customer_shipping_address

CartAddress · object

Address given for cart details.

Show child attributes

cart_details.customer_shipping_address.full_name

string

cart_details.customer_shipping_address.country

string

cart_details.customer_shipping_address.city

string

cart_details.customer_shipping_address.state

string

cart_details.customer_shipping_address.pincode

string

cart_details.customer_shipping_address.address_1

string

cart_details.customer_shipping_address.address_2

string

cart_details.customer_billing_address

CartAddress · object

Address given for cart details.

Show child attributes

cart_details.customer_billing_address.full_name

string

cart_details.customer_billing_address.country

string

cart_details.customer_billing_address.city

string

cart_details.customer_billing_address.state

string

cart_details.customer_billing_address.pincode

string

cart_details.customer_billing_address.address_1

string

cart_details.customer_billing_address.address_2

string

cart_details.cart_items

CartItem · object[]

Show child attributes

cart_details.cart_items.item_id

string

Unique identifier of the item

cart_details.cart_items.item_name

string

Name of the item

cart_details.cart_items.item_description

string

Description of the item

cart_details.cart_items.item_tags

string[]

Tags attached to that item

cart_details.cart_items.item_details_url

string

Item details url

cart_details.cart_items.item_image_url

string

Item image url

cart_details.cart_items.item_original_unit_price

number<double>

Original price

cart_details.cart_items.item_discounted_unit_price

number<double>

Discounted Price

cart_details.cart_items.item_currency

string

Currency of the item.

cart_details.cart_items.item_quantity

number<int32>

Quantity if that item

terminal

Terminal · object

Use this if you are creating an order for cashfree's softPOS

Show child attributes

terminal.terminal_type

string

required

To identify the type of terminal product in use, in this case it is SPOS.

Required string length: 4 - 10

terminal.added_on

string

date time at which terminal is added

terminal.cf_terminal_id

integer

Cashfree terminal id, this is a required parameter when you do not provide the terminal phone number.

terminal.last_updated_on

string

last instant when this terminal was updated

terminal.terminal_address

string

location of terminal

terminal.terminal_id

string

terminal id for merchant reference

Required string length: 3 - 100

terminal.terminal_name

string

name of terminal/agent/storefront

terminal.terminal_note

string

note given by merchant while creating the terminal

terminal.terminal_phone_no

string

mobile num of the terminal/agent/storefront,This is a required parameter when you do not provide the cf_terminal_id.

terminal.terminal_status

string

status of terminal active/inactive

Example:

{
  "added_on": "2023-08-04T13:12:58+05:30",
  "cf_terminal_id": "31051123",
  "last_updated_on": "2023-09-06T14:07:00+05:30",
  "terminal_address": "Banglore",
  "terminal_id": "terminal-1212",
  "terminal_name": "test",
  "terminal_note": "POS vertical",
  "terminal_phone_no": "6309291183",
  "terminal_status": "ACTIVE",
  "terminal_type": "SPOS"
}

order_meta

OrderMeta · object

Optional meta details to control how the customer pays and how payment journey completes

Show child attributes

order_meta.return_url

string

This is the URL to which the customer will be redirected after the payment reaches a terminal state (success, failed or cancelled). We recommend keeping context of order_id in your return_url so that you can identify the order when customer lands on your page. Cashfree triggers a GET request to this URL. Maximum URL length: 250 characters

Example:

"https://www.cashfree.com/devstudio/thankyou?order_id=devstudio_734905336776434862"

order_meta.notify_url

string

Notification URL for server-server communication. Useful when user's connection drops while re-directing. NotifyUrl should be an https URL. Maximum length: 250.

Example:

"https://example.com/cf_notify"

order_meta.payment_methods

any

Specifies the allowed payment modes for this order. To restrict payment options, provide a comma-separated list of values from the following options: cc, dc, ccc, ppc, nb, upi, paypal, app, paylater, cardlessemi, dcemi, ccemi, banktransfer, applepay. Leave this field blank to display all available payment methods.

Example:

"cc,dc,upi"

order_meta.payment_methods_filters

object

Allowed payment modes for this order. Along with multiple filters for cards can be added to this key. And this filtering will be honoured during transaction creation.

Show child attributes

order_meta.payment_methods_filters.methods

object

Allowed payment modes for this order. credit_card, debit_card, netbanking, paylater, etc are the values that can be passed to this parameter.

Show child attributes

order_meta.payment_methods_filters.methods.action

string

It accepts value of "ALLOW" and allows only those modes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.methods.values

string[]

The accepted entries for this paramter are "debit_card, credit_card, prepaid_card, upi, wallet, netbanking, banktransfer, paylater, paypal, debit_card_emi, credit_card_emi, upi_credit_card, upi_ppi, cardless_emi, account_based_payment, corporate_credit_card, sbc_debit_card, sbc_emandate, sbc_upi, sbc_credit_card"

order_meta.payment_methods_filters.filters

object

This object takes details of all the filtering that has to be done for this order. Filters on card bins, card schemes, card issuing bank and card suffixes

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_tenure

object

Allowed card emi tenure for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_tenure.action

string

It accepts value of "ALLOW" and allows only those bins present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_tenure.values

integer[]

List of tenure to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_bins

object

Allowed card bins for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_bins.action

string

It accepts value of "ALLOW" and allows only those bins present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_bins.values

string[]

List of card bins to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_schemes

object

Allowed card schemes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_schemes.action

string

It accepts value of "ALLOW" and allows only those schemes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_schemes.values

string[]

List of card schemes to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_suffix

object

Allowed card suffixes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_suffix.action

string

It accepts value of "ALLOW" and allows only those suffixes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_suffix.values

string[]

List of card suffixes to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_issuing_bank

object

Allowed card issuing bank for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_issuing_bank.action

string

It accepts value of "ALLOW" and allows only those issuing bank present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_issuing_bank.values

string[]

List of card issuing bank to be allowed for the order

order_meta.payment_methods_filters.filters.card_bins

object

Allowed card bins for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_bins.action

string

It accepts value of "ALLOW" and allows only those bins present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_bins.values

string[]

List of card bins to be allowed for the order

order_meta.payment_methods_filters.filters.card_schemes

object

Allowed card schemes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_schemes.action

string

It accepts value of "ALLOW" and allows only those schemes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_schemes.values

string[]

List of card schemes to be allowed for the order

order_meta.payment_methods_filters.filters.card_suffix

object

Allowed card suffixes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_suffix.action

string

It accepts value of "ALLOW" and allows only those suffixes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_suffix.values

string[]

List of card suffixes to be allowed for the order

order_meta.payment_methods_filters.filters.card_issuing_bank

object

Allowed card issuing bank for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_issuing_bank.action

string

It accepts value of "ALLOW" and allows only those issuing bank present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_issuing_bank.values

string[]

List of card issuing bank to be allowed for the order

Example:

{
  "return_url": "https://www.cashfree.com/devstudio/thankyou",
  "payment_methods": "cc,dc"
}

order_expiry_time

string<ISO8601>

Time after which the order expires. Customers will not be able to make the payment beyond the time specified here. We store timestamps in IST, but you can provide them in a valid ISO 8601 time format. Example 2021-07-02T10:20:12+05:30 for IST, 2021-07-02T10:20:12Z for UTC

Example:

"2021-07-02T10:20:12+05:30"

order_note

string

Order note for reference.

Required string length: 3 - 200

Example:

"Test order"

order_tags

object

Custom Tags in the form of {"key":"value"} which can be passed for an order. A maximum of 10 tags can be added

Show child attributes

order_tags.{key}

string

Required string length: 1 - 255

Example:

{
  "product": "Laptop",
  "shipping_address": "123 Main St",
  "name": "John Doe",
  "city": "Bangalore"
}

order_splits

VendorSplit · object[]

If you have Easy split enabled in your Cashfree account then you can use this option to split the order amount.

Show child attributes

order_splits.vendor_id

string

required

Vendor id created in Cashfree system

order_splits.amount

number

Amount which will be associated with this vendor

order_splits.percentage

number

Percentage of order amount which shall get added to vendor account

order_splits.tags

object

Custom Tags in the form of {"key":"value"} which can be passed for an order. A maximum of 10 tags can be added

Show child attributes

order_splits.tags.{key}

object

Example:

[{ "amount": 10, "vendor": "john" }]

products

products · object

Use this to set configurations for the products like One Click Checkout, Verify and Pay, if they are enabled for your account

Show child attributes

products.one_click_checkout

object

Specify the required configurations for this feature

Show child attributes

products.one_click_checkout.enabled

boolean

Option to enable or disable the feature

products.one_click_checkout.conditions

object[]

The conditions array allows to configure rules by adding condition objects with specific parameters for feature configurations.

Show child attributes

products.one_click_checkout.conditions.action

string

The Action key in the conditions array specifies whether a condition should "ALLOW" or "DENY" the specified rule or feature

products.one_click_checkout.conditions.key

string

Specify what you're trying to configure, such as "features"

Maximum string length: 50

products.one_click_checkout.conditions.values

string[]

Define the values you need to set within the conditions in this array, such as "checkoutCollectAddress", "checkoutAuthenticate".

Maximum array length: 10

products.verify_pay

object

Specify the required configurations for this feature

Show child attributes

products.verify_pay.enabled

boolean

Option to enable or disable the feature

products.verify_pay.conditions

object[]

The conditions array allows to configure rules by adding condition objects with specific parameters for feature configurations.

Show child attributes

products.verify_pay.conditions.action

string

The Action key in the conditions array specifies whether a condition should "ALLOW" or "DENY" the specified rule or feature

products.verify_pay.conditions.key

string

Specify what you're trying to configure, such as "features"

Maximum string length: 50

products.verify_pay.conditions.values

string[]

Define the values you need to set within the conditions in this array, such as "checkoutCollectAddress", "checkoutAuthenticate".

Maximum array length: 10

Response

The complete order entity.

cf_order_id

string

unique id generated by cashfree for your order

order_id

string

order_id sent during the api request

entity

string

Type of the entity.

order_currency

string

Currency of the order. Example INR

order_amount

number

order_status

string

Possible values are

ACTIVE: Order does not have a sucessful transaction yet
PAID: Order is PAID with one successful transaction
EXPIRED: Order was not PAID and not it has expired. No transaction can be initiated for an EXPIRED order. TERMINATED: Order terminated TERMINATION_REQUESTED: Order termination requested

payment_session_id

string

order_expiry_time

string

order_note

string

Additional note for order

created_at

string

When the order was created at cashfree's server

Example:

"2022-08-16T14:45:38+05:30"

order_splits

VendorSplit · object[]

Show child attributes

order_splits.vendor_id

string

required

Vendor id created in Cashfree system

order_splits.amount

number

Amount which will be associated with this vendor

order_splits.percentage

number

Percentage of order amount which shall get added to vendor account

order_splits.tags

object

Custom Tags in the form of {"key":"value"} which can be passed for an order. A maximum of 10 tags can be added

Show child attributes

order_splits.tags.{key}

object

customer_details

CustomerDetailsResponse · object

The customer details that are necessary. Note that you can pass dummy details if your use case does not require the customer details.

Show child attributes

customer_details.customer_id

string

A unique identifier for the customer. Use alphanumeric values only.

Required string length: 3 - 50

customer_details.customer_email

string

Customer email address.

Required string length: 3 - 100

customer_details.customer_phone

string

Customer phone number.

Required string length: 10

customer_details.customer_name

string

Name of the customer.

Required string length: 3 - 100

customer_details.customer_bank_account_number

string

Customer bank account. Required if you want to do a bank account check (TPV)

Required string length: 3 - 20

customer_details.customer_bank_ifsc

string

Customer bank IFSC. Required if you want to do a bank account check (TPV)

customer_details.customer_bank_code

number

Customer bank code. Required for net banking payments, if you want to do a bank account check (TPV)

customer_details.customer_uid

string

Customer identifier at Cashfree. You will get this when you create/get customer

Example:

{
  "customer_id": "7112AAA812234",
  "customer_email": "[email protected]",
  "customer_phone": "9908734801",
  "customer_name": "John Doe",
  "customer_bank_account_number": "1518121112",
  "customer_bank_ifsc": "XITI0000001",
  "customer_bank_code": 3333,
  "customer_uid": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10"
}

order_meta

OrderMeta · object

Optional meta details to control how the customer pays and how payment journey completes

Show child attributes

order_meta.return_url

string

Example:

"https://www.cashfree.com/devstudio/thankyou?order_id=devstudio_734905336776434862"

order_meta.notify_url

string

Notification URL for server-server communication. Useful when user's connection drops while re-directing. NotifyUrl should be an https URL. Maximum length: 250.

Example:

"https://example.com/cf_notify"

order_meta.payment_methods

any

Example:

"cc,dc,upi"

order_meta.payment_methods_filters

object

Allowed payment modes for this order. Along with multiple filters for cards can be added to this key. And this filtering will be honoured during transaction creation.

Show child attributes

order_meta.payment_methods_filters.methods

object

Allowed payment modes for this order. credit_card, debit_card, netbanking, paylater, etc are the values that can be passed to this parameter.

Show child attributes

order_meta.payment_methods_filters.methods.action

string

It accepts value of "ALLOW" and allows only those modes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.methods.values

string[]

order_meta.payment_methods_filters.filters

object

This object takes details of all the filtering that has to be done for this order. Filters on card bins, card schemes, card issuing bank and card suffixes

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_tenure

object

Allowed card emi tenure for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_tenure.action

string

It accepts value of "ALLOW" and allows only those bins present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_tenure.values

integer[]

List of tenure to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_bins

object

Allowed card bins for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_bins.action

string

It accepts value of "ALLOW" and allows only those bins present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_bins.values

string[]

List of card bins to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_schemes

object

Allowed card schemes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_schemes.action

string

It accepts value of "ALLOW" and allows only those schemes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_schemes.values

string[]

List of card schemes to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_suffix

object

Allowed card suffixes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_suffix.action

string

It accepts value of "ALLOW" and allows only those suffixes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_suffix.values

string[]

List of card suffixes to be allowed for the order

order_meta.payment_methods_filters.filters.card_emi_issuing_bank

object

Allowed card issuing bank for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_emi_issuing_bank.action

string

It accepts value of "ALLOW" and allows only those issuing bank present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_emi_issuing_bank.values

string[]

List of card issuing bank to be allowed for the order

order_meta.payment_methods_filters.filters.card_bins

object

Allowed card bins for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_bins.action

string

It accepts value of "ALLOW" and allows only those bins present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_bins.values

string[]

List of card bins to be allowed for the order

order_meta.payment_methods_filters.filters.card_schemes

object

Allowed card schemes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_schemes.action

string

It accepts value of "ALLOW" and allows only those schemes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_schemes.values

string[]

List of card schemes to be allowed for the order

order_meta.payment_methods_filters.filters.card_suffix

object

Allowed card suffixes for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_suffix.action

string

It accepts value of "ALLOW" and allows only those suffixes present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_suffix.values

string[]

List of card suffixes to be allowed for the order

order_meta.payment_methods_filters.filters.card_issuing_bank

object

Allowed card issuing bank for the order

Show child attributes

order_meta.payment_methods_filters.filters.card_issuing_bank.action

string

It accepts value of "ALLOW" and allows only those issuing bank present in it's neighbouring parameter "values"

order_meta.payment_methods_filters.filters.card_issuing_bank.values

string[]

List of card issuing bank to be allowed for the order

order_tags

object

Custom Tags in the form of {"key":"value"} which can be passed for an order. A maximum of 10 tags can be added

Show child attributes

order_tags.{key}

string

Required string length: 1 - 255

Example:

{
  "product": "Laptop",
  "shipping_address": "123 Main St"
}

cart_details

CartDetailsEntity · object

Cart Details in the Order Entity Response

Show child attributes

cart_details.cart_id

string

ID of the cart that was created

terminal_data

TerminalData · object

Terminal Data in the create order response

Show child attributes

terminal_data.agent_mobile_number

string

terminal_data.cf_terminal_id

integer

terminal_data.merchant_terminal_id

string

terminal_data.terminal_type

string

Example:

{
  "agent_mobile_number": "9876543214",
  "cf_terminal_id": 1838,
  "merchant_terminal_id": "ahdsgadjhgfaj7137e",
  "terminal_type": "STOREFRONT"
}

products

object

Configurations for the products like One Click Checkout, Verify and Pay, if they are enabled for your account

Show child attributes

products.one_click_checkout

object

Configurations for this feature

Show child attributes

products.one_click_checkout.enabled

boolean

Whether the feature has been enabled for this order

products.one_click_checkout.conditions

object[]

Configured condtions for the feature

Show child attributes

products.one_click_checkout.conditions.action

string

The Action key in the conditions array specifies whether a condition is allowed or denied for the specified rule or feature

products.one_click_checkout.conditions.key

string

key of the condition

Maximum string length: 50

products.one_click_checkout.conditions.values

string[]

Values set for the condition

Maximum array length: 10

products.verify_pay

object

Configurations for this feature

Show child attributes

products.verify_pay.enabled

boolean

Whether the feature has been enabled for this order

products.verify_pay.conditions

object[]

Configured condtions for the feature

Show child attributes

products.verify_pay.conditions.action

string

The Action key in the conditions array specifies whether a condition is allowed or denied for the specified rule or feature

products.verify_pay.conditions.key

string

key of the condition

Maximum string length: 50

products.verify_pay.conditions.values

string[]

Values set for the condition

Maximum array length: 10

Payments API

v2025-01-01

Other Versions

Create Order

Order

Authorizations

Headers

Body

Response