## Zoho Payments Documentation Index

Access the complete documentation index at:
https://www.zoho.com/in/payments/llms.txt

Use this file to discover all available documentation pages before proceeding.

# Flutter Integration

Zoho Payments provides a Flutter SDK to securely collect payments in your cross-platform app for iOS and Android. Flutter integration allows your app to communicate with Zoho Payments, handle transactions, and manage checkout flows across platforms.

**Prerequisites:**

*   **Android:** minSdkVersion 26 or higher
*   **iOS:** 15.6 or higher

### Platform Requirements for Android

Before using the SDK, ensure your project is properly configured so it functions correctly on Android and supports all required dependencies:

1.  Set `minSdkVersion` to 26 or higher in `android/app/build.gradle`.
2.  Add the Zoho Maven repository in `android/build.gradle`:

Install SDK - Project Level

Copy

```javascript
allprojects {
    repositories {
        maven { url 'https://maven.zohodl.com' }
    }
}
```

*   [Add Flutter SDK](#Add-the-dependency)
*   [Create Payment Session](#Create-Payment-Session)
*   [Integrate SDK](#Integrate-the-SDK)
*   [Invoke Checkout Widget](#Launch-checkout)
*   [Handle Payment Result](#Handle-Result)
*   [Confirm Payment](#Confirm-payment)
*   [Verify Payment Status](#Verify-status)

## 1\. Add Flutter SDK

To begin the integration, add the Zoho Payments Flutter SDK to your Flutter application. Then, include the package in your app’s `pubspec.yaml` file.

pubspec.yaml

Copy

```yaml
dependencies:
  flutter:
    sdk: flutter
  zoho_payments_flutter_sdk: ^1.0.0
```

To fetch the package, run the following command:

Install Package

Copy

```bash
flutter pub get
```

## 2\. Create Payment Session

To initiate the payment process, you need to create a payment session. Based on your payment type, you can create the session for one-time or recurring payments.

One-Time PaymentsRecurring Payments

### Payment Session for One-time Payments

To invoke the checkout widget, you need to obtain the `paymentSessionId`. To do this:

*   Collect payment information from your app (amount, currency, etc.).
*   Call the [Payment Session Create API.](https://www.zoho.com/in/payments/api/v1/payment-session/#create-payment-session "payment session")

The API will return a `paymentSessionId`. Use this ID to invoke the checkout widget and initiate the payment process.

### Create Customer

Collect customer details (name, email, phone, and metadata) and call the [Create Customer API.](https://www.zoho.com/in/payments/api/v1/mandates/#create-customer "Create Customer") The API will return a `customer_id`, which you can use to initiate a payment session for mandate enrollment.

### Create Payment Session for Mandate Enrollment

Call the [Create Payment Session for Mandate Enrollment API](https://www.zoho.com/in/payments/api/v1/mandates/#create-payment-session-mandate-enrollment "Mandate Enrollment") on your server using an OAuth token to obtain a `payment_session_id.`

**Note:** Each session allows up to three payment attempts, but only one can succeed. Any additional attempts return an `invalid_payment_session` response.

Use the `payment_session_id` when invoking the checkout widget.

## 3\. Integrate SDK

To integrate the SDK and enable payment processing in your Flutter application, you need to configure and initialize it within your project. The SDK provides methods to initialize, launch checkout, and handle payment results. Here are the main SDK methods you’ll use:

**Method**

**Description**

`initialize(apiKey, accountId)`

Initialize SDK with merchant credentials. This is required before checkout.

`showCheckout(options, domain, environment)`

Opens the payment checkout UI with the provided options. Returns a result of either `ZohoPaymentsSuccess` or `ZohoPaymentsFailure`.

### Import and create instance

First, you need to import the package and create an SDK instance.

Import SDK

Copy

```dart
import 'package:zoho_payments_flutter_sdk/zoho_payments_flutter_sdk.dart';

final _sdk = ZpaymentsFlutterSdk();
```

### Initialize SDK

Initialize the SDK with your **API Key** and **Account ID** before invoking the checkout widget. This is required before starting any checkout process.

Initialize SDK

Copy

```dart
await _sdk.initialize(
  apiKey: 'YOUR_API_KEY',
  accountId: 'YOUR_ACCOUNT_ID',
);
```

ENUMS

Copy

```dart
// Domains for payment processing
ZohoPaymentsDomain: india

// Environments for testing or production
ZohoPaymentsEnvironment: live, sandbox

// Supported payment methods
ZohoPaymentsPaymentMethod: card, netBanking, upi
```

### Configure checkout options

Set up the checkout options by providing your payment session details along with the customer’s information as shown below:

Checkout Options

Copy

```dart
final options = ZohoPaymentsCheckoutOptions(
  paymentSessionId: 'YOUR_PAYMENT_SESSION_ID',  // Required - create via your backend
  description: 'Order #12345',
  invoiceNumber: 'INV-001',
  referenceNumber: 'REF-001',
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+919876543210',
  paymentMethod: ZohoPaymentsPaymentMethod.card,  // Optional: card, netBanking, upi
);
```

The payment parameters for `ZohoPaymentsCheckoutOptions` are listed below:

**Parameter**

**Description**

`paymentSessionId`

A unique identifier created for each payment session (required). Learn [how to create a payment session.](https://www.zoho.com/in/payments/api/v1/payment-session/#create-payment-session "payment session")

`name`

Name of the customer.

`email`

Email address of the customer.

`phone`

Phone number associated with the customer.

`description`

Description of the payment session. The maximum length can be 500 characters.

`invoiceNumber`

Invoice number of the payment session. The maximum length can be 50 characters.

`referenceNumber`

Reference number for the payment.

`paymentMethod`

Type of payment method (optional): `card`, `netBanking`, or `upi`.

## 4\. Invoke Checkout Widget

Invoke the checkout widget to initiate the payment process. Use the sandbox environment for testing, and switch to production when you’re ready to go live.

Domain and Environment

Copy

```dart
// Domain: ZohoPaymentsDomain.india
// Environment: ZohoPaymentsEnvironment.live or ZohoPaymentsEnvironment.sandbox
```

Invoke Checkout Widget

Copy

```dart
final result = await _sdk.showCheckout(
  options,
  domain: ZohoPaymentsDomain.india
  environment: ZohoPaymentsEnvironment.live,  // or ZohoPaymentsEnvironment.sandbox
);

switch (result) {
  case ZohoPaymentsSuccess():
    final success = result as ZohoPaymentsSuccess;
    // Payment succeeded - use paymentId, signature, mandateId
    print('Payment ID: ${success.paymentId}');
    print('Signature: ${success.signature}');
    break;
  case ZohoPaymentsFailure():
    final failure = result as ZohoPaymentsFailure;
    // Payment failed or cancelled - use code, message
    print('Error Code: ${failure.code}');
    print('Error Message: ${failure.message}');
    break;
}
```

If you’re facing any errors while processing payments via mobile app, refer to the [error messages](https://www.zoho.com/in/payments/developerdocs/mobile-errors/ "error messages") to identify and resolve the issue.

## 5\. Handle Payment Result

After calling `showCheckout`, the SDK returns a result indicating the outcome of the payment, which can be either `ZohoPaymentsSuccess` or `ZohoPaymentsFailure`.

**Payment Result**

**Details**

**Description**

`ZohoPaymentsSuccess`

`paymentId`, `signature`, `mandateId?`

Indicates the payment was successful. Use `mandateId` for recurring or subscription payments, if applicable.

`ZohoPaymentsFailure`

`code`, `message`

Indicates the payment failed or was cancelled by the user. Use `code` and `message` to identify the error and provide appropriate feedback.

## 6\. Confirm the Payment

Once the customer completes the payment, the SDK will return a `paymentId` and `signature`. You can confirm the payment on your server and update your system.

**Note:** In some cases, you may not receive the `paymentId` if the customer accidentally closes the widget before a response is returned. In such cases, use your configured webhooks or the `paymentSessionId` to retrieve the payment status.

## 7\. Verify Payment Status

You can verify your payment status in three ways:

*   **Verify via Widget Response:** After receiving the `paymentId`, verify the payment status using the [Payment Retrieve API](/in/payments/api/v1/payments/#retrieve-payment "Retrieve API"). For recurring payments, use the [Retrieve Mandate API](https://www.zoho.com/in/payments/api/v1/mandates/#retrieve-mandate "Retrieve Mandate") to check specific mandates. Based on the status returned (success, failure, or pending), update your system.
    
*   **Verify via Webhooks:** Use your [configured webhooks](/in/payments/developerdocs/webhooks/configure/ "configure-webhooks") for the events **payment.success** and **payment.failed** to receive the final payment status directly.
    
*   **Verify via Session ID:** If you haven’t received the payment status via the widget response or webhooks, use the [Payment Session Retrieve API](https://www.zoho.com/in/payments/api/v1/payment-session/#retrieve-payment-session "Session") to verify the payment result.
    

**Note:** Ensure that all three options are configured for reliable payment verification.