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

# Flutter Subscription Integration

> Integrate the Cashfree Subscription Element SDK into your Flutter application to accept subscription payments via card, UPI, and eNach on Android and iOS.

The Cashfree Subscription Element SDK lets you build a fully custom subscription 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 appearance and behaviour of your payment flow.

The SDK supports three payment methods for subscriptions: card, UPI, and eNach (electronic National Automated Clearing House, also known as net banking). It runs on both Android and iOS from a single integration.

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/api-reference/authentication#generate-api-keys).
* Use Flutter SDK version **2.4.0+52** or above. Get it on [pub.dev](https://pub.dev/packages/flutter_cashfree_pg_sdk).
* Set your Android application's `minSdkVersion` to API level 19 or higher.
* Set your iOS minimum deployment target to 13.0 or higher.

The integration consists of three steps:

<CardGroup cols={3}>
  <Card title="Step 1" icon="money-bill-wave" href="/payments/subscription/custom-checkout/mobile/flutter-subscription-element#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/payments/subscription/custom-checkout/mobile/flutter-subscription-element#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/payments/subscription/custom-checkout/mobile/flutter-subscription-element#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge color="green">Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only — do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your Flutter client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "enach",
              "upi",
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/api-reference/payments/latest/subscription/mandate/create).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge color="orange">Client-side</Badge>

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

### 1. Set up the SDK

The Flutter SDK is hosted on [pub.dev](https://pub.dev/). You can get the SDK [2.4.0+52](https://pub.dev/packages/flutter_cashfree_pg_sdk). The Flutter SDK supports Android SDK version 19 and above and iOS minimum deployment target of 13.0 and above.

Open your project's `pubspec.yaml` and add the following under dependencies:

```yaml theme={"dark"}
flutter_cashfree_pg_sdk: 2.4.0+52
```

#### Android configuration

Add the following entry inside the `<application>` tag in your Android manifest file. If you do not enable the `cashfree_subscription_flow_enable` flag, the SDK will not provide a payment callback.

<Note>Add this entry inside the `<application>` tag, not inside the `<activity>` tag.</Note>

```xml theme={"dark"}
<application
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name">

    <meta-data
        android:name="cashfree_subscription_flow_enable"
        android:value="true"
        tools:replace="android:value"/>
</application>
```

#### iOS configuration

Add the following to your application's `info.plist` file:

```xml theme={"dark"}
<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>
```

### 2. Select a payment method

The Subscription Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. The SDK securely processes the card payment and initiates the subscription mandate.
  </Tab>

  <Tab title="UPI">
    In this flow, the SDK launches the customer's selected UPI app to authorise the subscription mandate. You pass the package name of the installed UPI PSP (payment service provider) application to identify the app to launch.
  </Tab>

  <Tab title="eNach (net banking)">
    In this flow, the customer authorises the subscription mandate through one of three methods: Aadhaar OTP, debit card, or net banking. You specify the preferred authorisation mode when building the payment object.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSubscriptionSession` object.
2. Create the payment object for the selected payment method.
3. Set up the subscription callback.
4. Initiate the payment using `doPayment()`.

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (sandbox or production).

The following example shows how to create the session object:

```dart theme={"dark"}
Future<CFSubscriptionSession?> createSubscriptionSession() async {
  try {
    var session = CFSubscriptionSessionBuilder()
        .setEnvironment(environment)
        .setSubscriptionId(subscriptionId)
        .setSubscriptionSessionId(subscriptionSessionId)
        .build();
    return session;
  } on CFException catch (e) {
    print(e.message);
  }
  return null;
}
```

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

<Tabs>
  <Tab title="Card">
    Use the following builders to create a card payment object:

    ```dart theme={"dark"}
    var subsCard = CFSubsCardBuilder()
        .setCardNumber(cardNumber)
        .setCardHolderName(cardHolderName)
        .setCardExpiryMM(cardExpiryMM)
        .setCardExpiryYY(cardExpiryYY)
        .setCardCVV(cardCVV)
        .build();

    var subsCardPayment = CFSubsCardPaymentBuilder()
        .setSession(session)
        .setCard(subsCard)
        .build();
    ```
  </Tab>

  <Tab title="UPI">
    The `setUPIID` field accepts the package name of the UPI PSP application installed on the device (for example, `com.phonepe.app`). This launches the selected UPI app directly to complete the payment.

    ```dart theme={"dark"}
    var subsUPI = CFSubsUPIBuilder()
        .setChannel(CFSubsUPIChannel.INTENT)
        .setUPIID(upiAppPackageName) // package name of the selected UPI PSP app
        .build();

    var subsUPIPayment = CFSubsUPIPaymentBuilder()
        .setSession(session)
        .setUPI(subsUPI)
        .build();
    ```
  </Tab>

  <Tab title="eNach (net banking)">
    The `setAuthMode` field specifies how the customer authorises the mandate. The following values are accepted:

    | Value         | Description                                                                   |
    | ------------- | ----------------------------------------------------------------------------- |
    | `aadhaar`     | The customer authorises the mandate using their Aadhaar number and OTP.       |
    | `debit_card`  | The customer authorises the mandate using their debit card details.           |
    | `net_banking` | The customer authorises the mandate by logging into their net banking portal. |

    The following example shows how to build the net banking payment object:

    ```dart theme={"dark"}
    var subsNetbanking = CFSubsNetbankingBuilder()
        .setAuthMode(authMode) // aadhaar, debit_card, or net_banking
        .setAccountHolderName(accountHolderName)
        .setAccountNumber(accountNumber)
        .setAccountType(accountType) // SAVINGS or CURRENT
        .setAccountBankCode(bankCode)
        .build();

    var subsNetbankingPayment = CFSubsNetbankingPaymentBuilder()
        .setSession(session)
        .setNetbanking(subsNetbanking)
        .build();
    ```
  </Tab>
</Tabs>

#### Set up the subscription callback

Register callback handlers to receive the result of the payment journey. The SDK calls `onSubscriptionVerify` when the flow completes and `onSubscriptionFailure` when an error occurs.

<Tip>Register the callback before calling `doPayment()`. Setting it in `initState` ensures it is registered correctly even after widget restarts.</Tip>

```dart theme={"dark"}
void onSubscriptionVerify(String subscriptionId) {
  // Verify subscription status from your backend before proceeding.
  print("Verify Subscription: $subscriptionId");
}

void onSubscriptionFailure(CFErrorResponse errorResponse, String orderId) {
  // Handle payment failure. Inspect errorResponse for details.
  print(errorResponse.getMessage());
}

var cfPaymentGatewayService = CFPaymentGatewayService();

@override
void initState() {
  super.initState();
  cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
}
```

#### Initiate the payment

Call `doPayment()` to open the payment screen when the customer taps the pay button. Pass the payment object for your selected payment method.

```dart theme={"dark"}
cfPaymentGatewayService.doPayment(subsCardPayment);
// or: cfPaymentGatewayService.doPayment(subsUPIPayment);
// or: cfPaymentGatewayService.doPayment(subsNetbankingPayment);
```

#### Sample code

The following example shows a complete card payment flow, including session creation, callback registration, and payment initiation.

```dart theme={"dark"}
class _MyAppState extends State<MyApp> {

  var cfPaymentGatewayService = CFPaymentGatewayService();

  @override
  void initState() {
    super.initState();
    cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
  }

  void onSubscriptionVerify(String subscriptionId) {
    print("Verify Subscription: $subscriptionId");
  }

  void onSubscriptionFailure(CFErrorResponse errorResponse, String orderId) {
    print(errorResponse.getMessage());
    print("Error while making payment");
  }

  subsCardPay() async {
    try {
      cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
      var session = await createSubscriptionSession();
      if (session == null) {
        return;
      }
      var subsCard = CFSubsCardBuilder()
          .setCardNumber(cardNumber)
          .setCardHolderName(cardHolderName)
          .setCardExpiryMM(cardExpiryMM)
          .setCardExpiryYY(cardExpiryYY)
          .setCardCVV(cardCVV)
          .build();
      var subsCardPayment = CFSubsCardPaymentBuilder()
          .setSession(session)
          .setCard(subsCard)
          .build();
      cfPaymentGatewayService.doPayment(subsCardPayment);
    } on CFException catch (e) {
      print(e.message);
    }
  }

  Future<CFSubscriptionSession?> createSubscriptionSession() async {
    try {
      var session = CFSubscriptionSessionBuilder()
          .setEnvironment(environment)
          .setSubscriptionId(subscriptionId)
          .setSubscriptionSessionId(subscriptionSessionId)
          .build();
      return session;
    } on CFException catch (e) {
      print(e.message);
    }
    return null;
  }
}
```

## Step 3: Confirm the payment <Badge color="green">Server-side</Badge>

After the SDK delivers a callback via `onSubscriptionVerify`, 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.

Use the [Fetch Details of All Payments of a Subscription API](/api-reference/payments/latest/subscription/payment/fetch-payments-for-mandate) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK throws a `CFException`. The following table lists SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code                            | Message                                                    | Description                                                                      |
  | ------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request.     | The `CFSubscriptionSession` object was not passed to the payment builder.        |
  | `SUBSCRIPTION_SESSION_ID_MISSING`     | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSessionBuilder`. |
  | `SUBSCRIPTION_ID_MISSING`             | The "subscription\_id" is missing in the request.          | The `subscription_id` was not set on the `CFSubscriptionSessionBuilder`.         |
  | `ENVIRONMENT_MISSING`                 | The "environment" is missing in the request.               | The Cashfree environment was not set on the `CFSubscriptionSessionBuilder`.      |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code                                    | Message                                                  | Description                                                                           |
  | --------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING`            | The "CFSubsCard" object is missing in the request.       | The `CFSubsCard` object was not passed to the `CFSubsCardPaymentBuilder`.             |
  | `SUBSCRIPTION_NB_OBJECT_MISSING`              | The "CFSubsNetbanking" object is missing in the request. | The `CFSubsNetbanking` object was not passed to the `CFSubsNetbankingPaymentBuilder`. |
  | `SUBSCRIPTION_UPI_OBJECT_MISSING`             | The "CFSubsUPI" object is missing in the request.        | The `CFSubsUPI` object was not passed to the `CFSubsUPIPaymentBuilder`.               |
  | `SUBSCRIPTION_NB_ACCOUNT_HOLDER_NAME_MISSING` | The "account holder name" is missing in the request.     | The `setAccountHolderName` field was not set on the `CFSubsNetbankingBuilder`.        |
  | `SUBSCRIPTION_NB_ACCOUNT_NUMBER_MISSING`      | The "account number" is missing in the request.          | The `setAccountNumber` field was not set on the `CFSubsNetbankingBuilder`.            |
  | `SUBSCRIPTION_NB_BANK_CODE_MISSING`           | The "bank code" is missing in the request.               | The `setAccountBankCode` field was not set on the `CFSubsNetbankingBuilder`.          |
  | `SUBSCRIPTION_NB_ACCOUNT_TYPE_MISSING`        | The "account type" is missing in the request.            | The `setAccountType` field was not set on the `CFSubsNetbankingBuilder`.              |
  | `SUBSCRIPTION_NB_AUTH_MODE_MISSING`           | The "auth mode" is missing in the request.               | The `setAuthMode` field was not set on the `CFSubsNetbankingBuilder`.                 |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code         | Message                        | Description                                                                                                                                       |
  | ------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setCallback` was not called on `CFPaymentGatewayService` before `doPayment()`. Register the callback in `initState` before you initiate payment. |
</Accordion>

<div class="hidden" data-table-of-contents="bottom">
  <p class="mt-4 font-medium flex items-center gap-2 related-docs-heading">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="w-4 h-4">
      <path d="M3 4h7a2 2 0 0 1 2 2v13a2 2 0 0 0-2-2H3z" />

      <path d="M21 4h-7a2 2 0 0 0-2 2v13a2 2 0 0 1 2-2h7z" />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/create">Create a Subscription</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/payment/fetch-payments-for-mandate">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/charge">Charge a Subscription</a></li>
    <li><a href="https://pub.dev/packages/flutter_cashfree_pg_sdk" target="_blank">Flutter SDK on pub.dev</a></li>
  </ul>
</div>