> ## 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.

# Overview

> Plan your upgrade from older Cashfree Payment Gateway V3 APIs to V4 with this overview of breaking changes, new capabilities, and recommended migration steps.

If you're migrating from the last version i.e. 2022-09-01 (V3), following are the key changes made in this latest version 2023-08-01 (V4).

1. **Cashfree IDs type change**  \[BREAKING]\
   All cashfree IDs like `cf_order_id`, `cf_payment_id`, `cf_refund_id` etc are now in **string** format instead of **integer** (in older versions).

2. **Order Entity Changes**
   1. We have removed payments, refunds, settlements urls from order entity.
   2. `customer_uid` part of customer\_details in order entity. This is the unique identifier of the customer created at Cashfree. You can create customer at cashfree using [Create Customer API](/api-reference/payments/latest/customers/create)
   3. `order_status` can have two more values - "TERMINATED" and "TERMINATION\_REQUESTED".

3. \*\*New Order Termination API \*\*\
   We have released a new API to terminate an Order. Find API details - [Order Termination API.](/api-reference/payments/latest/orders/terminate)

4. **New Customer APIs**\
   We have released Customer APIs to let merchants create and manager their customers. Find more about this here - [Customer Management](/api-reference/payments/latest/customers/create)

5. **CF Refund IDs**\
   Earlier cf\_refund\_id used to start with a prefix "refund\_". In this version, you will not get that prefix and cf\_refund\_id will be directly be the id without any prefix. Example - OLD cf\_refund\_id = "refund\_41805719", NEW cf\_refund\_id = "41805719"

## Migration from version V1 or V2

In the this latest version, we have revamped the integration method for using our pre-built checkout and made some changes in our SDKs.

Following are the key changes made in the latest version. Please check respective pages for detailed changes.

1. **Create Order API Change**\
   Deprecated use of order\_token and payment\_link from our APIs and instead introduced `payment_session_id` in response of [Create Order](/api-reference/payments/latest/orders/create) APIs. Hence, you cannot redirect the customer to the checkout page just by using the API. You'll need to use our JS SDK for starting checkout.
2. **New Javascript SDK**\
   Released new improvised JS SDK which will take in `payment_session_id` to redirect to checkout. This is a single SDK which can be used to either redirect the customer to checkout or render components check [JS Component Integration](/payments/online/element/introduction).
3. **New Order Pay API**\
   New endpoint for [order pay API](/api-reference/payments/latest/payments/pay) is released. This will take `payment_session_id` as body parameter instead of `order_token`
4. **New SDKs**\
   Going forward, all SDKs will use `payment_session_id` instead of `order_token` to complete the payment.
5. **Whitelisting of domain name/package name**\
   All new integrations require whitelisting of domain or app package from where the checkout page is being opened. If you're using web integration, please whitelist your website domain name. If you're using a mobile app, please whitelist the app package name.\
   You can check the step-by-step process of [making a whitelisting request](/payments/online/go-live/whitelist#whitelist-your-website-or-app).
6. **Cashfree IDs type change**\
   All cashfree IDs like `cf_order_id`, `cf_payment_id`, `cf_refund_id` etc are now in **string** format instead of integer (in older versions).

## Benefits

* **Performance Enhancement**: We've rebuilt our APIs with state-of-the-art technologies to ensure low latency and high Transactions Per Second (TPS).
* **Simplified Integration**: The v3 APIs now support JSON payload, providing a more user-friendly alternative to form-encoded data.
* **Payment Mode Visibility**: Easily identify the payment modes enabled for your account using the v3 APIs.
* **Offer Suite Integration**: Create offers directly from your server across various payment modes using our offer suite.
* **Expanded Payment Methods**: V3 APIs support newer payment methods such as Buy Now Pay Later and Cardless EMI.
* **Wider Card EMI Support**: Enjoy support for 10+ banks on card EMI transactions including Debit Cards.
* **Streamlined Error Handling**: We've enhanced error handling for clearer and more concise messages.
* **Entity-Based Responses**: All v3 responses are entity-based, consolidating details for a specific entity (e.g., order) in a single JSON response.
* **Order Termination API**: Stop an order from accepting payments using the v3 API's order termination capability.\
  Improved Webhooks: Our webhooks provide more comprehensive details about your orders and transactions.
* **Bank Error**: Introducing error codes directly from our banking partners for better troubleshooting.
* **Customer Eligibility Check:** Easily check customer eligibility on different pay-later and cardless modes using their phone number.
* **Customer Management**: Create customers at Cashfree and save their favourite payment methods with v3 APIs.
* **SDK Support**: We've developed SDKs for Go, Java, NodeJS/Typescript, PHP, C#, and Python.
* **Whitelisting**: Critical flow like Checkout and Payment can now be whitelisted to be only initiated from a particular domain or app.

### New tools

* **Devtools**: Monitor errors, webhook responses, and Rate limits in your API calls.
* **Integration Usage**: Gain insights into your integration through detailed reports.
* **Customer Dashboard**: Analyse patterns and payment trends of your customers.