Moneroo Flutter SDK provides a simple and reliable way to integrate payment processing into your Flutter applications, with support for various payment methods across multiple African countries. The SDK offers both a ready-to-use payment widget and a flexible API wrapper for custom implementations.
- 🌍 Multi-currency support - Process payments in XOF, XAF, NGN, GHS, and many other African currencies
- 🔌 Multiple payment methods - Support for mobile money, bank transfers, cards, and more
- 🛡️ Secure transactions - PCI-compliant payment processing
- 📱 Ready-to-use UI - Pre-built payment widget for quick integration
- 🔧 Flexible API - Direct API access for custom implementations
- 🧪 Sandbox mode - Test your integration without real transactions
❗ In order to start using Moneroo Flutter you must have the [Flutter SDK][flutter_install_link] installed on your machine.
- Flutter SDK 2.5.0 or higher
- Dart 2.14.0 or higher
- A Moneroo account and API key (get yours at moneroo.io)
Install via flutter pub add:
flutter pub add moneroo_flutter_sdkAlternatively, add the dependency to your pubspec.yaml file:
dependencies:
moneroo_flutter_sdk: ^0.3.4 # Use the latest versionThen run:
flutter pub getAdd this line in your AndroidManifest.xml. This will help you to avoid an ERR_CLEAR_TEXT_NOT_PERMITTED error while processing a payment.
Don't forget to allow internet access in your Android app ! Info here !
<application
...
android:usesCleartextTraffic="true"
...
>
...
</application>Add this line in your Info.plist. This will help you to avoid an ERR_CLEAR_TEXT_NOT_PERMITTED error while processing a payment.
<plist>
...
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
...
<plist>This README provides basic usage information. For more detailed documentation:
- Example App: Check out the complete example here
- API Reference: Comprehensive API documentation is available in the code
- Official Docs: Visit docs.moneroo.io for the official Moneroo documentation
The SDK offers two main ways to integrate payments:
- Using the Moneroo Widget - A pre-built UI component that handles the entire payment flow
- Using the MonerooApi class - Direct API access for custom implementations
Here's a simple example of how to integrate the Moneroo payment widget in your Flutter app:
import 'package:flutter/material.dart';
import 'package:moneroo_flutter_sdk/moneroo_flutter_sdk.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Moneroo Demo',
home: const MyHomePage(),
);
}
}
class MyHomePage extends StatelessWidget {
const MyHomePage({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
body: Center(
child: ElevatedButton(
child: const Text('Pay Now'),
onPressed: () {
Navigator.of(context).push(
MaterialPageRoute(
builder: (context) => Moneroo(
amount: 1, // Amount to charge
apiKey: 'YOUR_API_KEY', // Your Moneroo API key
currency: MonerooCurrency.XOF, // Currency code
customer: MonerooCustomer(
email: '[email protected]',
firstName: 'John',
lastName: 'Doe',
),
description: 'Payment description',
onPaymentCompleted: (infos, context) {
if (infos.status == MonerooStatus.success) {
Navigator.of(context).pop();
} else {
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(
content: Text('Payment failed'),
backgroundColor: Colors.red,
),
);
}
},
onError: (error, context) {
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(
content: Text('An error occurred'),
backgroundColor: Colors.red,
),
);
Navigator.pop(context);
},
),
),
);
},
),
),
);
}
}- Moneroo Widget: The main widget that handles the payment flow
- MonerooCustomer: Customer information required for the payment
- MonerooCurrency: Supported currency codes (e.g., XOF)
- MonerooStatus: Payment status enumeration
amount: The amount to chargeapiKey: Your Moneroo API keycurrency: The currency codecustomer: Customer informationdescription: Payment descriptiononPaymentCompleted: Callback for payment completiononError: Callback for error handling
While the Moneroo widget provides a complete payment flow with UI, you can also use the MonerooApi class directly for more customized payment processing. This is useful when you want to implement your own UI or integrate Moneroo payments into an existing flow.
final api = MonerooApi(
apiKey: 'YOUR_API_KEY',
sandbox: false, // Set to true for testing
);final payment = await api.initPayment(
amount: 5000, // Amount in smallest currency unit (e.g., cents)
customer: MonerooCustomer(
email: '[email protected]',
firstName: 'John',
lastName: 'Doe',
phone: '+1234567890', // Optional
country: 'US', // Optional
),
currency: MonerooCurrency.XOF,
description: 'Premium subscription',
callbackUrl: 'https://your-app.com/payment-callback', // Optional
metadata: { 'orderId': '12345' }, // Optional
);
// The checkout URL can be used in a WebView or browser
final checkoutUrl = payment.checkoutUrl;
// Store the payment ID for later verification
final paymentId = payment.id;final paymentInfo = await api.getMonerooPaymentInfos(
paymentId: 'payment_123456789',
);
switch (paymentInfo.status) {
case MonerooStatus.success:
print('Payment was successful!');
// Handle successful payment
break;
case MonerooStatus.pending:
print('Payment is still being processed...');
// Maybe show a waiting screen
break;
case MonerooStatus.failed:
print('Payment failed.');
// Handle failed payment
break;
case MonerooStatus.cancelled:
print('Payment was cancelled.');
// Handle cancelled payment
break;
case MonerooStatus.initiated:
print('Payment has been initiated but not yet processed.');
// Maybe redirect to payment page
break;
}final methods = await api.getMonerooPaymentMethods();
// Display available payment methods to the user
for (final method in methods) {
print('${method.name}: ${method.description}');
}try {
final payment = await api.initPayment(
amount: 5000,
customer: customer,
currency: MonerooCurrency.XOF,
description: 'Premium subscription',
);
// Process payment
} on MonerooException catch (e) {
// Handle Moneroo API errors
print('Error code: ${e.code}');
print('Error message: ${e.message}');
if (e.errors != null) {
print('Detailed errors: ${e.errors}');
}
} on ServiceUnavailableException {
// Handle service unavailable errors (e.g., network issues)
print('Service is currently unavailable. Please try again later.');
} catch (e) {
// Handle other errors
print('An unexpected error occurred: $e');
}Moneroo provides a sandbox environment for testing your integration without making real transactions. To use the sandbox mode:
// When using the widget
Moneroo(
apiKey: 'YOUR_API_KEY',
sandbox: true, // Enable sandbox mode
// other parameters...
);
// When using the API directly
final api = MonerooApi(
apiKey: 'YOUR_API_KEY',
sandbox: true, // Enable sandbox mode
);In sandbox mode, you can use test cards and payment methods to simulate different payment scenarios. For more information on testing, visit the Moneroo Testing Documentation.
The SDK throws the following exceptions that you should handle in your code:
-
MonerooException: Thrown when an error occurs during API communication. Contains:
code: HTTP status code or custom error codemessage: Human-readable error messageerrors: Detailed error information (if available)
-
ServiceUnavailableException: Thrown when the SDK cannot reach the Moneroo servers, typically due to network issues.
try {
// Moneroo API call
} on MonerooException catch (e) {
// Log the error details
print('Moneroo Error: ${e.message} (Code: ${e.code})');
// Show appropriate message to the user
if (e.code == 401) {
// Authentication error
} else if (e.code == 400) {
// Invalid request
}
} on ServiceUnavailableException {
// Handle connectivity issues
print('Cannot connect to Moneroo. Please check your internet connection.');
} catch (e) {
// Handle other unexpected errors
print('Unexpected error: $e');
}Currently, the SDK is optimized for mobile platforms (Android and iOS). Flutter Web support is planned for future releases.
Moneroo can send webhook notifications to your server when payment status changes. Configure your webhook URL in the Moneroo dashboard and implement an endpoint on your server to process these notifications.
If you need a custom UI, use the MonerooApi class directly instead of the pre-built widget. This gives you full control over the payment flow and UI.
Contributions are welcome! If you'd like to contribute to the Moneroo Flutter SDK:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
If you discover a security vulnerability within Moneroo Flutter SDK, please send an e-mail to Moneroo Security via [email protected]. All security vulnerabilities will be promptly addressed.
For support, questions, or feedback:
- 📧 Email: [email protected]
- 📝 Issues: GitHub Issues
- 📚 Documentation: docs.moneroo.io
The Moneroo Flutter SDK is open-sourced software licensed under the MIT license.