INTEGRATION TOOLKIT

Try our Integration

We have released our latest version 2022-09-01 to make our integration more secure for merchants and customers to use. In the this latest version, we have revamped the integration method for using our pre-built checkout.

Old Flow -

Create Order
Use payment_link received from create order response to redirect the customer to checkout page.
Handle redirection and confirm payment status

New Payment Gateway Integration Flow

1. Change API version

Change x-api-version in header to 2022-09-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 new request and response of Create Order

curl  --request POST \
 --url https://sandbox.cashfree.com/pg/orders \
 --header 'Content-Type: application/json' \
 --header 'x-api-version: 2022-09-01' \
 --header 'x-client-id: <App ID>' \
 --header 'x-client-secret: <Secret Key>' \
 --data '{
  "order_id": "order_1626945143520",
  "order_amount": 10.12,
  "order_currency": "INR",
  "order_note": "Additional order info",
  "customer_details": {
   "customer_id": "12345",
    "customer_name": "name",
    "customer_email": "[email protected]",
    "customer_phone": "9816512345"
  }
}'

{
  "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"
  },
  "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_id}",
    "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php",
    "payment_methods": null
  },
  "order_note": null,
  "order_status": "PAID",
  "payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD",
  "payments": {
    "url": "https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr/payments"
  },
  "refunds": {
    "url": "https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr/refunds"
  },
  "settlements": {
    "url": "https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr/settlements"
  }
}

If you want to create split order -

Create Order with Split from backend

You'll get payment_session_id in the response of create order (instead of order_token and payment_link)

Below is the new request and the response of Create 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: 2022-09-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"
}
'

{
  "cf_order_id": 3615229,
  "created_at": "2023-02-03T16:00:25+05:30",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_name": null,
    "customer_email": "[email protected]",
    "customer_phone": "9908734801"
  },
  "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",
  "payments": {
    "url": "https://sandbox.cashfree.com/pg/orders/386752t78/payments"
  },
  "refunds": {
    "url": "https://sandbox.cashfree.com/pg/orders/386752t78/refunds"
  },
  "settlements": {
    "url": "https://sandbox.cashfree.com/pg/orders/386752t78/settlements"
  },
  "terminal_data": null
}

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

Step 1: Include our SDK in your client code

Sandbox

<script src="https://sdk.cashfree.com/js/ui/2.0.0/cashfree.sandbox.js"></script>

Production

<script src="https://sdk.cashfree.com/js/ui/2.0.0/cashfree.prod.js"></script>

Step 2: Initialize the SDK

const paymentSessionId = "your payment session id"; 
const cf = new Cashfree(paymentSessionId);

Step 3: Redirect to checkout

You would be using redirect function to redirect to pre-built checkout page.

cf.redirect();

4. Handle Redirection and Confirm Status

Check status of the order.
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 email us at [email protected].
You can check step-by-step process of making whitelisting request here.

❗️
IMPORTANT!
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.