Overview

Build customised payment experiences with pre-built, secure payment components that integrate seamlessly into your web application.

Cashfree custom web checkout lets you embed payment UI elements in your application and keep customers on your site throughout checkout. Cashfree captures and transmits sensitive payment data, which helps you reduce your PCI DSS (Payment Card Industry Data Security Standard) compliance scope.

Key features

Custom web checkout provides the following capabilities:

• Complete design control: Design payment forms that match your brand identity with full control over styling, layout, and user experience.

• PCI DSS compliant: Payment data is securely captured and transmitted directly to Cashfree servers, reducing your PCI compliance scope.

• Flexible integration: Build custom payment flows with individual components or use the hosted checkout option based on your requirements.

• Multiple payment methods: Accept payments through cards (credit and debit), UPI (collect, intent, and QR), net banking, wallets, and Buy Now Pay Later options.

• Enhanced user experience: Keep customers on your website throughout the payment journey without redirecting to external pages.

• Framework support: Native libraries available for JavaScript, React, and Svelte for seamless integration.

Prerequisites

Ensure you complete the following tasks before starting the integration:

• Create a Cashfree Merchant Account.
• Log in to the Merchant Dashboard and generate an App ID and Secret Key. Learn how to generate API keys.
• Whitelist your website domain for integration. Learn more about domain whitelisting.

Integration steps

Follow these four steps to integrate custom web checkout:

Try it in DevStudio

Step 1: Create an order

Server-side

To integrate the custom web checkout, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can’t call this API from the client-side.

Create orders through your server as this API requires your secret key. Don’t call it directly from the client-side.

Here’s a sample request for creating an order using your desired backend language. Cashfree offers backend SDKs to simplify the integration process.

curl

curl --location 'https://sandbox.cashfree.com/pg/orders' \
--header 'X-Client-Secret: {{clientKey}}' \
--header 'X-Client-Id: {{clientId}}' \
--header 'x-api-version: 2025-01-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": "[e-mail]",
    "customer_phone": "[phone]"
  },
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
  }
}'

import { Cashfree, CFEnvironment } from "cashfree-pg";

const cashfree = new Cashfree(
	CFEnvironment.PRODUCTION,
	"{Client ID}",
	"{Client Secret Key}"
);

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

	cashfree
		.PGCreateOrder(request)
		.then((response) => {
			console.log("Order created successfully:", response.data);
		})
		.catch((error) => {
			console.error("Error setting up order request:", error.response.data);
		});
}

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)

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);
  }
}

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)
    }
}

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);
    }
}

\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;
}

After successfully creating an order, you will receive a unique order_id and payment_session_id that you need for subsequent steps.

You can view the complete API request and response for /orders in the Create Order API.

Step 2: Include SDK

Client-side

You must whitelist your domain with Cashfree before you start this step.

Include the Cashfree SDK in your client-side code. You must load cashfree.js directly from the Cashfree CDN to maintain PCI compliance. Don’t bundle or self-host this library.

JavaScript

Use the CDN or NPM to include the SDK in your project.

CDN

<script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>

npm install @cashfreepayments/cashfree-js

Initialise the SDK

Initialise the SDK using the Cashfree() function with the appropriate mode:

CDN

const cashfree = Cashfree({
    mode: "sandbox" // Use "production" for live environment
});

import { load } from "@cashfreepayments/cashfree-js";

const cashfree = await load({
    mode: "sandbox" // Use "production" for live environment
});

React

For React applications, refer to the SDK documentation for React-specific setup and usage patterns.

NPM

npm install @cashfreepayments/cashfree-js

Import and initialise the SDK in your React component:

import { useState, useEffect } from "react";
import { load } from "@cashfreepayments/cashfree-js";

function PaymentComponent() {
    const [cashfree, setCashfree] = useState(null);

    useEffect(() => {
        const initializeSDK = async () => {
            const cf = await load({
                mode: "sandbox" // Use "production" for live
            });
            setCashfree(cf);
        };
        initializeSDK();
    }, []);

    // Your component logic
}

Svelte

For Svelte applications, refer to the SDK documentation for Svelte-specific setup and usage patterns.

NPM

npm install @cashfreepayments/cashfree-js

Import and use the SDK in your Svelte component:

import { load } from "@cashfreepayments/cashfree-js";
import { onMount } from "svelte";

let cashfree;

onMount(async () => {
    cashfree = await load({
        mode: "sandbox" // Use "production" for live
    });
});

Async and deferred loading

Asynchronous loading of JavaScript is recommended as it improves your site’s user experience by preventing the script from blocking DOM rendering during load time.

You can load cashfree.js using the async or defer attribute on the script tag:

<!-- Using async attribute -->
<script src="https://sdk.cashfree.com/js/v3/cashfree.js" async></script>

<!-- Using defer attribute -->
<script src="https://sdk.cashfree.com/js/v3/cashfree.js" defer></script>

With asynchronous loading, you must make all SDK method calls only after the script execution completes. Ensure your code waits for the Cashfree SDK to load before initialising or calling any methods.

Step 3: Build payment interface

Client-side

Build your payment interface using one of the following approaches:

Option 1: Use hosted checkout

Redirect customers to a Cashfree-hosted payment page that supports all payment methods. This is the quickest integration option.

let checkoutOptions = {
    paymentSessionId: "payment_session_id_from_step_1",
    returnUrl: "https://yourwebsite.com/payment-success?order_id={order_id}",
    redirectTarget: "_self" // or "_blank", "_modal" for popup
};

cashfree.checkout(checkoutOptions).then(function (result) {
    if (result.error) {
        console.error(result.error.message);
    }
    if (result.redirect) {
        console.log("Redirection");
    }
});

The redirectTarget parameter controls how the checkout opens:

• _self: Opens in same window (default)
• _blank: Opens in new tab
• _modal: Opens in popup window
• DOM element: Embeds inline

Option 2: Build custom components

Create custom payment forms using individual components for complete design control. Components are available for cards, UPI, net banking, and wallets.

Card payments

Accept credit and debit card payments

UPI payments

Support UPI collect, intent, and QR

Other methods

Net banking, wallets, and BNPL

Component lifecycle:

For detailed component examples, refer to the Examples page.

Step 4: Confirm the payment

Server-side

After the customer completes the payment, verify the payment status on your server before delivering services.

Hosted checkout response

For hosted checkout, customers redirect to the returnUrl you provided when creating the order. For popup and inline checkouts, the cashfree.checkout() function returns a promise with payment details.

Custom component response

When using custom components, the cashfree.pay() method returns a promise with the payment result.

Order status verification

To verify an order you can call our /pg/orders endpoint from your backend. You can also use our SDK to achieve the same.

curl

curl --request GET \
     --url https://sandbox.cashfree.com/pg/orders/{order_id} \
     --header 'accept: application/json' \
     --header 'x-api-version: 2025-01-01' \
     --header 'x-client-id: "YOUR APP ID GOES HERE"' \
     --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'

cashfree
.PGFetchOrder("<order_id>")
.then((response) => {
	console.log("Order fetched successfully:", response.data);
})
.catch((error) => {
	console.error("Error:", error.response.data.message);
});

from cashfree_pg.models.create_order_request import CreateOrderRequest
from cashfree_pg.api_client import Cashfree
from cashfree_pg.models.customer_details import CustomerDetails
from cashfree_pg.models.order_meta import OrderMeta

Cashfree.XClientId = "<x-client-id>"
Cashfree.XClientSecret = "<x-client-secret>"
Cashfree.XEnvironment = Cashfree.SANDBOX
x_api_version = "2023-08-01"

try:
    api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
    print(api_response.data)
except Exception as e:
    print(e)

import com.cashfree.*;
//other code

try {
    Cashfree.XClientId = "<x-client-id>";
    Cashfree.XClientSecret = "<x-client-secret>";
    Cashfree.XEnvironment = Cashfree.SANDBOX;

    Cashfree cashfree = new Cashfree();
    String xApiVersion = "2023-08-01";

    ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
    System.out.println(response.getData().getOrderId());
} catch (ApiException e) {
    throw new RuntimeException(e);
}

version := "2023-08-01"
response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
if err != nil {
	fmt.Println(err.Error())
} else {
	fmt.Println(httpResponse.StatusCode)
	fmt.Println(response)
}

using cashfree_pg.Client;
using cashfree_pg.Model;

Cashfree.XClientId = "<x-client-id>";
Cashfree.XClientSecret = "<x-client-secret>";
Cashfree.XEnvironment = Cashfree.SANDBOX;
var cashfree = new Cashfree();
var xApiVersion = "2023-08-01";

try {
    var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
    Console.WriteLine(result);
    Console.WriteLine(result.StatusCode);
    Console.WriteLine((result.Content as OrderEntity));
} catch (ApiException e) {
    Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
    Console.WriteLine("Status Code: " + e.ErrorCode);
    Console.WriteLine(e.StackTrace);
}

$x_api_version = "2023-08-01";
try {
    $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
    print_r($response);
} catch (Exception $e) {
    echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
}

Always verify the order status before you deliver services to the customer. Use the Get Order API for this. An order is successful when the order_status is PAID.

Developer resources

SDK Libraries

JavaScript, React, and Svelte libraries for seamless integration

Integration Examples

Working code samples for cards, UPI, wallets, and multi-payment setups

Component Overview

Component lifecycle methods including mount, update, and unmount

Customise Styling

Apply custom styles, fonts, and themes to match your brand

Card Payments

Build custom card payment forms with secure components

UPI Components

Integrate UPI collect, QR code, and intent-based payments

Other Payment Methods

Add net banking, wallets, and Buy Now Pay Later options

Payment Options

Configure payment methods, filters, and checkout behaviour

Testing

After integration, verify that your payment flow works correctly:

1. Open the Network tab in your browser developer tools.
2. Initiate a payment and check the console logs.
3. Ensure you pass the correct environment (sandbox or production) and payment_session_id.
4. Use console.log() to confirm data is passed correctly to the SDK methods.
5. Test with sandbox credentials before going live.

FAQs

Which integration approach should I choose: hosted checkout or custom components?

Use hosted checkout if you want the quickest implementation with minimal code. It provides a ready-made payment page with all payment methods.

Use custom components when you need:

• Complete control over the payment form design
• Seamless integration with your existing UI
• Custom validation and error handling
• Specific payment flow customizations

Is my website PCI DSS compliant when using custom web checkout?

Yes. When you use Cashfree’s custom web checkout, payment card data is captured directly by secure components and transmitted to Cashfree servers. Your server never touches sensitive card information, which reduces your PCI DSS compliance scope significantly.

However, you must:

• Load the SDK from Cashfree’s CDN (don’t bundle or self-host)
• Never log or store card data on your servers
• Use HTTPS for all website pages

How do I handle payment failures and errors?

Always implement proper error handling:

1. Client-side: Check for result.error in the promise returned by cashfree.checkout() or cashfree.pay()
2. Server-side: Always verify the order status using the Get Order API before delivering services
3. Use webhooks: Implement webhook handlers for real-time payment status notifications
4. Display clear messages: Show user-friendly error messages to customers when payments fail

Can I use the same payment session for multiple payment attempts?

No. Payment sessions are single-use and expire after 30 minutes. For each new payment attempt, generate a fresh payment session through the Create Order API on your server.

What browsers are supported by the custom web checkout?

The Cashfree SDK supports all modern browsers:

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+
• Mobile browsers (iOS Safari 14+, Chrome Mobile 90+)

The SDK automatically handles browser compatibility and provides fallbacks where needed.

Do I need to whitelist my domain?

Yes. Domain whitelisting is mandatory for security. You must whitelist:

• Your website domain for web integrations
• Your app package name for mobile apps

Whitelist your domains in the Merchant Dashboard under Settings > Developers > Domain Whitelisting.

Can I customize the styling of payment components?

Yes. Custom components are fully styleable. You can customize:

• Colors and fonts
• Border styles and radius
• Padding and spacing
• Focus and error states
• Placeholder text

See the Customise Styling guide for detailed examples.

How do I test the integration before going live?

1. Use sandbox mode in the SDK initialization
2. Generate test API keys from the sandbox environment
3. Use test card numbers from the documentation
4. Test all payment scenarios: success, failure, pending
5. Verify webhook handling with test notifications
6. Switch to production mode and use live API keys only when ready to go live

What happens if the SDK fails to load?

If the SDK fails to load:

• Check browser console for errors
• Verify the CDN address is correct
• Ensure you’re loading from https://sdk.cashfree.com
• Check for network connectivity issues
• Verify no browser extensions are blocking the script

For async loading, ensure you wait for the SDK to load before making any method calls.

Can I save customer card details for future payments?

Yes. Use the savePaymentInstrument component in your card payment form. Customers can opt-in to save their card details securely. On subsequent payments, you can retrieve and use saved payment instruments through the Token Vault feature.

Learn more in the Token Vault documentation.

Affiliate partner program

As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.

Join the Cashfree affiliate partner program and get rewarded every time your clients use Cashfree.

What you get:

• Earn up to 0.25% commission on every transaction.
• Become a trusted fintech partner for your clients.
• Access to a dedicated partner manager for expert support.

What your clients get:

• Instant activation and go live in minutes.
• Industry-best success rate across all payment modes.
• Effortless acceptance of international payments in 140+ currencies.

Get started today. Become a partner now.

Related topics

• Create Order API
• Get Order API
• SDK Libraries
• Integration Examples