Skip to main content

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.

When processing payments through Cashfree Payments, orders and their associated payments progress through various states. Understanding these states helps you track transactions and handle different scenarios effectively.

​
Transaction lifecycle

The following diagram shows how transactions progress from order creation to final state:

​
Key concepts

Two critical concepts in payment flows are order expiry time and Transaction Time Limit (TTL). Understanding these concepts helps you manage your payment flows effectively.

​
Transaction time limit

Transaction Time Limit, also referred to as Transaction Completion Time (TCT), defines the maximum time allowed for a payment attempt.
During this period, the transaction will reach one of the following final statuses: SUCCESS, FAILED, or USER DROPPED.
It ensures predictable transaction behaviour and helps minimise financial risk for both merchants and customers.

​
Order expiry time

Order expiry time specifies the duration for which an order remains valid and can be used to initiate a new payment attempt.

​
Order expiry time vs TTL

ConceptStarts fromDefinitionBehaviour
Order expiry timeOrder creation time.Duration within which a customer must initiate a payment attempt.Once expired, no new payment attempts can be made.
Transaction time limitWhen the customer selects a payment method.Maximum time allowed for the last payment attempt to reach a terminal state.Even if the order expiry time passes, the last attempt is honoured until the TTL ends.

​
Order finalisation process

The following steps describe how a payment is finalised:
  1. Payment succeeds within TTL → Order is PAID, even if order expiry time passed.
  2. An order marked as EXPIRED can still move to PAID if a payment attempt was started before the expiry and completed successfully within the TTL window, even if the confirmation comes after the expiry time.
  3. If payment fails or the user drops → Order remains EXPIRED.
  4. When TTL ends, any non-terminal payments are automatically closed in a terminal state.

​
How order expiry time and TTL work

  • Order creation time: 10:00 AM
  • Order expiry time: 15 minutes
  • TTL: 20 minutes
Example scenarios:
  1. No payment attempt: If the customer does not select any payment method → Order moves from ACTIVE to EXPIRED at 10:15 AM
  2. Payment attempt before expiry:
    • Customer selects a payment method at 10:02 AM
    • TTL starts → transaction allowed until 10:22 AM
    • Even though the order expiry time is 10:15 AM, since a payment attempt is in progress, Cashfree waits until 10:22 AM
    • At 10:15 AM order moved to EXPIRED status.
    • If payment succeeds at 10:21 AM → Order status will change from EXPIRED to PAID.
    • If payment fails or is dropped → Order remains EXPIRED.

​
Order TTL flowchart

The following flowchart shows how order expiry time and TTL affect an order’s final state:
Order TTL Flowchart

​
Significance of TTL

TTL helps prevent financial loss and ensures a smoother customer experience in scenarios such as:
  • Customers initiate payment just before order expiry.
  • Banks or Payment Service Providers (PSPs) take additional time to confirm transactions.
If payments that succeed after expiry were rejected, Cashfree would incur financial loss since the bank would still charge for the transaction, but Cashfree would neither settle the funds nor reverse them.

​
Use cases

TTL is especially critical for industries where prices fluctuate rapidly, such as stock trading platforms, airline ticket sales, commodities, and flash sales. Example: Flight fares may change every minute. With TTL, once a customer locks a price by initiating payment, Cashfree continues to wait for confirmation even if the order has technically expired, ensuring the transaction is honoured at the locked price.

​
Configure order expiry time and TTL

Follow these steps to configure order expiry time and TTL in the Merchant Dashboard:
  1. Log in to the Merchant Dashboard.
  2. Navigate to Settings > Preferences.
  3. Set order expiry time: Minimum 5 minutes, maximum 30 days.
  4. Set TTL: Minimum 10 minutes, maximum 24 hours.
  5. Click Save Changes to apply your updates.

​
Order states

Order StateDescriptionRemarks
ACTIVEOrder is created and ready for payment.Initial state for all newly created orders.
PAIDPayment is verified and successful.Terminal state indicating the order is fully paid.
EXPIREDOrder has exceeded the order_expiry_time specified during creation.Further payment attempts are not allowed.
TERMINATEDOrder is ended using the Order Termination API.Permanent terminal state; customers can no longer pay.
TERMINATION_REQUESTEDCall to the Order Termination API is acknowledged and processing.If a pending transaction succeeds during this state, the order transitions to PAID instead of TERMINATED.

​
Payment states

Payment StateDescriptionRemarks
SUCCESSTransaction is successful and the amount is captured.Terminal state. Once successful, the order moves to PAID.
FAILEDTransaction failed due to bank, customer, or system issues.Terminal state. Customers can initiate a new attempt.
NOT_ATTEMPTEDTransaction is created but acknowledgement from the bank is awaited.Initial state for a payment attempt.
PENDINGRequest is sent to the bank and a response is awaited.Non-terminal state. Do not fulfil orders in this state.
FLAGGEDTransaction is identified as high-risk and requires review.Merchant must manually approve or reject the payment.
CANCELLEDAmount is reversed because a success response arrived after the time to live (TTL).Automatic system reversal for late confirmations.
VOIDTransaction amount is not captured by explicit request.Typically used for pre-authorised card payments or UPI mandates.
USER_DROPPEDCustomer abandoned the payment flow before completion.Includes closing the app or OTP page without attempting payment.