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: 'johndoe@email.com',
      // 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: 'johndoe@email.com',

  // 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: 'johndoe@email.com',
  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: 'johndoe@email.com',
  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: 'johndoe@email.com',
  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: 'johndoe@email.com',
  flashNumber: '1234567890',
  flashPin: '1234',
);

User Info & Payment Method Info Options #

Control which forms are shown to the user:

// 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 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('user@example.com');

// 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: support@lokotroo.com
• 🐛 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