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

# Migration to Version 2023-08-01

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 the [migration overview](/payments/migration/overview) for changes from V3.

## 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](/api-reference/payments/latest/orders/create) (instead of order\_token and payment\_link)

Below is the request and response you get when you create an order.

**Request**

<CodeGroup>
  ```typescript Typescript theme={"dark"}
  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": "example@gmail.com",
        "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);
      });
  }
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go Go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
  }

  }
  ```

  ```csharp C# theme={"dark"}
  using cashfree_pg.Client;

  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};

  Cashfree.XClientSecret = {Client Secret Key};

  Cashfree.XEnvironment = Cashfree.PRODUCTION;

  var cashfree = new Cashfree();

  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php PHP theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```

  ```curl cURL theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' 
  --header 'x-api-version: 2023-08-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": { 
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }

  }'
  ```
</CodeGroup>

**Response**

```
{
  "cf_order_id": "1539553",
  "created_at": "2021-07-19T16:13:35+05:30",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_name": null,
    "customer_email": "john@cashfree.com",
    "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 an order with Split from backend. You will get the 'payment\_session\_id' in the response of [create order](/api-reference/payments/latest/orders/create) (instead of order\_token and payment\_link).

Below is the request and the response when you create an order with split.

<CodeGroup>
  ```curl Create Order with Split Request theme={"dark"}
  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": "john@cashfree.com",
            "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"
  }
  '
  ```

  ```json Create Order with Split Response theme={"dark"}
  {
    "cf_order_id": "3615229",
    "created_at": "2023-02-03T16:00:25+05:30",
    "customer_details": {
      "customer_id": "7112AAA812234",
      "customer_name": null,
      "customer_email": "john@cashfree.com",
      "customer_phone": "9908734801",
      "customer_uid":null
    },
    "entity": "order",
    "order_amount": 400.15,
    "order_currency": "INR",
    "order_expiry_time": "2023-02-27T05:30:00+05:30",
    "order_id": "386752t78",
    "order_meta": {
      "return_url": null,
      "notify_url": null,
      "payment_methods": null
    },
    "order_note": "Test order",
    "order_splits": [
      {
        "vendor_id": "kyc10",
        "amount": 100,
        "percentage": null
      },
      {
        "vendor_id": "11testkyc",
        "amount": 200,
        "percentage": null
      }
    ],
    "order_status": "ACTIVE",
    "order_tags": null,
    "payment_session_id": "session_2C6iky7TTw6eOy4MCNQjJvw0ZR3qXK_xedGM-7uBGlF8oZiKeji8-oCMqdcIy5WL-GEoKB0o5ivP9SHoD47I8FW8L2PgdXqM7kqf-CVF3dCa",
    "terminal_data": null
  }
  ```
</CodeGroup>

### 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](/payments/online/element/sdks).

#### Step 1: Include our SDK in your client code

Including the Script Tag. Import the URL in the snippet below to your HTML file.

```Text HTML theme={"dark"}
<script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
```

OR

Install from npm

```Text Shell theme={"dark"}
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.

```javascript theme={"dark"}
const cashfree = Cashfree({
    mode:"sandbox" //or production
});
```

#### Step 3: Redirect to checkout

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

```javascript theme={"dark"}
cf.checkout();
```

### 4. Handle redirection and confirm status

1. Check [status](/api-reference/payments/latest/orders/get) 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](https://merchant.cashfree.com/auth/login).\
You can check the step-by-step process of [making a whitelisting request](/payments/online/go-live/whitelist#whitelist-your-website-or-app).

<Note>
  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.
</Note>