Skip to main content
The Cashfree Payment Gateway Element SDK lets you build a fully custom payment experience within your Flutter 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 payment methods: card, net banking, and UPI Intent. It runs on both Android and iOS from a single Dart codebase.
For card payments, the SDK provides a CFCardWidget that renders the card number field for you. Your application never receives the raw card number. You collect only the card holder name, expiry, and CVV in your own UI and pass them to the SDK alongside the widget.

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 Flutter SDK version 2.4.0+52 or above. Get it from pub.dev.
  • Use Flutter 2.5.0 or above and Dart 3.0.0 or above.
  • Set your Android application’s minSdkVersion to API level 19 or higher.
  • Set your iOS minimum deployment target to 12.0 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.
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 Flutter SDK is hosted on pub.dev. Add it to your project:
Alternatively, add it directly to your pubspec.yaml file:
Then install the package:

iOS configuration

To support UPI payments on iOS, add the following UPI app URI schemes to your application’s ios/Runner/Info.plist file:
Then install the pods:

2. Select a payment method

The Element SDK supports the following payment methods:
In this flow, the SDK renders the card number field using CFCardWidget, so your application never handles the raw card number. Your application collects the card holder name, expiry, and CVV in its own UI and passes them to the SDK along with a reference to the widget.

3. Complete the payment

To complete the payment, follow these steps:
  1. Set up the payment callback.
  2. Create a CFSession object.
  3. Create the payment object for the selected payment method.
  4. Initiate the payment using doPayment().

Set up the payment callback

Register a success callback and an error callback using setCallback(). The SDK invokes the success callback with the order ID when the payment flow ends, and the error callback with a CFErrorResponse and order ID if the flow fails.
Call setCallback() in initState(), before you call doPayment().

Create a session

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

Create a payment object

The SDK provides a dedicated payment builder for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.
Render a CFCardWidget in your widget tree to collect the card number, then build the CFCard object using setCardWidget along with the remaining card details.
To charge a previously saved card, call setInstrumentId on CFCardBuilder with the saved instrument ID instead of setCardWidget, and pass only the CVV.

Initiate the payment

Call doPayment() to open the Cashfree payment flow for the selected method. The example below uses cardPayment. Replace it with netbankingPayment or upiPayment for your selected payment method.

Sample code

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

Sample GitHub code

You can explore a working integration example on GitHub:

Step 3: Confirm the payment Server-side

After the SDK delivers a callback via verifyPayment, 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.
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:
  1. Trigger a payment using each method you have integrated.
  2. Confirm that the SDK opens the correct payment screen for the method (Cashfree’s hosted net banking screen, the card widget’s own flow, or the selected UPI app).
  3. Confirm that verifyPayment or onError is called when the payment flow ends.
Use the sandbox environment to test payments before you go live.

Error codes

Before it reaches the native SDK, the Flutter layer validates each builder call and throws a CFException if a required field is missing. Catch CFException around every builder and doPayment() call to handle these cases.
If the payment itself fails after reaching the native SDK, your onError callback receives a CFErrorResponse with getStatus(), getMessage(), getCode(), and getType() accessors describing the failure.

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.