neopay 1.0.0

A Flutter package for handling payment flows with UPI, PayU, and QR code generation.

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

Parameter	Type	Required	Description
apiBaseUrl	String	✅	Your API server base URL
orderId	String	✅	Unique order identifier
fcmToken	String	✅	Firebase Cloud Messaging token
authToken	String	✅	Authentication token
isPaying	bool	✅	true for payment mode, false for QR generation
debugMode	bool	❌	Enable debug logging (default: false)
customerName	String?	❌	Customer name for payments
customerEmail	String?	❌	Customer email for payments
customerPhone	String?	❌	Customer phone for payments
payUConfig	PayUConfig?	❌	PayU payment configuration
transactionStatusConfig	TransactionStatusConfig?	❌	Transaction monitoring settings
autoRedirect	bool	❌	Auto-close screen and return result when status resolves (default: true)
autoRedirectDelaySeconds	int	❌	Delay before auto-close in seconds (default: 0)
theme	NeoThemeData?	❌	Custom UI theme
qrTheme	QrGeneratorTheme?	❌	QR code styling

PayUConfig Parameters

Parameter	Type	Required	Description
environment	PayUEnvironment	❌	test or production (default: test)

TransactionStatusConfig Parameters

Parameter	Type	Required	Description
checkCount	int	❌	Number of status checks (default: 6)
monitoringWindowSeconds	int	❌	Total monitoring window in seconds (default: 120). Also used for UPI monitoring timebox
enableStatusChecking	bool	❌	Enable monitoring (default: true)
initialDelaySeconds	int	❌	Delay before first check (default: 10)

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

Platform	Payment UI	QR Generation	UPI Support
Android	✅	✅	✅
iOS	✅	✅	✅
Windows	❌	✅	❌

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