Skip to main content
This migration guide is for merchants on version V1 or V2. Merchants using version V3 (2022-09-01) don’t need to use this as their migration guide. Please check changes from V3 here.

​
New payment gateway integration flow

​
1. Change API version

Change x-api-version in header to 2023-08-01

​
2. Create order from backend

You’ll get payment_session_id in the response of create order (instead of order_token and payment_link) Below is the request and response you get when you create a order. Request 
import { Cashfree } from "cashfree-pg"; 

Cashfree.XClientId = {Client ID};
Cashfree.XClientSecret = {Client Secret Key};
Cashfree.XEnvironment = Cashfree.Environment.PRODUCTION;

function createOrder() {
  var request = {
    "order_amount": "1",
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "node_sdk_test",
      "customer_name": "",
      "customer_email": "[email protected]",
      "customer_phone": "9999999999"
    },
    "order_meta": {
      "return_url": "https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123"
    },
    "order_note": ""
  }

  Cashfree.PGCreateOrder("2023-08-01", request).then((response) => {
    var a = response.data;
    console.log(a)
  })
    .catch((error) => {
      console.error('Error setting up order request:', error.response.data);
    });
}
Response 
{
  "cf_order_id": "1539553",
  "created_at": "2021-07-19T16:13:35+05:30",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_name": null,
    "customer_email": "[email protected]",
    "customer_phone": "9908734801",
    "customer_uid": null
  },
  "entity": "order",
  "order_amount": 5.01,
  "order_currency": "INR",
  "order_expiry_time": "2021-08-18T16:13:34+05:30",
  "order_id": "order_271vWwzSQOHe01ZVXpEcguVxQSRqr",
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123",
    "payment_methods": null
  },
  "order_note": null,
  "order_status": "PAID",
  "payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD"
}
If you want to create a split order - create a order with Split from backend. You will get the ‘payment_session_id’ in the response of create order (instead of order_token and payment_link). Below is the request and the response when you create a order with split. 
curl --request POST \
     --url https://sandbox.cashfree.com/pg/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-version: 2023-08-01' \
     --header 'x-client-id: xxxx' \
     --header 'x-client-secret: xxxx' \
     --data '
{
     "customer_details": {
          "customer_id": "7112AAA812234",
          "customer_email": "[email protected]",
          "customer_phone": "9908734801",
          "customer_bank_ifsc": "CITI0000001",
          "customer_bank_account_number": "1518121112",
          "customer_bank_code": 3333
     },
     "order_splits": [
          {
               "vendor_id": "Vendor01",
               "amount": 100
          },
          {
               "vendor_id": "Vendor02",
               "amount": 200
          }
     ],
     "order_amount": 400.15,
     "order_id": "386752t78",
     "order_currency": "INR",
     "order_expiry_time": "2023-02-29T00:00:00Z",
     "order_note": "Test order"
}
'

​
3. Use new JS SDK to redirect to pre-built checkout

Once you receive payment_session_id from create order response, you need to use Cashfree’s JS SDK.

​
Step 1: Include our SDK in your client code

Including the Script Tag. Import the URL in the snippet below to your HTML file.
HTML
<script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
OR Install from npm
Shell
npm install @cashfreepayments/cashfree-js

​
Step 2: Initialize the SDK

You need to initialise the variable using the Cashfree() function. There are two modes applicable for this - “sandbox” or “production”. Sandbox is used for test environment, whereas production is used for production mode. 
const cashfree = Cashfree({
    mode:"sandbox" //or production
});

​
Step 3: Redirect to checkout

To open the checkout, you can use cashfree.checkout()method. 
cf.checkout();

​
4. Handle redirection and confirm status

  1. Check status of the order.
  2. Redirection to return_url happens the same way as before. However, format of return_url doesn’t contain order-token now.
    New format https://test.cashfree.com/pgappsdemos/return.php?order_id={order_id}

​
5. Whitelist domain

New integration will require whitelisting of the domain which is used to open the checkout page. You can request for a domain whitelisting via developers>whitelisting in your merchant dashboard or submit a Support Form.
You can check step-by-step process of making whitelisting request here.
New integration only supports opening of the checkout page via the whitelisted domain. Any other domain used to open the checkout page will be blocked by Cashfree and checkout page will not open.