React Native Element Integration

The Cashfree Payment Gateway Element SDK lets you build a fully custom payment experience within your React Native application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the look and feel of your payment flow. The SDK supports three Element payment methods: card (including saved card), net banking, and UPI Intent. It runs on both Android and iOS from a single integration.

This page describes the raw card flow, where your application collects the card number directly and is responsible for PCI DSS (Payment Card Industry Data Security Standard) compliance. To avoid handling raw card numbers, use the React Native Custom Card Component instead, which captures the card number inside an SDK-managed input field.

Prerequisites

Complete the following tasks before you start 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.
Use Cashfree React Native SDK version 2.4.0 or above. Get it from npm.
Set your Android application’s minSdkVersion to API level 19 or higher.
Set your iOS minimum deployment target to 10.3 or higher.

The integration consists of three steps:

Step 1

Create an order

Step 2

Open the payment page

Step 3

Confirm the payment

Step 1: Create an order Server-side

Create an order from your backend server before you process any payment.

This API requires your secret key. Create orders through your server only. Do not call this API directly from your mobile application.

API request for creating an order

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

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": "joe.s@cashfree.com",
    "customer_phone": "+919876543210"
  },
  "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: "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(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: Open the payment page Client-side

After you create the order, open the payment page so the customer can provide payment details.

1. Set up the SDK

The React Native SDK is hosted on npm. You can get the SDK 2.4.0. The React Native SDK supports Android SDK version 19 and above and iOS minimum deployment target of 10.3 and above. Install the SDK in your React Native project:

npm install react-native-cashfree-pg-sdk@2.4.0

yarn add react-native-cashfree-pg-sdk@2.4.0

npx expo install react-native-cashfree-pg-sdk
npx expo install expo-dev-client
npx expo prebuild
npx expo run:android
npx expo run:ios

iOS configuration

To provide UPI payments on iOS, add the following to your application’s info.plist file:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>amazonpay</string>
  <string>upi</string>
  <string>credpay</string>
  <string>bhim</string>
  <string>paytmmp</string>
  <string>phonepe</string>
  <string>tez</string>
  <string>navipay</string>
  <string>mobikwik</string>
  <string>myairtel</string>
  <string>popclubapp</string>
  <string>super</string>
  <string>kiwi</string>
  <string>simplypayupi</string>
  <string>whatsapp</string>
</array>

For iOS, run the following commands:

cd ios
pod install --repo-update

2. Select a payment method

The Element SDK supports the following payment methods:

Card
Net banking
UPI Intent

In this flow, the customer enters their card details directly in your application UI. Your application receives the raw card number and passes it to the SDK, so your application remains in PCI DSS scope for card data. To avoid handling raw card numbers, use the React Native Custom Card Component instead. You can also charge a previously saved card by passing the saved card instrument ID and CVV.

3. Complete the payment

To complete the payment, follow these steps:

Set up the payment callback.
Create a CFSession object.
Create the payment object for the selected payment method.
Initiate the payment using makePayment().

Set up the payment callback

The SDK exposes a CFCallback interface to receive callbacks from the SDK once the payment flow ends. The callback supports two methods:

onVerify(orderID: string): void
onError(error: CFErrorResponse, orderID: string): void

Set the callback in componentDidMount and remove it in componentWillUnmount. This configuration also handles activity restart cases and prevents memory leaks.

Always call setCallback before calling makePayment.

import { Component } from 'react';
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';

export default class App extends Component {
  componentDidMount() {
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        // Verify the order status from your backend.
      },
      onError(error: CFErrorResponse, orderID: string): void {
        console.log(JSON.stringify(error), orderID);
      },
    });
  }

  componentWillUnmount() {
    CFPaymentGatewayService.removeCallback();
  }
}

Create a session

The CFSession object holds the session context for the payment. It accepts the payment_session_id and order_id obtained from Step 1, and the Cashfree environment (CFEnvironment.SANDBOX or CFEnvironment.PRODUCTION).

import {
  CFEnvironment,
  CFSession,
} from 'cashfree-pg-api-contract';

try {
  const session = new CFSession(
    '<PAYMENT_SESSION_ID>',
    '<ORDER_ID>',
    CFEnvironment.SANDBOX // or CFEnvironment.PRODUCTION
  );
} catch (e: any) {
  console.log(e.message);
}

Create a payment object

The SDK provides a dedicated payment class for each supported payment method. Build only the object that corresponds to the payment method your customer has selected. Card objects can be of two types: Card for a new card payment, and SavedCard for a previously saved instrument.

Object	Fields
`Card`	`cardNumber`, `cardHolderName`, `cardExpiryMM`, `cardExpiryYY`, `cardCvv`, `saveCard`
`SavedCard`	`instrumentId`, `cardCvv`

Card
Saved card
Net banking
UPI Intent

Use the following code to create a card payment object. This is the raw card flow. Your application passes the full card number to the SDK.

import {
  Card,
  CFCardPayment,
  CFEnvironment,
  CFSession,
} from 'cashfree-pg-api-contract';
import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

async _startCardPayment() {
  try {
    const session = new CFSession(
      '<PAYMENT_SESSION_ID>',
      '<ORDER_ID>',
      CFEnvironment.SANDBOX
    );

    const card = new Card(
      '<CARD_NUMBER>',
      '<CARD_HOLDER_NAME>',
      '<CARD_EXPIRY_MM>',
      '<CARD_EXPIRY_YY>',
      '<CARD_CVV>',
      false // set true to save the card for future payments
    );

    const cardPayment = new CFCardPayment(session, card);
    CFPaymentGatewayService.makePayment(cardPayment);
  } catch (e: any) {
    console.log(e.message);
  }
}

Use SavedCard when the customer pays with a previously saved card instrument. Pass the saved card instrumentId and the card CVV.

import {
  CFCardPayment,
  CFEnvironment,
  CFSession,
  SavedCard,
} from 'cashfree-pg-api-contract';
import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

async _startSavedCardPayment() {
  try {
    const session = new CFSession(
      '<PAYMENT_SESSION_ID>',
      '<ORDER_ID>',
      CFEnvironment.SANDBOX
    );

    const card = new SavedCard(
      '<INSTRUMENT_ID>',
      '<CARD_CVV>'
    );

    const cardPayment = new CFCardPayment(session, card);
    CFPaymentGatewayService.makePayment(cardPayment);
  } catch (e: any) {
    console.log(e.message);
  }
}

The CFNB constructor accepts the bank code of the customer’s bank.

import {
  CFEnvironment,
  CFNB,
  CFNBPayment,
  CFSession,
} from 'cashfree-pg-api-contract';
import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

async _makeNBPayment() {
  try {
    const session = new CFSession(
      '<PAYMENT_SESSION_ID>',
      '<ORDER_ID>',
      CFEnvironment.SANDBOX
    );

    const nb = new CFNB('<BANK_CODE>');
    CFPaymentGatewayService.makePayment(
      new CFNBPayment(session, nb)
    );
  } catch (e: any) {
    console.log(e.message);
  }
}

Use getInstalledUpiApps() to discover the UPI apps installed on the customer’s device, then build a CFUPI object using the selected app identifier. On Android, pass the app package name. On iOS, pass the UPI app URI scheme (for example, tez://).

import {
  CFEnvironment,
  CFSession,
  CFUPI,
  CFUPIPayment,
  UPIMode,
} from 'cashfree-pg-api-contract';
import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

async _makeUpiIntentPayment() {
  try {
    const apps = await CFPaymentGatewayService.getInstalledUpiApps();
    let appId = '';
    JSON.parse(apps as string).forEach((item: any) => {
      appId = item.appPackage;
    });

    const session = new CFSession(
      '<PAYMENT_SESSION_ID>',
      '<ORDER_ID>',
      CFEnvironment.SANDBOX
    );

    const upi = new CFUPI(UPIMode.INTENT, appId);
    CFPaymentGatewayService.makePayment(
      new CFUPIPayment(session, upi)
    );
  } catch (e: any) {
    console.log(e.message);
  }
}

Initiate the payment

Call makePayment() to open the Cashfree payment flow for the selected method. Pass the payment object you created in the previous step (CFCardPayment, CFNBPayment, or CFUPIPayment).

CFPaymentGatewayService.makePayment(cardPayment);
// or: CFPaymentGatewayService.makePayment(nbPayment);
// or: CFPaymentGatewayService.makePayment(upiPayment);

doCardPayment() is deprecated. Use makePayment() for card, net banking, and UPI Element payments.

Sample code

The following example shows a complete integration, including session creation, payment object setup for each method, and payment initiation.

Element checkout sample

import { Component } from 'react';
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';
import {
  Card,
  CFCardPayment,
  CFEnvironment,
  CFNB,
  CFNBPayment,
  CFSession,
  CFUPI,
  CFUPIPayment,
  SavedCard,
  UPIMode,
} from 'cashfree-pg-api-contract';

export default class App extends Component {
  componentDidMount() {
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        // Verify the order status from your backend.
        console.log('orderId is :' + orderID);
      },
      onError(error: CFErrorResponse, orderID: string): void {
        console.log(
          'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
        );
      },
    });
  }

  componentWillUnmount() {
    CFPaymentGatewayService.removeCallback();
  }

  getSession(): CFSession {
    return new CFSession(
      '<PAYMENT_SESSION_ID>',
      '<ORDER_ID>',
      CFEnvironment.SANDBOX
    );
  }

  async _startCardPayment() {
    try {
      const card = new Card(
        '<CARD_NUMBER>',
        '<CARD_HOLDER_NAME>',
        '<CARD_EXPIRY_MM>',
        '<CARD_EXPIRY_YY>',
        '<CARD_CVV>',
        false
      );
      CFPaymentGatewayService.makePayment(
        new CFCardPayment(this.getSession(), card)
      );
    } catch (e: any) {
      console.log(e.message);
    }
  }

  async _startSavedCardPayment() {
    try {
      const card = new SavedCard('<INSTRUMENT_ID>', '<CARD_CVV>');
      CFPaymentGatewayService.makePayment(
        new CFCardPayment(this.getSession(), card)
      );
    } catch (e: any) {
      console.log(e.message);
    }
  }

  async _makeNBPayment() {
    try {
      const nb = new CFNB('<BANK_CODE>');
      CFPaymentGatewayService.makePayment(
        new CFNBPayment(this.getSession(), nb)
      );
    } catch (e: any) {
      console.log(e.message);
    }
  }

  async _makeUpiIntentPayment() {
    try {
      const apps = await CFPaymentGatewayService.getInstalledUpiApps();
      let appId = '';
      JSON.parse(apps as string).forEach((item: any) => {
        appId = item.appPackage;
      });

      const upi = new CFUPI(UPIMode.INTENT, appId);
      CFPaymentGatewayService.makePayment(
        new CFUPIPayment(this.getSession(), upi)
      );
    } catch (e: any) {
      console.log(e.message);
    }
  }
}

Sample GitHub code

You can explore a working integration example on GitHub: GitHub sample Sample UPI Test APK

Step 3: Confirm the payment Server-side

After the SDK delivers a callback via onVerify, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment. 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 --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 from your backend before you deliver goods or services to the customer. You can use the Get Order API for this. An order is successful when the order_status is PAID.

Testing

After you integrate a payment method, verify that it behaves as expected. Follow these steps to test:

Trigger a payment using each method you have integrated.
Confirm that the SDK opens the correct payment screen for the method (Cashfree’s hosted card or net banking screen, or the selected UPI app).
Confirm that onVerify or onError is called when the payment flow ends.

Use the sandbox environment to test payments before you go live.

Error codes

To confirm the error returned in your React Native application, you can view the error codes exposed by the SDK.

Show error codes

The following are some of the error codes that are exposed by the SDK:

Error code	Message
`MISSING_CALLBACK`	The callback is missing in the request.
`ORDER_ID_MISSING`	The “order_id” is missing in the request.
`SESSION_OBJECT_MISSING`	The “session” is missing in the request.
`PAYMENT_OBJECT_MISSING`	The “payment” is missing in the request.
`ENVIRONMENT_MISSING`	The “environment” is missing in the request.
`ORDER_TOKEN_MISSING`	The “order_token” is missing in the request.

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.

Payments

Payment Gateway

Checkout

International Payments

Flowwise

RiskShield

Subscription

Other Products

Developer updates

React Native Element Integration

Prerequisites

Step 1

Step 2

Step 3

Step 1: Create an order Server-side

API request for creating an order

Step 2: Open the payment page Client-side

1. Set up the SDK

iOS configuration

2. Select a payment method

3. Complete the payment

Set up the payment callback

Create a session

Create a payment object

Initiate the payment

Sample code

Sample GitHub code

Step 3: Confirm the payment Server-side

Testing

Error codes

​Prerequisites

Step 1

Step 2

Step 3

​Step 1: Create an order Server-side

API request for creating an order

​Step 2: Open the payment page Client-side

​1. Set up the SDK

​iOS configuration

​2. Select a payment method

​3. Complete the payment

​Set up the payment callback

​Create a session

​Create a payment object

​Initiate the payment

​Sample code

​Sample GitHub code

​Step 3: Confirm the payment Server-side

​Testing

​Error codes

Prerequisites

Step 1: Create an order Server-side

Step 2: Open the payment page Client-side

1. Set up the SDK

iOS configuration

2. Select a payment method

3. Complete the payment

Set up the payment callback

Create a session

Create a payment object

Initiate the payment

Sample code

Sample GitHub code

Step 3: Confirm the payment Server-side

Testing

Error codes