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 Flutter SDK version 2.4.0+52 or above. Get it on pub.dev.
- Set your Android application’s
minSdkVersionto API level 19 or higher. - Set your iOS minimum deployment target to 13.0 or higher.
Step 1
Create a subscription
Step 2
Open the payment page
Step 3
Confirm the payment
Step 1: Create a subscription Server-side
Create a subscription from your backend server before you process any payment.This API requires your secret key. Create subscriptions through your server only — do not call this API directly from your mobile application.
subscription_id and a subscription_session_id. Pass both values to your Flutter client to proceed with the payment.
API request for creating a subscription
API request for creating a subscription
The following example shows how to create a subscription using the Create Subscription API:A successful response returns the For the full list of request parameters and response fields, see the Create Subscription API.
subscription_id and subscription_session_id. Use these values to build the CFSubscriptionSession object in Step 2. The API returns the following response on success:Step 2: Open the payment page Client-side
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. You can get the SDK 2.4.0+52. The Flutter SDK supports Android SDK version 19 and above and iOS minimum deployment target of 13.0 and above. Open your project’spubspec.yaml and add the following under dependencies:
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.
Add this entry inside the
<application> tag, not inside the <activity> tag.iOS configuration
Add the following to your application’sinfo.plist file:
2. Select a payment method
The Subscription Element SDK supports the following payment methods:- Card
- UPI
- eNach (net banking)
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.
3. Complete the payment
To complete the payment, follow these steps:- Create a
CFSubscriptionSessionobject. - Create the payment object for the selected payment method.
- Set up the subscription callback.
- Initiate the payment using
doPayment().
Create a session
TheCFSubscriptionSession object holds the session context for the payment. It accepts the subscription_session_id and subscription_id obtained from Step 1, and the Cashfree environment (sandbox or production).
The following example shows how to create the session object:
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.- Card
- UPI
- eNach (net banking)
Use the following builders to create a card payment object:
Set up the subscription callback
Register callback handlers to receive the result of the payment journey. The SDK callsonSubscriptionVerify when the flow completes and onSubscriptionFailure when an error occurs.
Initiate the payment
CalldoPayment() to open the payment screen when the customer taps the pay button. Pass the payment object for your selected payment method.
Sample code
The following example shows a complete card payment flow, including session creation, callback registration, and payment initiation.Step 3: Confirm the payment Server-side
After the SDK delivers a callback viaonSubscriptionVerify, 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 to retrieve the current payment status.
API request for fetching subscription payments
API request for fetching subscription payments
The following request fetches all payments for a subscription: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:Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when
payment_status is SUCCESS.Error codes
If a required field or object is missing when you initiate payment, the SDK throws aCFException. The following table lists SDK-level validation errors and when they occur.
Show error codes
Show error codes
The SDK validation errors are grouped by category as follows:
Session errors
These errors occur when theCFSubscriptionSession 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. |