welloo_sdk 0.0.118

Package de transaction Welloo

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, configurer et exécuter des paiements de manière sécurisée.

---

✨ Fonctionnalités

• 💳 Initialisation sécurisé du SDK
• 🔗 Gestion sécurisée des transactions (dépôt, transfert)
• 📦 Intégration rapide dans n’importe quelle app Flutter
• 🧩 Compatible Android & iOS

🔗 Les Etapes

L'utilisation du package est la plus simple possible, dans son utilisation, il s'agit d'invoquer celui-ci avec :

• Les paramétres d'initialisation du guichet
• Le callback d'attente du retour de paiement
• Le callback d'écoute d'erreur d'exécution

🛠 Installation

Ajoutez le package à votre fichier pubspec.yaml :

dependencies:
  welloo_sdk: ^0.0.117
  # Recommandé pour écouter les retours de paiement :
  app_links: ^7.0.0

Pour fonctionner, le sdk doit impérativement recevoir des données telles que :

• ACCESS_TOKEN | L'access Token | Chaine de caractère | Obligatoire
• RESFRESH_TOKEN | Le refresh Token | Chaine de caractère | Obligatoire
• SUCCESS_URL | lien en cas de succès | URL | Obligatoire
• ERROR_URL | lien en cas de succès | URL | Obligatoire

⚙️ Configuration (Obligatoire)

Pour garantir que l'application se réouvre automatiquement après un paiement (via les URLs de succès ou d'erreur), une configuration native est requise.:

• Android (AndroidManifest.xml)
  Ouvrez android/app/src/main/AndroidManifest.xml. Vous devez ajouter launchMode="singleTask" à votre activité principale et configurer l'intent-filter pour intercepter les liens HTTPS.

<activity
    android:name=".MainActivity"
    android:launchMode="singleTask" android:theme="@style/LaunchTheme"
    ...>

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="https" />
        <data android:host="domain_name" />
        <data android:pathPrefix="/OP_DEP_" />
    </intent-filter>
</activity>

• iOS (Runner.entitlements) Pour iOS, vous devez activer la capability Associated Domains. Ajoutez ceci dans votre fichier ios/Runner/Runner.entitlements ou via Xcode :

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:domain_name</string>
</array>

• Côté Serveur (Web)
  Pour que l'association fonctionne sans popup, les fichiers de vérification doivent être présents sur le domaine API :
  . Android : https://domain_name/.well-known/assetlinks.json (Doit contenir le SHA-256 de votre application).

. iOS : https://domain_name/.well-known/apple-app-site-association (Doit contenir le TeamID + BundleID).

// Pour generer le SHA-256
cd android && ./gradlew signingReport 

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "package_name",
      "sha256_cert_fingerprints": [
    "Value Key SHA-256" 
      ]
    }
  }
]

-La Fonction initDeepLinks
Copiez cette méthode dans votre State (par exemple _DemoWelloState) :

Future<void> initDeepLinks() async {
    _linkSubscription = AppLinks().uriLinkStream.listen((uri) {
      debugPrint('🔗 DeepLink reçu : $uri');

      // CAS 1 : Retour de Paiement Finapay  
      if (uri.host == 'domain_name') {
                
      }
      // CAS 2 : Autres liens
      else {
        if (uri.fragment.isNotEmpty) {
          navigatorKey.currentState?.pushNamed(uri.fragment);
        }
      }
    });
  }

📥 Les callbacks

Les callbacks onSuccess et onError reçoivent tous deux le même objet WellooResult (onError ne renvoie pas une exception) :

enum WellooStatus { success, failure, pending }

class WellooResult {
  final WellooStatus status;
  final String description;
  final String? transactionId; // référence de la transaction, si disponible
}

Quel callback reçoit quel statut :

Statut	Callback	Quand
success	onSuccess	Opération confirmée.
pending	onSuccess	Dépôt Wave en attente de validation dans l'app Wave (asynchrone).
failure	onError	Échec (validation, solde, service externe…).

⚠️ onSuccess peut recevoir success OU pending. Teste toujours result.status avant de considérer l'opération comme terminée — un pending n'est confirmé qu'une fois validé côté Wave. Le statut pending ne concerne aujourd'hui que WellooDeposit.

ℹ️ transactionId est renseigné pour success et pending lorsque le backend fournit une référence ; il peut être null (ex. échec, ou backend sans réf).

1 — Effectuer un dépôt

WellooDeposit(
  accessToken: "ACCESS_TOKEN",   // jeton d'accès de l'utilisateur authentifié
  refreshToken: "REFRESH_TOKEN", // jeton de rafraîchissement associé
  returnUrl: "https://domain_name/OP_DEP_...", // optionnel (deep link de retour)
  onSuccess: (result) {
    switch (result.status) {
      case WellooStatus.success:
        print('Dépôt confirmé — réf: ${result.transactionId}');
        break;
      case WellooStatus.pending:
        print('Dépôt en attente de validation Wave — réf: ${result.transactionId}');
        break;
      case WellooStatus.failure:
        break; // n'arrive pas ici : voir onError
    }
  },
  onError: (result) {
    print('Échec du dépôt : ${result.description}');
  },
)

2 — Effectuer un transfert

WellooTransfer(
  accessToken: "ACCESS_TOKEN",
  refreshToken: "REFRESH_TOKEN",
  onSuccess: (result) {
    print('Transfert confirmé — réf: ${result.transactionId}');
  },
  onError: (result) {
    print('Échec du transfert : ${result.description}');
  },
)

3 — Scanner QR Code

WellooScanQr(
  accessToken: "ACCESS_TOKEN",
  refreshToken: "REFRESH_TOKEN",
  onSuccess: (result) {
    print('Paiement marchand confirmé — réf: ${result.transactionId}');
  },
  onError: (result) {
    print('Échec du paiement : ${result.description}');
  },
)

📱 Aperçu

Dépôt

🛠 Installation

Exécutez cette commande :

Avec Flutter :

flutter pub add welloo_sdk

ou Ajoutez le package à votre fichier pubspec.yaml :

dependencies:
  wello_sdk_mobile: ^0.0.117