Migration to latest Version V4

Migration from Version V3

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
   3. order_status can have two more values - "TERMINATED" and "TERMINATION_REQUESTED". Find the complete list of order statuses here

3. New Order Termination API
   We have released a new API to terminate an Order. Find API details - Order Termination API.

4. New Customer APIs
   We have released Customer APIs to let merchants create and manager their customers. Find more about this here - Customer Management

5. CF Refund IDs
   Earlier cfrefund_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 APIs. Hence, you can not 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.
3. New Order Pay API
   New endpoint for order pay API 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 step-by-step process of making whitelisting request here.
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 favorite 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: Analyze patterns and payment trends of your customers.

Quickstart

Try out our interactive guides to understand out latest integration without any coding!

Integration Migration