Welloo SDK

Welloo SDK est un SDK Flutter qui facilite l'intégration du service de paiement Welloo dans vos applications mobiles. Il fournit des widgets pour configurer et exécuter des paiements de manière sécurisée avec un système de vérification moderne et résilient.

✨ Fonctionnalités #

Interface Utilisateur #

• 💳 Initialisation sécurisée du SDK
• 🔗 Gestion sécurisée des transactions (dépôt, transfert)
• 📦 Intégration rapide dans n'importe quelle app Flutter
• 🧩 Compatible Android & iOS
• 🎨 Interface moderne avec animations et design responsive
• 🔄 Gestion automatique du cycle de vie avec WidgetsBindingObserver

Nouveau Système de Vérification #

• ⚡ 3 stratégies de vérification : Polling, Deeplink, Hybrid
• 🎯 8 configurations prédéfinies : Wave, Wello, Production, Development, etc.
• 🛡️ Circuit Breaker : Protection contre les cascades d'erreurs
• 🔄 Retry Policy : Retry automatique avec exponential backoff
• 📊 Métriques détaillées : Taux de succès, temps de réponse, etc.
• 📡 12 types d'events : Monitoring en temps réel
• 🔍 Logs structurés : 4 niveaux (DEBUG, INFO, WARNING, ERROR)
• ✅ Type-safe : Sealed classes avec pattern matching

🎯 Système de Vérification #

Le SDK propose 3 stratégies pour vérifier vos transactions :

Configurations Prédéfinies #

🚀 Installation #

1. Ajouter la dépendance #

flutter pub add welloo_sdk

Ou dans votre pubspec.yaml :

dependencies:
  welloo_sdk: ^0.0.51

2. Initialisation (OBLIGATOIRE) #

Le SDK doit être initialisé dans main() avant le lancement de l'app :

import 'package:flutter/material.dart';
import 'package:welloo_sdk/welloo_sdk.dart';
import 'package:welloo_sdk/src/shared/services/logger_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Configurer le logger (optionnel)
  LoggerService().configure(
    minLevel: LogLevel.debug,
    enabledInProduction: true,
  );

  // Initialize Welloo SDK
  await WellooSdk.init();

  runApp(const MyApp());
}

👩‍💻 Utilisation #

Exemple Basique #

import 'package:welloo_sdk/welloo_sdk.dart';

// Lancer un dépôt
Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => WellooDeposit(
      packageName: 'com.example.myapp',
      accessToken: "YOUR_ACCESS_TOKEN",
      refreshToken: "YOUR_REFRESH_TOKEN",
      waitResponse: (response) {
        print('📦 Réponse: $response');
        // response contient:
        // - status: "pending" | "SUCCEEDED" | "FAILED"
        // - reference_transaction: "TXN_DEP_..."
        // - description: "..."
      },
      onError: (error) {
        print('❌ Erreur: $error');
      }
    ),
  ),
);

Avec Logs Détaillés #

Le SDK affiche automatiquement des logs structurés dans la console :

============================================================
🚀 WELLOO SDK - NOUVEAU SYSTÈME DE VÉRIFICATION
============================================================
Configuration: Wave Config (2s, 150x)
Stratégie: hybrid
Polling: 150x @ 2s
Deeplink: Activé
Circuit Breaker: Activé
Retry Policy: Max 3 tentatives
============================================================

📦 INITIATION DÉPÔT
============================================================

✅ RÉPONSE TRANSACTION:
Status: SUCCEEDED
Reference: TXN_DEP_20251205_ABC123

Vérification Manuelle #

Vous pouvez vérifier manuellement le statut d'une transaction :

final sdk = WellooSdk();

final result = await sdk.checkDepositStatus(
  reference: 'TXN_DEP_20251204_ABC123',
);

if (result.isSuccess && result.data != null) {
  final transaction = result.data!;
  print('Status: ${transaction.status}');
} else {
  print('Error: ${result.error}');
}

⚙️ Configuration Deep Links (Optionnel) #

Pour la stratégie Hybrid ou Deeplink, configurez les deep links :

Android - android/app/src/main/AndroidManifest.xml #

<activity android:name=".MainActivity" android:launchMode="singleTop">
    <!-- Deep link avec scheme personnalisé (RECOMMANDÉ) -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        <data android:scheme="yourapp" android:host="payment"/>
    </intent-filter>
</activity>

Note : Remplacez yourapp par le nom unique de votre application.

iOS - ios/Runner/Info.plist #

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
    </dict>
</array>
<key>FlutterDeepLinkingEnabled</key>
<true/>

Configuration Backend - Simplifiée #

Nouveau format direct : Le SDK envoie maintenant directement les deep links finaux :

success_url: "yourapp://?status=success&reference={{reference}}"
error_url: "yourapp://?status=error&reference={{reference}}"

✅ Avantages :

• Pas de path = Pas d'erreur 404
• Pas de redirection backend = Plus simple
• Retour direct = L'app s'ouvre sur la vue du SDK
• Callbacks immédiats = waitResponse et onError déclenchés automatiquement

🎨 Aperçu de l'Interface #

Le SDK offre un flow en 4 étapes avec une UX moderne :

1. Sélection de l'opérateur - Logos clairs avec animations
2. Numéro de téléphone - Sélecteur de pays intégré (+225, +221, etc.)
3. Montant - Calcul automatique des frais en temps réel
4. Résumé - Bouton swipe-to-confirm pour validation sécurisée

Dépôt

🛡️ Fonctionnalités Avancées #

Circuit Breaker #

Protège votre app contre les cascades d'erreurs en interrompant temporairement les requêtes après plusieurs échecs consécutifs.

Retry Policy #

Retry automatique avec exponential backoff pour les erreurs réseau temporaires.

Métriques en Temps Réel #

• ✅ Taux de succès/erreur
• ⏱️ Temps de réponse moyen
• 📞 Nombre d'appels API
• 🔗 Taux de réception des deeplinks
• ⚡ Déclenchements du circuit breaker

Logs Structurés #

4 niveaux de logs (DEBUG, INFO, WARNING, ERROR) pour un debugging facile avec export JSON/Text.

📚 Documentation Complète #

• 📖 Guide d'intégration détaillé - Nouveau système de vérification
• 🔄 Documentation Polling - Système de polling automatique
• 🔗 Configuration Deep Links - Guide des deeplinks
• 💻 Exemple complet - Avec sélecteur de configuration

🔧 Architecture #

Le nouveau système utilise :

• Strategy Pattern pour les 3 stratégies de vérification
• Sealed Classes pour type-safety et pattern matching
• Circuit Breaker Pattern pour la résilience
• Observer Pattern pour le lifecycle management
• Repository Pattern pour l'abstraction API
• Dependency Injection pour la testabilité

📊 Pays Supportés #

• 🇨🇮 Côte d'Ivoire (+225)
• 🇸🇳 Sénégal (+221)
• 🇲🇱 Mali (+223)
• 🇧🇫 Burkina Faso (+226)
• 🇧🇯 Bénin (+229)
• 🇹🇬 Togo (+228)
• 🇳🇪 Niger (+227)
• 🇬🇳 Guinée (+224)
• 🇫🇷 France (+33)

🆘 Support #

Pour toute question ou problème :

• 📝 GitHub Issues
• 📧 Email: support@finapay.net
• 🌐 Documentation: https://finapay.net

📝 Changelog #

Version 0.0.50 #

• ✨ Nouveau système de vérification avec 3 stratégies
• 🎯 8 configurations prédéfinies (Wave, Wello, Production, etc.)
• 🛡️ Circuit Breaker et Retry Policy
• 📊 Métriques détaillées et 12 types d'events
• 🔍 Logs structurés avec 4 niveaux
• ✅ Type-safe avec sealed classes
• 🔄 Amélioration de la résilience avec stratégie Hybrid

Développé avec ❤️ par l'équipe Finapay