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.

Path Parameters

cf_terminal_id

integer

required

Provide the Cashfree terminal ID for which the details have to be updated.

Query Parameters

utr

string

required

Utr of the transaction.

Response

Fetch Terminal Transaction

terminal payment entity full object

cf_payment_id

string

order_id

string

entity

string

error_details

ErrorDetailsInPayments · object

The error details are present only for failed payments

Show child attributes

error_details.error_code

string

error_details.error_description

string

error_details.error_reason

string

error_details.error_source

string

error_details.error_code_raw

string

error_details.error_description_raw

string

error_details.error_subcode_raw

string

Example:

{
  "error_code": "TRANSACTION_DECLINED",
  "error_description": "issuer bank or payment service provider declined the transaction",
  "error_reason": "auth_declined",
  "error_source": "customer",
  "error_code_raw": "ZM",
  "error_description_raw": "INVALID / INCORRECT MPIN",
  "error_subcode_raw": ""
}

is_captured

boolean

order_amount

number

Order amount can be different from payment amount if you collect service fee from the customer

payment_group

string

Type of payment group. One of ['prepaid_card', 'upi_ppi_offline', 'cash', 'upi_credit_card', 'paypal', 'net_banking', 'cardless_emi', 'credit_card', 'bank_transfer', 'pay_later', 'debit_card_emi', 'debit_card', 'wallet', 'upi_ppi', 'upi', 'credit_card_emi']

payment_currency

string

payment_amount

number

payment_time

string

This is the time when the payment was initiated

payment_completion_time

string

This is the time when the payment reaches its terminal state

payment_status

enum<string>

The transaction status can be one of ["SUCCESS", "NOT_ATTEMPTED", "FAILED", "USER_DROPPED", "VOID", "CANCELLED", "PENDING"]

Available options:

SUCCESS,

NOT_ATTEMPTED,

FAILED,

USER_DROPPED,

VOID,

CANCELLED,

PENDING

payment_message

string

bank_reference

string

auth_id

string

authorization

AuthorizationInPayments · object

If preauth enabled for account you will get this body

Show child attributes

authorization.action

enum<string>

One of CAPTURE or VOID

Available options:

CAPTURE,

VOID

authorization.status

enum<string>

One of SUCCESS or PENDING

Available options:

SUCCESS,

PENDING

authorization.captured_amount

number

The captured amount for this authorization request

authorization.start_time

string

Start time of this authorization hold (only for UPI)

authorization.end_time

string

End time of this authorization hold (only for UPI)

authorization.approve_by

string

Approve by time as passed in the authorization request (only for UPI)

authorization.action_reference

string

CAPTURE or VOID reference number based on action

authorization.action_time

string

Time of action (CAPTURE or VOID)

Example:

{
  "action": "CAPTURE",
  "status": "PENDING",
  "captured_amount": 100,
  "start_time": "2022-02-09T18:04:34+05:30",
  "end_time": "2022-02-19T18:04:34+05:30",
  "approve_by": "2022-02-09T18:04:34+05:30",
  "action_reference": "6595231908096894505959",
  "action_time": "2022-08-03T16:09:51"
}

customer_details

CustomerDetails · 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

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"
}

payment_method

Card · object

The following code samples show the payment method object payload for different payment methods.

Card
Net banking
UPI
App
Cardless EMI
Pay later
Card EMI
Bank transfer

Show child attributes

payment_method.card

object

Show child attributes

payment_method.card.channel

string

The requested channel, can be link or post.

payment_method.card.card_number

string

The last four digits of the customer's card number. For external token transactions or external Alt ID transactions, this value is passed only when the merchant includes card_display in the Order Pay API request.

payment_method.card.card_network

string

The card scheme or network of the card. For example, visa, mastercard, rupay, amex, or diners.

payment_method.card.card_type

string

The type of card. For example, credit_card, debit_card, or prepaid_card.

payment_method.card.card_sub_type

string

The sub-type of card. R is Retail card, P is Premium card, C is Corporate card.

payment_method.card.card_country

string

The issuing country of the card. For example, IN.

payment_method.card.card_bank_name

string

The issuing bank of the card. For example, HDFC BANK, AXIS BANK, or ICICI BANK.

payment_method.card.card_network_reference_id

string

The authentication reference ID provided by the respective card network.

payment_method.card.instrument_id

string

The identifier for the card saved at Cashfree. This value is sent only for CF token transactions.

Example:

{
  "channel": "link",
  "card_number": "XXXXXXXXXXXX4738",
  "card_network": "visa",
  "card_type": "credit_card",
  "card_sub_type": "R",
  "card_country": "IN",
  "card_bank_name": "HDFC Bank",
  "card_network_reference_id": "100212023061229",
  "instrument_id": "3fc5814b-e732-4a71-b2ee-94b4f147d9e1"
}

payment_gateway_details

PaymentGatewayDetails · object

payment gateway details present in the webhook response

Show child attributes

payment_gateway_details.gateway_name

string

payment_gateway_details.gateway_order_id

string

payment_gateway_details.gateway_payment_id

string

payment_gateway_details.gateway_order_reference_id

string

payment_gateway_details.gateway_status_code

string

payment_gateway_details.gateway_settlement

string

payment_gateway_details.gateway_reference_name

string

Payments API

v2025-01-01

Other Versions

Get Terminal Transaction

Authorizations

Headers

Path Parameters

Query Parameters

Response