Flutter SDK

Overview

The Moosyl Flutter SDK is a powerful tool for integrating payment solutions with Mauritania's popular banking apps, such as Bankily, Sedad, and Masrivi. Simplify the payment process in your Flutter applications with features like webhooks and an easy-to-use interface.

Features

Seamless Integration: Easily connect with local banking apps
Customizable: Adapt the payment UI with flexible options
Webhook Support: Enable real-time payment status updates
Localization: Built-in support for multiple languages and locales
Cross-Platform: Fully compatible with iOS, Android, and the web
Multi-Platform Readiness: While not extensively tested, the package should theoretically work on Linux, macOS, and Windows as well

Installation

Add the Moosyl package to your pubspec.yaml:

dependencies:
  moosyl: ^1.0.10

Fetch the package:

flutter pub get

Import the Package

import 'package:moosyl/moosyl.dart';

Getting Started

1) Create a Payment Request (Backend)

Create a payment request on your backend and pass the returned transactionId to your Flutter app. See: API quickstart.

2) Display the Payment View (Flutter)

Before instantiating MoosylView, make sure your MaterialApp registers the Moosyl localization delegates and supported locales:

return MaterialApp(
  localizationsDelegates: MoosylLocalization.localizationsDelegates,
  supportedLocales: MoosylLocalization.supportedLocales,
  // ... other MaterialApp properties
);

Here's how you can use the MoosylView widget in your Flutter app:

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

class PaymentScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MoosylView(
      publishableApiKey: 'YOUR_PUBLISHABLE_API_KEY',
      transactionId: 'TRANSACTION_ID', // Retrieved from your backend
      organizationLogo: const Text('Your Logo Here'),
      customHandlers: {
        PaymentMethodTypes.bimBank: () {
          print('Custom handler for BIM Bank payment method');
        },
      },
      onPaymentSuccess: () {
        print('Payment was successful!');
      },
    );
  }
}

API Reference

The main widget for displaying the payment interface.

Properties

Property	Type	Description	Required
`publishableApiKey`	`String`	Your Moosyl publishable API key	Yes
`transactionId`	`String`	Unique transaction identifier from backend	Yes
`organizationLogo`	`Widget`	Your organization's logo to display	No
`customHandlers`	`Map<PaymentMethodTypes, VoidCallback>`	Custom actions for specific payment methods	No
`onPaymentSuccess`	`VoidCallback`	Callback when payment succeeds	No
`onPaymentError`	`Function(String error)`	Callback when payment fails	No
`onPaymentCancel`	`VoidCallback`	Callback when payment is cancelled	No

Example Usage

MoosylView(
  publishableApiKey: 'pk_test_...',
  transactionId: 'txn_123456789',
  organizationLogo: Image.asset('assets/logo.png'),
  customHandlers: {
    PaymentMethodTypes.bankily: () {
      // Custom logic for Bankily payments
      _handleBankilyPayment();
    },
    PaymentMethodTypes.sedad: () {
      // Custom logic for Sedad payments
      _handleSedadPayment();
    },
  },
  onPaymentSuccess: () {
    Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (context) => SuccessPage()),
    );
  },
  onPaymentError: (error) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('Payment failed: $error')),
    );
  },
  onPaymentCancel: () {
    Navigator.pop(context);
  },
)

PaymentMethodTypes

Enum representing different payment methods available:

enum PaymentMethodTypes {
  bankily,
  sedad,
  masrivi,
  bimBank,
}

Configuration

Use your publishable key in Flutter, and create payment requests with your backend. See: API Keys.

Best Practices

Security

Never expose your secret API key in your Flutter app
Always use HTTPS for API calls
Validate webhook signatures on your backend
Store sensitive data securely using Flutter's secure storage

Error Handling

MoosylView(
  // ... other properties
  onPaymentError: (error) {
    // Log the error for debugging
    print('Payment error: $error');
    
    // Show user-friendly message
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('Payment failed. Please try again.'),
        action: SnackBarAction(
          label: 'Retry',
          onPressed: () {
            // Retry payment logic
          },
        ),
      ),
    );
  },
)