lokotro_pay 1.0.3

Lokotro Pay: A modern Flutter payment plugin with glassmorphism design for seamless payment collection via cards and mobile money.

Lokotro Pay 💳

Lokotro Pay is a modern Flutter payment plugin with glassmorphism design for seamless payment collection via cards, mobile money, e-wallets, and more. Built with enhanced UI/UX and inspired by Lokotro's modern design language.

✨ Features

• 🎨 Modern Glassmorphism Design - Beautiful dark theme with glass-like effects
• 💳 Multiple Payment Methods - Cards, Mobile Money, E-Wallets, Bank Transfers
• 🔄 Reactive State Management - Built with RxDart for smooth user experience
• 🌍 Multi-Environment Support - Development and production configurations
• 🌐 Multi-Language Support - 10 languages with easy language switching
• 📱 Responsive Design - Optimized for all screen sizes
• 🎯 Haptic Feedback - Enhanced user interaction with tactile responses
• 🔒 Secure Processing - Enterprise-grade security for payment handling
• 🚀 Easy Integration - Simple API with comprehensive documentation

🚀 Quick Start

Installation

Add lokotro_pay to your pubspec.yaml:

dependencies:
  lokotro_pay: ^1.0.1

Run:

flutter pub get

Basic Usage

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

class PaymentScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: () => _startPayment(context),
          child: Text('Pay \$50.00'),
        ),
      ),
    );
  }

  void _startPayment(BuildContext context) {
    // Configure payment settings
    final configs = LokotroPayConfigs(
      token: 'your_encrypted_app_key_here',
      isProduction: false, // Set to true for production
      acceptLanguage: 'en', // Language for API responses
    );

    // Create payment request
    final paymentBody = LokotroPaymentBody(
      customerReference: 'ORDER_${DateTime.now().millisecondsSinceEpoch}',
      amount: '50.00',
      currency: 'USD',
      paymentMethod: 'wallet', // wallet, card, mobile_money, flash, bank_transfer
      userInfo: 'full', // full, partial, none
      paymentMethodInfo: 'full', // full, partial, none
      feeCoveredBy: 'buyer', // buyer or seller
      deliveryBehaviour: 'direct_delivery', // direct_delivery or escrow
      // User information (required when userInfo = 'full')
      firstName: 'John',
      lastName: 'Doe',
      phoneNumber: '2439978540000',
      email: '[e-mail]',
      // Wallet credentials (required when paymentMethod = 'wallet' and paymentMethodInfo = 'full')
      walletNumber: '3005710720108954',
      walletPin: '048698',
      // Callback URLs
      notifyUrl: 'https://yourserver.com/notify',
      successRedirectUrl: 'https://yourserver.com/success',
      failRedirectUrl: 'https://yourserver.com/failed',
      // Merchant information
      merchant: const LokotroMerchantInfo(
        name: 'My Store',
        url: 'https://mystore.com',
        logo: 'https://mystore.com/logo.png',
      ),
      metadata: {
        'order_id': '12345',
        'source': 'mobile_app',
      },
    );

    // Launch payment flow
    Navigator.of(context).push(
      MaterialPageRoute(
        builder: (context) => LokotroPayCheckout(
          configs: configs,
          paymentBody: paymentBody,
          onResponse: (response) {
            // Handle successful payment
            print('Payment successful: ${response.message}');
            Navigator.of(context).pop();
          },
          onError: (error) {
            // Handle payment error
            print('Payment failed: ${error.message}');
            Navigator.of(context).pop();
          },
        ),
      ),
    );
  }
}

📖 Documentation

Configuration

LokotroPayConfigs

Configure your payment environment and authentication:

final configs = LokotroPayConfigs(
  token: 'your_encrypted_app_key',   // Required: Encrypted API key from backend
  isProduction: false,               // Optional: Environment (default: false)
  customApiUrl: 'https://api.custom.com', // Optional: Custom API endpoint
  timeout: Duration(seconds: 60),    // Optional: Request timeout
  acceptLanguage: 'en',              // Optional: Language for API responses (default: 'fr')
);

LokotroPaymentBody

Define your payment request details:

final paymentBody = LokotroPaymentBody(
  // Required fields
  customerReference: 'ORDER_12345',  // Required: Unique customer reference
  amount: '100.00',                  // Required: Amount as string
  currency: 'USD',                   // Required: Currency code

  // Payment configuration
  paymentMethod: 'wallet',           // wallet, card, mobile_money, flash, bank_transfer
  userInfo: 'full',                  // full, partial, none - controls user form visibility
  paymentMethodInfo: 'full',         // full, partial, none - controls payment method form
  feeCoveredBy: 'buyer',             // buyer or seller
  deliveryBehaviour: 'direct_delivery', // direct_delivery or escrow

  // User information (required when userInfo = 'full')
  firstName: 'John',
  lastName: 'Doe',
  phoneNumber: '2439978540000',
  email: '[e-mail]',

  // E-wallet fields (when paymentMethod = 'wallet')
  walletNumber: '3005710720108954',
  walletPin: '048698',

  // Mobile money fields (when paymentMethod = 'mobile_money')
  mobileMoneyPhoneNumber: '2439978540000',

  // Flash fields (when paymentMethod = 'flash')
  flashNumber: '1234567890',
  flashPin: '1234',

  // Card fields (when paymentMethod = 'card' with DIRECT_CAPTURE)
  cardNumber: '4111111111111111',
  cardExpiryDate: '12/25',
  cardCvv: '123',
  cardHolderName: 'John Doe',

  // Mastercard payment method (for card payments)
  mastercardPaymentMethod: 'HOSTED_SESSION', // or 'DIRECT_CAPTURE'

  // Callback URLs
  notifyUrl: 'https://yourserver.com/notify',
  successRedirectUrl: 'https://yourserver.com/success',
  failRedirectUrl: 'https://yourserver.com/failed',

  // Merchant information
  merchant: LokotroMerchantInfo(
    name: 'My Store',
    url: 'https://mystore.com',
    logo: 'https://mystore.com/logo.png',
  ),

  // Additional metadata
  metadata: {
    'order_id': '12345',
    'source': 'mobile_app',
  },
);

Payment Flow

The plugin provides a complete payment flow with multiple screens:

1. Payment Method Selection - Choose from available payment options
2. Payment Form - Enter payment details (card info, phone number, etc.)
3. Processing - Secure payment processing with loading indicators
4. Result Screen - Success or error feedback with next actions

Supported Payment Methods

• 💳 Payment Cards - Visa, Mastercard, American Express (HOSTED_SESSION or DIRECT_CAPTURE)
• 📱 Mobile Money - Various mobile money providers
• 💰 E-Wallets - Lokotro wallet integration
• 🏦 Bank Transfers - Direct bank account transfers
• ⚡ Lokotro Flash - Instant payment method

Payment Method Examples

E-Wallet Payment

final paymentBody = LokotroPaymentBody(
  customerReference: 'WALLET_${DateTime.now().millisecondsSinceEpoch}',
  amount: '50.00',
  currency: 'USD',
  paymentMethod: 'wallet',
  userInfo: 'full',
  paymentMethodInfo: 'full',
  firstName: 'John',
  lastName: 'Doe',
  phoneNumber: '2439978540000',
  email: '[e-mail]',
  walletNumber: '3005710720108954',
  walletPin: '048698',
);

Mobile Money Payment

final paymentBody = LokotroPaymentBody(
  customerReference: 'MOMO_${DateTime.now().millisecondsSinceEpoch}',
  amount: '25.00',
  currency: 'USD',
  paymentMethod: 'mobile_money',
  userInfo: 'full',
  paymentMethodInfo: 'full',
  firstName: 'John',
  lastName: 'Doe',
  phoneNumber: '2439978540000',
  email: '[e-mail]',
  mobileMoneyPhoneNumber: '2439978540000',
);

Card Payment (Hosted Session - Recommended)

final paymentBody = LokotroPaymentBody(
  customerReference: 'CARD_${DateTime.now().millisecondsSinceEpoch}',
  amount: '100.00',
  currency: 'USD',
  paymentMethod: 'card',
  userInfo: 'full',
  paymentMethodInfo: 'full', // Card handled by secure session
  mastercardPaymentMethod: 'HOSTED_SESSION',
  firstName: 'John',
  lastName: 'Doe',
  phoneNumber: '2439978540000',
  email: '[e-mail]',
  successRedirectUrl: 'https://yourserver.com/success',
  failRedirectUrl: 'https://yourserver.com/failed',
  notifyUrl: 'https://yourserver.com/notify',
);

Flash Payment

final paymentBody = LokotroPaymentBody(
  customerReference: 'FLASH_${DateTime.now().millisecondsSinceEpoch}',
  amount: '10.00',
  currency: 'USD',
  paymentMethod: 'flash',
  userInfo: 'full',
  paymentMethodInfo: 'full',
  firstName: 'John',
  lastName: 'Doe',
  phoneNumber: '2439978540000',
  email: '[e-mail]',
  flashNumber: '1234567890',
  flashPin: '1234',
);

User Info & Payment Method Info Options

Control which forms are shown to the user:

userInfo	paymentMethodInfo	User Form	Payment Form
none	none	Visible	Visible
full	none	Hidden	Visible
none	full	Visible	Hidden
full	full	Hidden	Hidden

// Show both forms (user enters all info)
final paymentBody = LokotroPaymentBody(
  userInfo: 'none',
  paymentMethodInfo: 'none',
  // ... other fields
);

// Pre-fill user info, show payment form only
final paymentBody = LokotroPaymentBody(
  userInfo: 'full',
  paymentMethodInfo: 'none',
  firstName: 'John',
  lastName: 'Doe',
  // ... other fields
);

🌐 Multi-Language Support

The plugin supports 10 languages out of the box. You can set the language when initializing the checkout widget:

import 'package:lokotro_pay/enums/lokotro_pay_language.dart';

LokotroPayCheckout(
  // ... other parameters
  language: LokotroPayLanguage.french, // Set specific language
  // ... other parameters
)

Supported Languages

Language	Code	Native Name
English	en	English
French	fr	Français
German	de	Deutsch
Spanish	es	Español
Italian	it	Italiano
Russian	ru	Русский
Hindi	hi	हिंदी
Japanese	ja	日本語
Chinese	zh	中文（普通话）
Lingala	ln	Lingala

Language Selection Examples

// English (default)
LokotroPayCheckout(
  language: LokotroPayLanguage.english,
  // ... other parameters
)

// French
LokotroPayCheckout(
  language: LokotroPayLanguage.french,
  // ... other parameters
)

// Dynamic language selection
LokotroPayLanguage selectedLanguage = LokotroPayLanguage.fromCode('es') ?? LokotroPayLanguage.english;
LokotroPayCheckout(
  language: selectedLanguage,
  // ... other parameters
)

// Use device locale (default behavior when language is null)
LokotroPayCheckout(
  language: null, // Will use device locale or fallback to English
  // ... other parameters
)

Language Utilities

// Get all supported languages
List<LokotroPayLanguage> languages = LokotroPayLanguage.values;

// Get language from code
LokotroPayLanguage? language = LokotroPayLanguage.fromCode('fr');

// Get supported locales
List<Locale> locales = LokotroPayLanguage.supportedLocales;

// Get language details
Map<String, String> languageInfo = LokotroPayLanguage.french.toMap();
// Returns: {'code': 'fr', 'label': 'Français', 'flag': 'assets/flags/france.svg'}

Response Handling

Success Response

void handlePaymentResponse(LokotroPayOnResponse response) {
  print('Payment Amount: ${response.amount}');
  print('Currency: ${response.currency}');
  print('Status: ${response.paymentStatus.displayName}');
  print('Transaction ID: ${response.transactionId}');
  print('System Reference: ${response.systemRef}');
  print('Custom Reference: ${response.customRef}');
  print('Timestamp: ${response.timestamp}');
}

Error Handling

void handlePaymentError(LokotroPayOnError error) {
  print('Error Title: ${error.title}');
  print('Error Message: ${error.message}');
  print('Error Code: ${error.errorCode?.code}');
  print('Timestamp: ${error.timestamp}');

  // Show user-friendly error message
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(content: Text(error.message)),
  );
}

🎨 Customization

Theme Customization

The plugin uses Lokotro's modern design system with glassmorphism effects. You can customize colors and styling:

LokotroPayCheckout(
  configs: configs,
  paymentBody: paymentBody,
  language: LokotroPayLanguage.english,
  backgroundColor: LokotroPayColors.backgroundDark,
  themeConfig: LokotroPayThemeConfig.dark(
    primaryColor: LokotroPayColors.primary,
    backgroundColor: LokotroPayColors.backgroundDark,
  ),
  onResponse: handlePaymentResponse,
  onError: handlePaymentError,
)

Available Colors

The plugin provides a comprehensive color palette:

// Primary colors
LokotroPayColors.primary
LokotroPayColors.secondary
LokotroPayColors.accent

// Status colors
LokotroPayColors.success
LokotroPayColors.error
LokotroPayColors.warning
LokotroPayColors.info

// Background colors
LokotroPayColors.backgroundDark
LokotroPayColors.cardDark
LokotroPayColors.surfaceDark

// Text colors
LokotroPayColors.textPrimaryDark
LokotroPayColors.textSecondaryDark

🔧 Advanced Usage

Environment Configuration

Set up different environments for development and production:

// Development
await LokotroPayEnv.initialize(isProduction: false);

// Production
await LokotroPayEnv.initialize(isProduction: true);

Custom API Endpoints

Override default API endpoints:

final configs = LokotroPayConfigs(
  token: 'your_token',
  customApiUrl: 'https://your-custom-api.com',
  timeout: Duration(minutes: 2),
);

Utility Functions

The plugin provides helpful utility functions:

// Format currency
String formatted = LokotroPayUtils.formatCurrency(100.50, 'USD');

// Validate card number
bool isValid = LokotroPayUtils.isValidCardNumber('4111111111111111');

// Validate email
bool isValidEmail = LokotroPayUtils.isValidEmail('[e-mail]');

// Show snackbar with Lokotro styling
LokotroPayUtils.showSnackBar(
  context,
  'Payment successful!',
  type: LokotroPayResultScreen.successScreen,
);

🛠️ Development

Running the Example

1. Clone the repository
2. Navigate to the example directory:

   cd lokotro_pay/example
   

3. Install dependencies:

   flutter pub get
   

4. Run the example:

   flutter run
   

Testing

Run tests for the plugin:

cd lokotro_pay
flutter test

📋 Requirements

• Flutter SDK: >=3.3.0
• Dart SDK: ^3.8.1
• Android: API level 21+
• iOS: 12.0+

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

📄 License

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

🆘 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation

🙏 Acknowledgments

• Built with ❤️ by the Lokotroo team
• Inspired by modern payment experiences
• Special thanks to the Flutter community

---

Made with ❤️ for the Flutter community