> ## Documentation Index > Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Authorisation Only > Use this API to authorise payment sessions using token-based authentication. ## OpenAPI ````yaml post /orders/sessions/authorize openapi: 3.0.3 info: title: Cashfree - Orders Pay Authorise - Sandbox description: API to authorise a payment session in sandbox environment. version: '2026-01-01' servers: - url: https://sandbox.cashfree.com/pg description: Sandbox. security: [] paths: /orders/sessions/authorize: post: tags: - Payments summary: Authorisation Only description: >- Use this API to authorise payment sessions using token-based authentication. parameters: - $ref: '#/components/parameters/apiVersionHeader' - $ref: '#/components/parameters/xRequestIDHeader' - $ref: '#/components/parameters/xIdempotencyKeyHeader' requestBody: $ref: '#/components/requestBodies/PayOrderRequest' responses: '200': description: Payment authorised successfully. content: application/json: schema: $ref: '#/components/schemas/PayOrderAuthorizationEntity' examples: success: value: auth_id: '302651' authorization: null bank_reference: '524410198110' cf_payment_id: '4304193706' entity: payment error_details: null international_payment: international: false is_captured: false order_amount: 1 order_currency: INR order_id: CFPay_payme_rohittest_3vv0ethp9r payment_amount: 1 payment_completion_time: '2025-09-01T15:42:38+05:30' payment_currency: INR payment_gateway_details: gateway_name: CASHFREE gateway_order_id: CF_ORDER_987654321 gateway_payment_id: CF_PAY_123456789 gateway_order_reference_id: REF_ORD_2025010112345 gateway_status_code: SUCCESS gateway_settlement: cashfree gateway_reference_name: APPLE_PAY_TXN_REF payment_group: debit_card payment_message: PRE_AUTH|Transaction Success payment_method: card: card_bank_name: KOTAK MAHINDRA BANK card_country: IN card_network: visa card_network_reference_id: VIS_REF_20250101123456 card_number: XXXXXXXXXXXX4738 card_sub_type: R card_type: debit_card channel: link instrument_id: 0dca46b1-01f7-4a60-9e4a-ae5474603563 par: V0010014623022637739353641436 payment_offers: [] payment_status: SUCCESS payment_surcharge: payment_surcharge_service_charge: 0 payment_surcharge_service_tax: 0 payment_time: '2025-09-01T15:40:58+05:30' headers: x-api-version: $ref: '#/components/headers/x-api-version' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-retry: $ref: '#/components/headers/x-ratelimit-retry' x-ratelimit-type: $ref: '#/components/headers/x-ratelimit-type' x-request-id: $ref: '#/components/headers/x-request-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key' x-idempotency-replayed: $ref: '#/components/headers/x-idempotency-replayed' '400': $ref: '#/components/responses/Response400' '401': $ref: '#/components/responses/Response401' '404': $ref: '#/components/responses/Response404' '409': $ref: '#/components/responses/Response409' '422': $ref: '#/components/responses/Response422' '429': $ref: '#/components/responses/Response429' '500': $ref: '#/components/responses/Response500' '502': $ref: '#/components/responses/Response502' security: [] components: parameters: apiVersionHeader: in: header name: x-api-version required: true description: API version to be used. Format is YYYY-MM-DD. schema: type: string default: '2026-01-01' example: '2026-01-01' x-ignore: true xRequestIDHeader: in: header name: x-request-id description: Request id for the API call. Can be used to resolve tech issues. required: false schema: type: string example: 4dfb9780-46fe-11ee-be56-0242ac120002 xIdempotencyKeyHeader: in: header name: x-idempotency-key required: false description: > 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. schema: type: string format: UUID example: 47bf8872-46fe-11ee-be56-0242ac120002 requestBodies: PayOrderRequest: description: Request body to authorise the payment transaction. required: true content: application/json: schema: type: object properties: payment_session_id: type: string description: >- Unique identifier for the payment session, returned in the response of the Create Order API. example: >- session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn authorization_data: $ref: '#/components/schemas/AuthorizationData' required: - payment_session_id - authorization_data examples: token: summary: Token Example value: payment_session_id: >- session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn authorization_data: authentication_token: BwABBJQ1AgAAAAAgJDUCAAAAAAA= directory_server_transaction_id: 8ac7b70f-9c5c-4e8f-9f4a-6d7c8b2a1e3f three_ds_server_transaction_id: 9b8a7c6d-5e4f-3210-9876-543210fedcba eci: '02' token_number: '4111111111111111' token_expiry_year: '2029' token_expiry_month: '09' token_cryptogram: /wAAAAAAUSwFGXgAAAAAgPAAAA= transaction_type: TOKEN alt_id: summary: AltId Example value: payment_session_id: >- session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn authorization_data: authentication_token: BwABBJQ1AgAAAAAgJDUCAAAAAAA= directory_server_transaction_id: 8ac7b70f-9c5c-4e8f-9f4a-6d7c8b2a1e3f three_ds_server_transaction_id: 9b8a7c6d-5e4f-3210-9876-543210fedcba eci: '02' token_number: '4111111111111111' token_expiry_year: '2029' token_expiry_month: '09' token_cryptogram: /wAAAAAAUSwFGXgAAAAAgPAAAA= transaction_type: ALT_ID applePay: summary: Apple Pay Example description: > This sample shows how to pass Apple Pay details. Map the fields directly from Apple’s `token.paymentData.data` object: - `authentication_token` → `onlinePaymentCryptogram` - `eci` → `eciIndicator` - `token_number` → `applicationPrimaryAccountNumber` - `token_expiry_year` → `applicationExpirationDate` in YY format - `token_expiry_month` → `applicationExpirationDate` in MM format value: payment_session_id: >- session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn authorization_data: authentication_token: BwABBJQ1AgAAAAAgJDUCAAAAAAA= eci: '05' token_number: '4111111111111111' token_expiry_year: '2029' token_expiry_month: '06' transaction_type: APPLE_PAY schemas: PayOrderAuthorizationEntity: type: object properties: auth_id: type: string example: '302651' authorization: nullable: true description: Additional authorisation object if available. bank_reference: type: string example: '524410198110' cf_payment_id: type: string example: '4304193706' entity: type: string example: payment error_details: nullable: true international_payment: $ref: '#/components/schemas/InternationalPayment' is_captured: type: boolean example: false order_amount: type: number format: double example: 1 order_currency: type: string example: INR order_id: type: string example: CFPay_payme_rohittest_3vv0ethp9r payment_amount: type: number format: double example: 1 payment_completion_time: type: string format: date-time example: '2025-09-01T15:42:38+05:30' payment_currency: type: string example: INR payment_gateway_details: $ref: '#/components/schemas/PaymentGatewayDetails' payment_group: type: string example: debit_card payment_message: type: string example: PRE_AUTH|Transaction Success payment_method: type: object properties: card: $ref: '#/components/schemas/Card' payment_offers: type: array items: type: object payment_status: type: string example: SUCCESS payment_surcharge: $ref: '#/components/schemas/PaymentSurcharge' payment_time: type: string format: date-time example: '2025-09-01T15:40:58+05:30' AuthorizationData: type: object description: 3DS / token authorisation details. properties: authentication_token: type: string description: > Authentication token / cryptogram. For Apple Pay, map from `token.paymentData.data.onlinePaymentCryptogram`. example: BwABBJQ1AgAAAAAgJDUCAAAAAAA= directory_server_transaction_id: type: string description: > Required for txn with native 3DS flow. Optional for Apple Pay or other token-based flows. example: 8ac7b70f-9c5c-4e8f-9f4a-6d7c8b2a1e3f three_ds_server_transaction_id: type: string description: > Required for txn with native 3DS flow. Optional for Apple Pay or other token-based flows. example: 9b8a7c6d-5e4f-3210-9876-543210fedcba eci: type: string description: > E-Commerce Indicator. - Mandatory for 3DS flow - For Apple Pay: pass `eciIndicator` if provided by wallet. - Optional field. example: '02' token_number: type: string description: > Tokenised Primary Account Number (PAN). For Apple Pay, map from `applicationPrimaryAccountNumber`. example: '4111111111111111' token_expiry_year: type: string description: > Expiry year in YY format. For Apple Pay, extract from `applicationExpirationDate`. example: '29' token_expiry_month: type: string description: > Expiry month in MM format. For Apple Pay, extract from `applicationExpirationDate`. example: '06' token_cryptogram: type: string description: > Required for txn with native 3DS flow. Optional for Apple Pay or other token-based flows. Not used in Apple Pay. example: /wAAAAAAUSwFGXgAAAAAgPAAAA= transaction_type: type: string description: > Type of tokenisation flow. Example values: `TOKEN`, `ALT_ID`, `APPLE_PAY` or similar. example: TOKEN/ALT_ID/APPLE_PAY InternationalPayment: type: object properties: international: type: boolean example: false PaymentGatewayDetails: type: object properties: gateway_name: type: string description: Name of the payment gateway processor. example: CASHFREE gateway_order_id: type: string nullable: true description: Order identifier from the gateway processor. example: CF_ORDER_987654321 gateway_payment_id: type: string nullable: true description: Payment identifier from the gateway processor. example: CF_PAY_123456789 gateway_order_reference_id: type: string nullable: true description: Reference identifier for the order at gateway level. example: REF_ORD_2025010112345 gateway_status_code: type: string nullable: true description: Status code returned by the gateway processor. example: SUCCESS gateway_settlement: type: string description: Settlement method used by the gateway. example: cashfree gateway_reference_name: type: string nullable: true description: Reference name or identifier from the gateway. example: APPLE_PAY_TXN_REF Card: type: object properties: card_bank_name: type: string description: Name of the issuing bank for the card. example: KOTAK MAHINDRA BANK card_country: type: string description: ISO country code of the card issuing country. example: IN card_network: type: string description: Card network or scheme like Visa, Mastercard, etc. example: visa card_network_reference_id: type: string nullable: true description: Reference ID from the card network for this transaction. example: VIS_REF_20250101123456 card_number: type: string description: Masked card number showing only last 4 digits. example: XXXXXXXXXXXX4738 card_sub_type: type: string description: Card sub-type classification R for Regular, P for Premium, etc. example: R card_type: type: string description: Type of card like credit_card, debit_card, prepaid_card. example: debit_card channel: type: string description: Payment channel used for the transaction. example: link instrument_id: type: string description: Unique identifier for the payment instrument. example: 0dca46b1-01f7-4a60-9e4a-ae5474603563 par: type: string description: Payment Account Reference, unique identifier for the card account. example: V0010014623022637739353641436 PaymentSurcharge: type: object properties: payment_surcharge_service_charge: type: number format: double example: 2.36 payment_surcharge_service_tax: type: number format: double example: 0.42 ApiErrorGeneric: type: object properties: message: type: string description: Human-readable error message explaining what went wrong. code: type: string description: Machine-readable error code for programmatic handling. type: type: string example: message: Invalid Apple Pay cryptogram or missing required authorisation data code: invalid_request type: invalid_request_error ApiError404: title: ApiError404 description: Error when resource requested is not found. type: object properties: message: type: string description: >- Human-readable error message explaining that the requested resource was not found. code: type: string description: >- Machine-readable error code identifying the specific resource not found. help: type: string description: Helpful guidance on how to resolve the not found error. type: type: string enum: - invalid_request_error description: Invalid request error. example: message: Payment session not found or has expired help: >- Verify the payment_session_id is correct and hasn't expired. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9 code: payment_session_not_found type: invalid_request_error ApiError409: title: ApiError409 description: Duplicate request. type: object properties: message: type: string description: >- Human-readable error message explaining the conflict or duplicate request. help: type: string description: Helpful guidance on how to resolve the conflict error. code: type: string description: Machine-readable error code identifying the specific conflict type. type: type: string enum: - invalid_request_error description: Invalid request error. example: message: Payment has already been processed for this session help: >- Each payment session can only be used once. Create a new order and payment session for additional transactions. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9 code: payment_already_exists type: invalid_request_error ApiError502: title: ApiError502 description: Error when there is error at partner bank. type: object properties: message: type: string description: Human-readable error message explaining the bank processing failure. help: type: string description: Helpful guidance on how to resolve the bank processing error. code: type: string description: | `bank_processing_failure` will be returned here to denote failure at bank. type: type: string enum: - api_error description: API error. example: message: Apple Pay transaction declined by issuing bank help: >- The customer's bank declined the Apple Pay transaction. Advise customer to try a different payment method or contact their bank. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9 code: bank_processing_failure type: api_error headers: x-api-version: description: >- This header has the version of the API. The current version is `2026-01-01`. schema: type: string format: YYYY-MM-DD enum: - '2026-01-01' example: '2026-01-01' x-ratelimit-limit: description: Ratelimit set for your account for this API per minute. schema: type: integer example: 200 x-ratelimit-remaining: description: Rate limit remaining for your account for this API in the next minute. schema: type: integer example: 2 x-ratelimit-retry: description: Contains number of seconds to wait if rate limit is breached. schema: type: integer example: 4 x-ratelimit-type: description: Either ip or app_id. schema: type: string enum: - app_id - ip example: ip x-request-id: description: Request id for your API call, echoed back in response. schema: type: string example: 4dfb9780-46fe-11ee-be56-0242ac120002 x-idempotency-key: description: Idempotency key echoed back by server if supplied. schema: type: string example: 47bf8872-46fe-11ee-be56-0242ac120002 x-idempotency-replayed: description: > In conjunction with `x-idempotency-key` this means: - `true` if the response was replayed - `false` if the response has not been replayed schema: type: string format: boolean example: 'true' responses: Response400: description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorGeneric' Response401: description: Unauthorised. content: application/json: schema: $ref: '#/components/schemas/ApiErrorGeneric' Response404: description: Not found. content: application/json: schema: $ref: '#/components/schemas/ApiError404' Response409: description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ApiError409' Response422: description: Unprocessable entity. content: application/json: schema: $ref: '#/components/schemas/ApiErrorGeneric' Response429: description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/ApiErrorGeneric' Response500: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiErrorGeneric' Response502: description: Bad gateway - bank processing failure. content: application/json: schema: $ref: '#/components/schemas/ApiError502' ````