Cashfree Payments Developer Documentation

curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "payment_session_id": "session__someidwhichislongandhasnumbers1232132andcharacterscn",
  "transaction_expiry_time": "2021-07-02T10:20:12+05:30",
  "payment_method": {
    "upi": {
      "channel": "link"
    }
  }
}
'

{
  "action": "link",
  "cf_payment_id": "4105073870",
  "channel": "link",
  "payment_amount": 1.75,
  "payment_method": "card",
  "data": {
    "url": "https://api.cashfree.com/pg/view/gateway/session_FEeYTISZ-xOJcuR7YeOZOm1MhVIrjHa2l1G79Pg_ZktVJxPSdu7oAKf9RTFZQlR19lkBU7VGIh8dARedu9otO8VstZVT3-HpjLpIn75v-hKCNOxYuEOV_wJ975ed89f2-ad57-4094-8728-7cff9f1928f2",
    "payload": null,
    "content_type": null,
    "method": null
  }
}

POST

orders

sessions

curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "payment_session_id": "session__someidwhichislongandhasnumbers1232132andcharacterscn",
  "transaction_expiry_time": "2021-07-02T10:20:12+05:30",
  "payment_method": {
    "upi": {
      "channel": "link"
    }
  }
}
'

{
  "action": "link",
  "cf_payment_id": "4105073870",
  "channel": "link",
  "payment_amount": 1.75,
  "payment_method": "card",
  "data": {
    "url": "https://api.cashfree.com/pg/view/gateway/session_FEeYTISZ-xOJcuR7YeOZOm1MhVIrjHa2l1G79Pg_ZktVJxPSdu7oAKf9RTFZQlR19lkBU7VGIh8dARedu9otO8VstZVT3-HpjLpIn75v-hKCNOxYuEOV_wJ975ed89f2-ad57-4094-8728-7cff9f1928f2",
    "payload": null,
    "content_type": null,
    "method": null
  }
}

Run in Postman: You can also try this API in our Postman Collection.

Client environment headers

Cashfree requires information about the customer’s device environment to enforce NPCI rules. You must include the following headers in your Order Pay API and Get Eligible Payment Methods request:

Client environment headers

Header	Accepted values	Requirement	Description
`x-client-device`	`mobile`, `desktop`, `tablet`	Required	Type of device used by customer
`x-client-os`	`android`, `ios`, `windows`, `macos`, `linux`, `others`	Required	Operating system of customer’s device
`x-client-rendering-type`	`mweb`, `webview`, `native`	Required when `x-client-device` is mobile	Rendering method used for the checkout experience
`x-client-browser`	`safari`, `chrome`, `firefox`, `edge`, `others`	Required	Browser used by the customer

x-client-rendering-type is required only when x-client-device is set to mobile. For desktop and tablet devices, this header is optional.

Error codes

The following table lists the error codes, descriptions, and types you may encounter when initiating a payment:

Error codes

Code	Description	Type	Status
`channel_missing`	The `channel` field is required but was not included in the request.	`invalid_request_error`	400
`phone_invalid`	The `phone` field must contain a valid 10-digit Indian phone number (for example, `9090407368`). Value received: `1234567890`	`invalid_request_error`	400
`phone_missing`	The `phone` field is required but was not included in the request.	`invalid_request_error`	400
`provider_missing`	The `provider` field is required but was not included in the request.	`invalid_request_error`	400
`version_missing`	The `version` field must be one of the following supported values: `2021-05-21`, `2022-01-01`, `2022-09-01`, `2023-08-01`, `2025-01-01`, or `2026-01-01`.	`invalid_request_error`	400
`card_cvv_invalid`	The `card_cvv` field must be at least 3 characters long. Value received: `12`	`invalid_request_error`	400
`card_cvv_missing`	The `card_cvv` field is required but was not included in the request.	`invalid_request_error`	400
`card_invalid`	The `card` field is invalid. Provide payment details using one of the following: card details, `card_alias`, `instrument_id`, or `cryptogram`.	`invalid_request_error`	400
`bank_processing_failure`	The transaction could not be created at the banking partner. Retry the request or contact support if the issue persists.	`api_error`	502
`request_invalid`	Cards issued in India cannot be used for transactions where the order currency is non-INR. Value received: `AUD`	`invalid_request_error`	400
`orderpay_not_found`	The specified order is no longer active and cannot be used to initiate a payment.	`invalid_request_error`	404
`card_bank_name_missing`	The `card_bank_name` field is required but was not included in the request.	`invalid_request_error`	400
`card_bank_name_invalid`	The `card_bank_name` field contains an unrecognised value. Accepted values are: `hdfc`, `icici`, `kotak`, `rbl`, `bob`, `axis`, `standard chartered`, `au`, `yes`, `indus`, `fed`, `hsbc`, `citi`, `sbi`, `amex`, `onecard`, or `idfc`. Value received: `INVALID$BANK`	`invalid_request_error`	400
`card_expiry_yy_missing`	The `card_expiry_yy` field is required but was not included in the request.	`invalid_request_error`	400
`card_expiry_yy_invalid`	The `card_expiry_yy` field must be at least 2 characters long. Value received: `0`	`invalid_request_error`	400
`card_expiry_mm_missing`	The `card_expiry_mm` field is required but was not included in the request.	`invalid_request_error`	400
`card_expiry_mm_invalid`	The `card_expiry_mm` field must be at least 2 characters long. Value received: `0`	`invalid_request_error`	400
`card_number_invalid`	The `card_number` field contains an invalid card number. Verify the card number and try again. Value received: `INVALID`	`invalid_request_error`	400
`card_number_missing`	The `card_number` field is required but was not included in the request.	`invalid_request_error`	400
`card_not_found`	The card details could not be retrieved. Verify the card information and try again.	`invalid_request_error`	404
`emi_tenure_missing`	The `emi_tenure` field is required but was not included in the request.	`invalid_request_error`	400
`order_amount_invalid`	The order amount exceeds the maximum allowed value. The amount must be less than `1,000,000`.	`invalid_request_error`	400
`netbanking_account_number_invalid`	The `netbanking_account_number` field must be at least 9 characters long. Value received: `test`	`invalid_request_error`	400
`netbanking_bank_code_invalid`	The `netbanking_bank_code` field contains an invalid value. Provide a supported bank code and try again.	`invalid_request_error`	400
`netbanking_ifsc_invalid`	The `netbanking_ifsc` field contains an invalid IFSC code. Verify the IFSC and try again. Value received: `INVALID`	`invalid_request_error`	400
`request_failed`	The selected payment mode is not configured for this account. Enable the payment mode or contact support.	`invalid_request_error`	400
`currency_invalid`	The `currency` field does not accept `INR` for this request. Use a supported non-INR currency. Value received: `INR`	`invalid_request_error`	400
`currency_missing`	The `currency` field is required but was not included in the request.	`invalid_request_error`	400
`risk_data.customer_ip_invalid`	The `risk_data.customer_ip` field contains an invalid IP address. Provide a valid IPv4 or IPv6 address. Value received: `1.1.1`	`invalid_request_error`	400
`risk_data_ip_address_request_failed`	The IP address could not be resolved. Verify the IP address and try again.	`invalid_request_error`	400
`order_token_missing`	The `order_token` field is required but was not included in the request.	`invalid_request_error`	400
`payment_method_invalid`	The `payment_method` field contains an unrecognised value. Provide a valid payment method and try again.	`invalid_request_error`	400
`payment_method_missing`	The `payment_method` field is required but was not included in the request.	`invalid_request_error`	400
`payment_method_unsupported`	The specified payment method is not supported for this request. Use a supported payment method and try again.	`invalid_request_error`	400

Headers

x-api-version

string

default:2025-01-01

required

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 parameters to Order Pay.

payment_session_id

string

required

Unique identifier for the payment session, returned in the response of the Create Order API.

Example:

"session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn"

payment_method

CardPaymentMethod · object

required

Payload for different payment methods is given below.

Show child attributes

save_instrument

boolean

Send as true if the customer has given consent to save or tokenise the card; otherwise, send as false.

offer_id

string

This is required if any offers needs to be applied to the order.

Example:

"faa6cc05-d1e2-401c-b0cf-0c9db3ff0f0b"

transaction_expiry_time

string<ISO8601>

The maximum time for the payment attempt to reach a terminal state. If this timestamp expires, the transaction is marked as failed and cannot be retried. Provide the value in ISO 8601 timestamp format. Timestamps are stored in IST. IST appears as 2021-07-02T10:20:12+05:30, UTC appears as 2021-07-02T10:20:12Z.

Example:

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

Response

Success response for Order Pay.

Order pay response once you create a transaction for that order.

payment_amount

number

Total amount payable.

cf_payment_id

string<int64>

Payment identifier created by Cashfree.

payment_method

enum<string>

The payment method used for this transaction.

netbanking: Net banking payment.
card: Credit or debit card payment.
upi: UPI payment via collect, intent, or QR code.
app: Wallet-based payment.
cardless_emi: Cardless EMI payment.
paylater: Pay later payment.
banktransfer: Direct bank transfer payment.
applepay: Apple Pay payment.

Available options:

netbanking,

card,

upi,

app,

cardless_emi,

paylater,

banktransfer,

applepay

channel

enum<string>

The channel used for the payment method.

link: Redirect-based flow where the customer is taken to an external page.
post: Native OTP flow where the merchant renders a custom UI to collect OTP.
collect: UPI collect request sent to the customer's VPA.
qrcode: UPI QR code for the customer to scan.
podQrCode: Pay on delivery QR code.

Available options:

link,

post,

collect,

qrcode,

podQrCode

action

enum<string>

The action to complete the payment.

link: Redirect the customer to data.url using a browser or in-app webview.
post: Render a native UI, collect required input, and POST it to data.url.
form: Render the form from data.payload and auto-submit it to data.url.
custom: Follow integration-specific instructions or SDK handling.

Available options:

link,

post,

custom,

form

data

OrderPayData · object

The data object of Order Pay API.

Show child attributes

Update Order Extended Submit or Resend OTP

⌘I

​Client environment headers

​Error codes

Headers

Body

Response

Client environment headers

Error codes