payment_gateway_plugin 5.0.9

Omniware's Payment Gateway Plugin for Flutter

Paymentgateway Plugin Flutter

Flutter plugin for Paymentgateway SDK.

Table of Contents

• Getting Started
• Prerequisites
• Installation
• Platform-Specific Setup
  • Android Setup
  • iOS Setup
• Usage
  • Basic Implementation
  • Payment Parameters
  • Handling Responses
• Error Handling
• Example App

Getting Started

This Flutter plugin is a wrapper around our native Android and iOS SDKs for Paymentgateway integration. It provides a simple interface to initiate payment transactions from your Flutter application.

Prerequisites

Development Tools:

• Xcode 15 and above
• Flutter 3.3.0+ & Dart 2.19.0+ (compatible with Dart 3 and 4)
• Android Studio 4.0+ (for Android development)

Device Requirements:

• Android: API level 21 (Android 5.0) or higher
• iOS: iOS 13.0 or higher (Note: This plugin does not support iOS Simulator, only real iPhone devices)

Installation

This plugin is available on Pub: https://pub.dev/packages/payment_gateway_plugin

Add this to dependencies in your app's pubspec.yaml:

payment_gateway_plugin: ^5.0.9

Run flutter packages get in the root directory of your app.

Platform-Specific Setup

Android Setup

1. Minimum SDK Version: Ensure your app's minSdkVersion is set to 21 or higher in your app-level build.gradle file.

2. Java and Kotlin Configuration: Add the following to your app-level build.gradle file to ensure Java 11 compatibility:

android {
    // ... existing code ...
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
}

kotlin {
    jvmToolchain(11)
}

Alternatively, you can use the older approach with kotlinOptions:

android {
    // ... existing code ...
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    
    kotlinOptions {
        jvmTarget = "11"
    }
}

3. Add Required Dependencies: Add the following to your app-level build.gradle file:

dependencies {
    // Other dependencies
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.multidex:multidex:2.0.1'
}

4. Update settings.gradle: Make sure your project's settings.gradle includes the plugin:

include ':app'
include ':payment_gateway_plugin'

5. Configure Resources: Ensure you have the following files in your Android project:

<project_root>/android/app/src/main/res/values/colors.xml:

<resources>
    <color name="colorPrimary">#FF6200EE</color>
    <color name="colorPrimaryDark">#FF3700B3</color>
    <color name="colorAccent">#FF03DAC5</color>
</resources>

<project_root>/android/app/src/main/res/values/styles.xml:

<resources>
    <style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
        <!-- Customize your theme here -->
        <item name="colorPrimary">@color/colorPrimary</item>
        <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
        <item name="colorAccent">@color/colorAccent</item>
    </style>
</resources>

iOS Setup

1. Minimum iOS Version: Set the minimum deployment target for your app to iOS 13.0 or higher in Xcode.

2. UPI Payment Support: Add the following to your info.plist file to support UPI payment applications:

<dict>
    <!-- Other entries -->
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>upi</string>
        <string>credpay</string>
        <string>gpay</string>
        <string>phonepe</string>
        <string>paytmmp</string>
        <string>mobikwik</string>
        <string>com.amazon.mobile.shopping</string>
        <string>bharatpe</string>
        <string>freecharge</string>
        <string>payzapp</string>
        <string>myjio</string>
        <string>bhim</string>
        <string>slice</string>
    </array>
</dict>

3. Important Note: This plugin does not support iOS Simulator. You must test on a real iPhone device.

Usage

Basic Implementation

1. Import the package:

import 'package:payment_gateway_plugin/payment_gateway_plugin.dart';

2. Initialize payment:

// Create payment parameters
Map<String, dynamic> params = {
  'api_key': '<API_KEY>',
  'hash': '<HASH_KEY>',
  'order_id': 'ORDER123',
  'mode': 'LIVE', // or 'TEST' for testing
  'description': 'Product purchase',
  'currency': 'INR',
  'amount': '100', // Amount in string format
  'name': 'Customer Name',
  'email': '[e-mail]',
  'phone': '9876543210',
  'city': 'Mumbai',
  'state': 'Maharashtra',
  'country': 'IND',
  'zip_code': '400001',
  'address_line_1': 'Address Line 1',
  'address_line_2': 'Address Line 2',
  'return_url': 'https://yourapp.com/payment-response'
};

// Initiate payment
try {
  Map<String, dynamic>? response = await PaymentGatewayPlugin.open(
    '<PAYMENT_URL>', 
    params
  );
  
  // Handle response
  if (response != null) {
    String status = response['status'] ?? 'Unknown';
    String responseMessage = response['response']?.toString() ?? 'No response';
    
    // Process payment result
    if (status == 'success') {
      // Payment successful
    } else if (status == 'cancelled') {
      // Payment cancelled by user
    } else {
      // Payment failed
    }
  }
} catch (e) {
  // Handle exceptions
  print('Payment error: $e');
}

Payment Parameters

The following parameters are supported by the plugin:

Parameter	Description	Required
api_key	Your API key provided by Payment Gateway	Yes
hash	Hash key for security	Yes
order_id	Unique order identifier	Yes
amount	Transaction amount (as string)	Yes
mode	'LIVE' or 'TEST'	Yes
description	Transaction description	Yes
currency	Currency code (e.g., 'INR')	Yes
name	Customer name	Yes
email	Customer email	Yes
phone	Customer phone number	Yes
city	Customer city	Yes
state	Customer state	Yes
country	Customer country code	Yes
zip_code	Customer postal code	Yes
address_line_1	Customer address line 1	Yes
address_line_2	Customer address line 2	Yes
return_url	URL to return after payment	Yes
udf1 to udf5	User-defined fields	No

For a complete list of parameters, refer to the official documentation.

Handling Responses

The plugin returns a Map<String, dynamic> with the following structure:

{
  'status': 'success' | 'error' | 'cancelled',
  'response': 'Raw response from payment gateway (if available)'
}

Example implementation for handling responses:

void processPayment(Map<String, dynamic> params) async {
  try {
    Map<String, dynamic>? response = await PaymentGatewayPlugin.open('<PAYMENT_URL>', params);

    if (response != null) {
      String status = response['status'] ?? 'Unknown';
      String responseMessage = response['response']?.toString() ?? '';

      switch (status) {
        case 'success':
          // Verify transaction details from responseMessage
          // Important: Always verify order_id and amount from the response
          // to ensure they match your original request
          showSuccessMessage('Payment successful!');
          break;
        
        case 'cancelled':
          showInfoMessage('Payment was cancelled');
          break;
        
        case 'error':
          showErrorMessage('Payment failed');
          break;
        
        default:
          showErrorMessage('Unknown payment status');
      }
    } else {
      showErrorMessage('No response received from payment gateway');
    }
  } catch (e) {
    showErrorMessage('Payment error: ${e.toString()}');
  }
}

Error Handling

The plugin may throw PlatformException in case of errors. It's recommended to wrap your payment code in a try-catch block to handle any exceptions.

Common error scenarios:

• Network connectivity issues
• Invalid payment parameters
• User cancellation
• Payment gateway server errors

Example App

For a complete implementation example, refer to the example app.

The example demonstrates:

• Setting up the plugin
• Creating payment parameters
• Initiating payment
• Handling responses and errors
• UI integration