NeoPay Flutter Plugin #

A comprehensive Flutter plugin for payment processing with support for PayU, UPI, and QR code generation. Built with clean architecture principles and designed for both merchant and customer payment flows.

Features #

• PayU Integration: Credit/Debit cards and NetBanking payments
• UPI Payments: Intent-based and collect payment flows
• QR Code Generation: Dynamic QR codes for payment collection
• Transaction Status: Real-time payment monitoring and verification
• Secure Hash Generation: Built-in cryptographic services
• Customizable UI: Themeable payment interfaces
• Clean Architecture: Well-structured, maintainable codebase
• Debug Mode: Enhanced logging for development

Supported Payment Methods #

PayU Integration #

• Credit Cards (CC)
• Debit Cards (DC)
• Net Banking (NB)
• Production and test environment support

UPI Payments #

• UPI Intent: Direct app-to-app payments
• UPI Collect: Request payments from UPI IDs
• iOS targeted launch: Opens the selected UPI app using its custom scheme (no OS picker)
• Transaction monitoring: Real-time status polling until success/failure/timeout

QR Code Payments #

• Dynamic QR code generation
• Real-time payment status monitoring
• Merchant collection flows

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  neopay:
    git:
      url: https://repo.splenta.com/neomaxer/mobile/neomaxer-payment-plugin
      ref: alwin

Or for local development:

dependencies:
  neopay:
    path: ../neopay

Quick Start #

1. Import and Setup #

import 'package:flutter/material.dart';
import 'package:neopay/neopay.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Set up bloc observer for debugging
  Bloc.observer = PrettyBlocObserver();
  
  runApp(MyApp());
}

2. Initialize with Configuration #

// Create configuration
final config = NeoPayConfig(
  apiBaseUrl: 'https://your-api.com/api',
  orderId: 'ORDER_123',
  fcmToken: 'your_fcm_token',
  authToken: 'your_auth_token',
  isPaying: true, // true for payment, false for QR generation
  debugMode: true, // Enable debug logging

  // Optional: PayU configuration (required only if using PayU)
  payUConfig: const PayUConfig(
    environment: PayUEnvironment.test,
  ),

  // Optional: Transaction status monitoring
  transactionStatusConfig: const TransactionStatusConfig(
    checkCount: 5,
    monitoringWindowSeconds: 120, // 2 minutes
    enableStatusChecking: true,
    initialDelaySeconds: 10,
  ),
  // Optional: Auto close the plugin after result
  autoRedirect: true,
  // Optional: Delay auto close by N seconds (works when autoRedirect is true)
  autoRedirectDelaySeconds: 0,
);

// Initialize SDK
await NeoPay.initialize(config);

Basic Usage #

1. Customer Payment Flow #

Show the payment UI with multiple payment options:

// Configure for payment mode
final paymentConfig = NeoPayConfig(
  apiBaseUrl: 'https://your-api.com/api',
  orderId: 'ORDER_123',
  fcmToken: 'your_fcm_token',
  authToken: 'your_auth_token',
  isPaying: true, // Set to true for payment
  debugMode: true,
  payUConfig: const PayUConfig(
    environment: PayUEnvironment.test,
  ),
);

// Initialize and show payment UI
await NeoPay.initialize(paymentConfig);

await NeoPay.showPaymentUI(
  context: context,
  config: paymentConfig,
  onPaymentResult: (PaymentResult result) {
    switch (result.status) {
      case 'success':
        // Payment completed successfully
        print('Payment successful: ${result.transactionId}');
        break;
      case 'failed':
        // Payment failed
        print('Payment failed: ${result.message}');
        break;
      case 'cancelled':
        // User cancelled payment
        print('Payment cancelled by user');
        break;
    }
  },
);

2. Merchant QR Code Generation #

Generate QR codes for collecting payments:

// Configure for QR generation mode
final qrConfig = NeoPayConfig(
  apiBaseUrl: 'https://your-api.com/api',
  orderId: 'ORDER_123',
  fcmToken: 'your_fcm_token',
  authToken: 'your_auth_token',
  isPaying: false, // Set to false for QR generation
  debugMode: true,
  transactionStatusConfig: const TransactionStatusConfig(
    checkCount: 6,
    monitoringWindowSeconds: 120,
    enableStatusChecking: true,
  ),
  autoRedirect: true,
  autoRedirectDelaySeconds: 0,
);

// Initialize and generate QR
await NeoPay.initialize(qrConfig);

await NeoPay.generateQrCode(
  context: context,
  config: qrConfig,
  onPaymentResult: (PaymentResult result) {
    if (result.status == 'success') {
      print('Payment received: ${result.transactionId}');
    } else if (result.status == 'timeout') {
      print('QR code expired');
    }
  },
);

3. SDK Management #

// Check if SDK is initialized
if (NeoPay.isInitialized) {
  print('SDK is ready');
}

// Reset SDK (useful when switching between modes)
await NeoPay.reset();

// Get platform version (optional)
final version = await NeoPay.platformVersion;
print('Platform version: $version');

Configuration Options #

NeoPayConfig Parameters #

PayUConfig Parameters #

TransactionStatusConfig Parameters #

Hash Service #

The plugin includes built-in cryptographic services:

import 'package:neopay/neopay.dart';

// Access hash service through the exported classes
// The plugin automatically handles hash generation for PayU payments

Architecture #

The plugin follows clean architecture principles with feature-based organization:

lib/
├── src/
│   ├── core/                    # Core functionality
│   │   ├── config/             # Configuration classes
│   │   ├── services/           # Utility services (logging, hash, UPI apps)
│   │   ├── network/            # HTTP client and networking
│   │   ├── di/                 # Dependency injection
│   │   ├── error/              # Error handling
│   │   ├── theme/              # UI theming
│   │   └── widgets/            # Reusable UI components
│   ├── features/               # Feature modules
│   │   ├── payment_flow/       # Main payment orchestration
│   │   ├── payment_modes/      # Payment method selection
│   │   ├── payu_payment/       # PayU integration
│   │   ├── upi_payment/        # UPI intent payments
│   │   ├── upi_collect/        # UPI collect requests
│   │   ├── qr_generator/       # QR code generation
│   │   └── transaction_status/ # Payment monitoring
│   └── shared/
│       └── models/             # Shared data models

Payment Flows #

Customer Payment Flow #

1. Initialize SDK with isPaying: true
2. Show Payment UI with available payment methods
3. Select Payment Method (UPI, PayU, etc.)
4. Process Payment through respective gateway
5. Return Result via callback

Merchant QR Flow #

1. Initialize SDK with isPaying: false
2. Generate QR Code for the order
3. Monitor Transaction Status (optional)
4. Receive Payment Notification via callback

Testing & Development #

Debug Mode #

Enable debug mode for detailed logging during development:

final config = NeoPayConfig(
  // ... other config
  debugMode: true, // Enable detailed logging
);

// Set up bloc observer for state management debugging
Bloc.observer = PrettyBlocObserver();

PayU Test Environment #

Use PayU's test environment for development:

payUConfig: const PayUConfig(
  merchantKey: 'YOUR_TEST_MERCHANT_KEY',
  merchantSalt: 'YOUR_TEST_MERCHANT_SALT',
  environment: PayUEnvironment.test,
),

SDK Reset #

Reset the SDK when switching between different configurations:

// Check if already initialized
if (NeoPay.isInitialized) {
  await NeoPay.reset();
}

// Initialize with new config
await NeoPay.initialize(newConfig);

Production Deployment #

1. PayU Production Setup #

payUConfig: const PayUConfig(
  merchantKey: 'YOUR_PRODUCTION_MERCHANT_KEY',
  merchantSalt: 'YOUR_PRODUCTION_MERCHANT_SALT',
  environment: PayUEnvironment.production,
),

2. Disable Debug Mode #

final config = NeoPayConfig(
  apiBaseUrl: 'https://your-api.com/api',
  orderId: 'ORDER_123',
  fcmToken: 'your_fcm_token',
  authToken: 'your_auth_token',
  isPaying: true,
  debugMode: false, // Disable debug logging in production
);

3. Error Monitoring #

Implement proper error handling for production:

onPaymentResult: (PaymentResult result) {
  // Log to your analytics service
  if (result.status == 'failed') {
    Analytics.logError('payment_failed', {
      'message': result.message,
      'order_id': orderId,
    });
  }
},

Error Handling #

The plugin provides comprehensive error handling with detailed error messages:

// PaymentResult status values
switch (result.status) {
  case 'success':
    // Payment completed successfully
    // result.transactionId contains the transaction ID
    break;
  case 'failed':
    // Payment failed - check result.message for details
    break;
  case 'cancelled':
    // User cancelled payment
    break;
  case 'timeout':
    // QR code expired or transaction timeout
    break;
}

// Error details are provided in result.message
print('Error details: ${result.message}');

Security Features #

• Secure Hash Generation: Automatic SHA512 hash generation for PayU
• Payment Verification: Server-side payment verification support
• Environment Separation: Clear separation between test and production
• No Local Storage: No sensitive data stored locally

Platform Support #

Dependencies #

Core dependencies used by the plugin:

dependencies:
  crypto: ^3.0.6
  dartz: ^0.10.1
  dio: ^5.7.0
  equatable: ^2.0.7
  flutter_bloc: ^8.1.6
  get_it: ^7.7.0
  intl: ^0.19.0
  payu_checkoutpro_flutter: ^1.3.2
  plugin_platform_interface: ^2.0.2
  qr_flutter: ^4.1.0
  upi_pay:
    path: ./upi_pay
  url_launcher: ^6.2.5
  window_size: ^0.1.0

Example App #

The plugin includes a comprehensive example app demonstrating all features:

cd example
flutter run

API Reference #

NeoPay Class #

// Main SDK methods
static Future<void> initialize(NeoPayConfig config, {bool enableDebugMode = false})
static Future<void> reset()
static bool get isInitialized
static Future<String?> get platformVersion

// Payment methods
static Future<void> showPaymentUI({required BuildContext context, required NeoPayConfig config, required Function(PaymentResult) onPaymentResult})
static Future<void> generateQrCode({required BuildContext context, required NeoPayConfig config, required Function(PaymentResult) onPaymentResult})

PaymentResult Class #

class PaymentResult {
  final String status;                // 'success', 'failed', 'cancelled', 'timeout'
  final String message;               // Detailed message
  final String? transactionId;        // Transaction ID (if available)
  final String? bankReferenceNumber;  // Gateway/Bank reference
  final bool fromFullScreenFlow;      // Internal flow indicator
  final String? paymentMethod;        // 'UPI', 'PayU', etc.
}

Contributing #

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup #

# Clone the repository
git clone https://repo.splenta.com/neomaxer/mobile/neomaxer-payment-plugin
cd neopay

# Install dependencies
flutter pub get

# Run example app
cd example
flutter run

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Support & Resources #

PayU Integration #

• PayU Flutter SDK Documentation
• PayU Merchant Dashboard
• PayU Support Team`

Version Compatibility #

• Flutter: 3.24.3+
• Dart: 3.5.0+
• Android: API 24+
• iOS: 12.0+

Made by Alwin ❤️ for the Neomaxer