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.

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:

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

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.

dependencies:
  flutter:
    sdk: flutter
  zoho_payments_flutter_sdk: ^1.0.0

To fetch the package, run the following command:

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.

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:

Import and create instance

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

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.

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

// 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:

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:

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: ZohoPaymentsDomain.india
// Environment: ZohoPaymentsEnvironment.live or ZohoPaymentsEnvironment.sandbox

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

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.

7. Verify Payment Status

After receiving the payment_id, use the Payment Retrieve API with the paymentId to verify the transaction status. Based on the status returned (success, failure, or pending), update your system.