Intégrer GeniusPay sur Flutter en 10 minutes

Flutter est devenu le framework de choix pour le développement mobile en Afrique. Dans ce tutoriel, nous allons voir comment intégrer le SDK GeniusPay pour accepter les paiements Wave, Orange Money et Cartes.

1. Installation du Package

Ajoutez geniuspay_flutter à votre fichier pubspec.yaml ou lancez la commande suivante :

flutter pub add geniuspay_flutter

2. Initialisation

Importez le package et initialisez-le avec votre clé publique (trouvable dans votre dashboard).

import 'package:geniuspay_flutter/geniuspay_flutter.dart';

void main() {
  GeniusPay.init(
    publicKey: "pk_live_xxxxxxxx",
    sandbox: false // Mettre true pour tester
  );
  runApp(MyApp());
}

3. Lancer le Paiement

Utilisez le widget GeniusPayButton ou appelez la méthode GeniusPay.charge() directement.

final payment = PaymentRequest(
  amount: 5000,
  currency: 'XOF',
  reason: 'Achat Premium',
  customer: Customer(
    email: 'client@email.com',
    name: 'Jean Kouassi'
  )
);

try {
  final response = await GeniusPay.charge(context, payment);
  if (response.isSuccess) {
    print("Paiement réussi : ${response.transactionId}");
  }
} catch (e) {
  print("Erreur : $e");
}

Best Practices

Gérez les Webhooks : Ne vous fiez pas uniquement au retour de l'application mobile. Écoutez les webhooks côté serveur pour valider la livraison du service.
Sandbox d'abord : Testez toujours en mode sandbox avant de passer en production.

Voir la documentation complète

Prérequis : Flutter 3.0+, Dart 3.0+, et une compréhension basique de Dart et Flutter.

📱 Pourquoi GeniusPay pour Flutter ?

GeniusPay offre une solution complète pour intégrer les paiements mobiles (Wave, Orange Money, MTN, Moov) et les cartes bancaires directement dans votre application Flutter. Notre SDK est léger, performant et supporte iOS et Android.

🚀 Installation du SDK

Étape 1 : Ajouter la dépendance

Dans votre fichier pubspec.yaml :

dependencies:
  flutter:
    sdk: flutter
  geniuspay_flutter: ^1.0.0
  http: ^1.1.0
  crypto: ^3.0.0

Puis exécutez :

flutter pub get

Étape 2 : Initialiser GeniusPay

Dans votre main.dart :

import 'package:geniuspay_flutter/geniuspay_flutter.dart';

void main() {
  GeniusPay.initialize(
    publicKey: 'pk_live_xxxxxxxxxxxxx',
    environment: GeniusPayEnvironment.live,
  );
  runApp(const MyApp());
}

💳 Créer une Transaction

Exemple Basique

import 'package:geniuspay_flutter/geniuspay_flutter.dart';

class PaymentScreen extends StatefulWidget {
  @override
  State<PaymentScreen> createState() => _PaymentScreenState();
}

class _PaymentScreenState extends State<PaymentScreen> {
  final geniuspay = GeniusPay();

  void initiatePayment() async {
    try {
      final payment = await geniuspay.initiatePayment(
        amount: 5000,
        currency: 'XOF',
        description: 'Achat de produit',
        customerName: 'John Doe',
        customerEmail: 'john@example.com',
        customerPhone: '+2250704750465',
        metadata: {
          'order_id': '12345',
          'product': 'Premium Plan',
        },
      );

      // Ouvrir le checkout
      final result = await geniuspay.openCheckout(payment.checkoutUrl);

      if (result.status == PaymentStatus.success) {
        print('Paiement réussi: ${result.reference}');
        // Mettre à jour votre UI
      } else if (result.status == PaymentStatus.failed) {
        print('Paiement échoué');
      }
    } catch (e) {
      print('Erreur: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Paiement')),
      body: Center(
        child: ElevatedButton(
          onPressed: initiatePayment,
          child: Text('Payer 5000 XOF'),
        ),
      ),
    );
  }
}

🔐 Vérifier les Paiements (Webhooks)

Pour vérifier les paiements côté serveur, utilisez notre API REST :

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<bool> verifyPayment(String reference) async {
  final response = await http.get(
    Uri.parse('https://api.pay.genius.ci/v1/payments/$reference'),
    headers: {
      'Authorization': 'Bearer sk_live_xxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
  );

  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    return data['data']['status'] == 'completed';
  }
  return false;
}

🧪 Mode Sandbox pour les Tests

Avant de passer en production, testez en mode Sandbox :

GeniusPay.initialize(
  publicKey: 'pk_sandbox_xxxxxxxxxxxxx',
  environment: GeniusPayEnvironment.sandbox,
);

Scénarios de test disponibles :

success - Paiement réussi
failure - Paiement échoué
pending - Paiement en attente

📊 Gestion des Erreurs

try {
  final payment = await geniuspay.initiatePayment(...);
} on GeniusPayException catch (e) {
  switch (e.code) {
    case 'INVALID_AMOUNT':
      print('Montant invalide');
      break;
    case 'NETWORK_ERROR':
      print('Erreur réseau');
      break;
    case 'AUTHENTICATION_ERROR':
      print('Clé API invalide');
      break;
    default:
      print('Erreur: ${e.message}');
  }
} catch (e) {
  print('Erreur inattendue: $e');
}

🎨 Personnaliser le Checkout

final payment = await geniuspay.initiatePayment(
  amount: 5000,
  currency: 'XOF',
  description: 'Mon produit',
  theme: CheckoutTheme(
    primaryColor: Colors.blue,
    buttonText: 'Payer maintenant',
    language: 'fr',
  ),
);

📱 Gestion des Notifications

Écoutez les changements de statut de paiement :

geniuspay.onPaymentStatusChanged.listen((status) {
  if (status == PaymentStatus.success) {
    print('Paiement confirmé');
    // Mettre à jour la UI
  } else if (status == PaymentStatus.failed) {
    print('Paiement échoué');
  }
});

🆘 Troubleshooting

Le checkout ne s'ouvre pas

Vérifiez que votre clé publique est correcte
Assurez-vous que l'URL est valide
Vérifiez les permissions d'accès à Internet dans AndroidManifest.xml

Erreur "INVALID_AMOUNT"

Le montant doit être un nombre positif
Montant minimum : 100 XOF
Montant maximum : 999999999 XOF

📚 Ressources Supplémentaires

Retour à l'Academy