lengopay_flutter 1.3.0

Package Flutter pour l'intégration de l'API de paiement Lengo Pay. Support des paiements classiques (v1) et Cash In direct (v2) vers Orange Money et MTN Mobile Money Guinée.

lengopay_flutter

lengopay_flutter est un package Flutter permettant d'intégrer facilement Lengo Pay dans vos applications. Il simplifie la génération d'URL de paiement et la gestion des notifications de callback.

Fonctionnalités

• Génération d'URL de paiement (API v1) : Créez une URL pour chaque transaction avec un montant et une devise spécifiques.

• Paiements Cash In (API v2) : Initiez des transactions de paiement direct vers des comptes mobiles.

• Gestion des callbacks : Recevez les notifications sur le statut des paiements.

• Support multi-devises : Accepte plusieurs devises comme GNF, XOF, USD, etc.

• Vérification du statut de paiement : Vérifiez les statuts de vos transactions.

• Types de comptes supportés : Orange Money Guinée (lp-om-gn), MTN Mobile Money Guinée (lp-momo-gn).

Installation

Ajoutez lengopay_flutter comme dépendance dans votre projet Flutter en exécutant la commande suivante :

flutter pub add lengopay_flutter

Ou ajoutez-le manuellement dans le fichier pubspec.yaml :

dependencies:
  lengopay_flutter: ^1.2.0

Puis, installez les dépendances avec :

flutter pub get

Utilisation de base

Importation

Commencez par importer le package dans votre projet :

import 'package:lengopay_flutter/lengopay_flutter.dart';

Exemple de création d'une URL de paiement (API v1)

 // Initialisation du service Lengopay avec votre clé de licence
    final lengopay = LengopayFlutter(
      // Initialisation du service Lengopay avec votre clé de licence
      licenseKey: 'VOTRE_LICENSE_KEY',

      // Par defaut le package utilise l'url de test: 'https://sandbox.lengopay.com/api/v1'
      // vous pouvez utiliser l'URL de production
      // ici 👇👇
      // baseUrl:
    );

    try {
      // Initier un paiement
      final paymentResponse = await lengopay.initiatePayment(
        PaymentRequest(
          websiteId: 'VOTRE_WEBSITE_ID',
          // L'identifiant unique de votre site
          amount: 1500,
          // Montant du paiement
          currency: 'GNF',
          // Devise utilisée "GNF", "XOF" ou "USD"
          returnUrl: '',
          // (Optionnel) URL de retour 
          callbackUrl: '',
          // (Optionnel) URL de callback
        ),
      );
    // Vous pouvez remplacer log par print selon vos bésoins.
      log('Status: ${paymentResponse.status}');
      log('Pay ID: ${paymentResponse.payId}');
      log('URL de paiement: ${paymentResponse.paymentUrl}');
    } on LengopayException catch (e) {
      log('Erreur Lengopay: ${e.toString()}');
    } catch (e) {
      log('Erreur inattendue: ${e.toString()}');
    }

Exemple de paiement Cash In (API v2)

// Initialisation du service Lengopay
final lengopay = LengopayFlutter(
  licenseKey: 'VOTRE_LICENSE_KEY',
  // Par défaut utilise l'environnement sandbox
  // Pour la production, spécifiez les URLs de production
  // baseUrlV2: 'https://portal.lengopay.com/api/v2',
);

try {
  // Initier un paiement Cash In
  final cashInResponse = await lengopay.initiateCashIn(
    CashInRequest(
      amount: '1000', // Montant en chaîne
      currency: 'GNF',
      websiteId: 'VOTRE_WEBSITE_ID',
      typeAccount: 'lp-om-gn', // Orange Money Guinée
      account: '620124578', // Numéro de téléphone
      callbackUrl: 'https://votre-site.com/callback', // Optionnel
    ),
  );

  print('Status: ${cashInResponse.status}');
  print('Pay ID: ${cashInResponse.payId}');
  print('Message: ${cashInResponse.message}');

} on LengopayException catch (e) {
  print('Erreur Lengopay: ${e.toString()}');
  print('Code d\'erreur: ${e.statusCode}');
} catch (e) {
  print('Erreur inattendue: ${e.toString()}');
}

Gestion des erreurs

Vous pouvez intercepter les exceptions en utilisant un bloc try-catch pour traiter les éventuelles erreurs comme :

• La demande était mal formée ou il manquait les paramètres requis (400 Bad Request)

• La clé API fournie était invalide ou manquante (401 Unauthorized)

• La ressource demandée n'a pas été trouvée (404 Not Found)

• Une erreur inattendue s'est produite sur le serveur. (500 Internal Server Error)

Gestion des notifications de callback

Callback pour les paiements classiques (API v1)

Lorsque vous fournissez une callbackUrl dans la requête, le serveur de Lengopay enverra une notification HTTP POST à cette URL une fois le paiement traité.

{
"pay_id": "123456789",
"status": "SUCCESS",
"amount": 1500,
"message": "Transaction Successful",
"client": "123456789"
}

Callback pour les paiements Cash In (API v2)

Pour les paiements Cash In, le callback contient des informations spécifiques :

{
"pay_id": "RzFmb1JvVWwxWFJQaXBCaXFWM",
"status": "SUCCESS",
"amount": 1000,
"message": "Transaction Successful",
"account": "620124578"
}

Gestion du callback côté serveur

⚠️ Important : Le SDK ne gère pas les callbacks automatiquement. Vous devez implémenter un endpoint sur votre serveur.

// Exemple d'endpoint de callback (implémentation côté serveur requise)
// Le modèle CashInCallback vous aide à parser les données reçues

void exempleTraitementCallback(Map<String, dynamic> callbackData) {
  final callback = CashInCallback.fromJson(callbackData);
  
  switch (callback.status) {
    case 'SUCCESS':
      // Transaction réussie - mettre à jour votre base de données
      print('Paiement réussi: ${callback.payId}');
      break;
    case 'FAILED':
      // Transaction échouée - gérer l'erreur
      print('Paiement échoué: ${callback.message}');
      break;
  }
  
  // IMPORTANT: Votre serveur doit répondre avec un statut 200
}

Note : Assurez-vous que votre serveur répond avec un statut HTTP 200 pour confirmer la réception du callback.

Types de comptes supportés (Cash In)

Le système Cash In supporte actuellement les types de comptes suivants :

• lp-om-gn : Orange Money Guinée
• lp-momo-gn : MTN Mobile Money Guinée

Exemple d'utilisation par type de compte

// Orange Money Guinée
final orangeMoneyRequest = CashInRequest(
  amount: '5000',
  currency: 'GNF',
  websiteId: 'VOTRE_WEBSITE_ID',
  typeAccount: 'lp-om-gn',
  account: '620123456', // Numéro Orange Money
);

// MTN Mobile Money Guinée
final mtnRequest = CashInRequest(
  amount: '3000',
  currency: 'GNF',
  websiteId: 'VOTRE_WEBSITE_ID',
  typeAccount: 'lp-momo-gn',
  account: '655123456', // Numéro MTN
);

Configuration requise

• Flutter SDK : >=3.27.0

• Dart SDK : >=3.7.0

• Lengo Pay Sandbox ou clé de production

Contribution

Les contributions sont les bienvenues ! Suivez ces étapes pour contribuer :

1. git clone https://github.com/4n-d3er-git/lengopay_flutter.git

2. git checkout -b ma-fonctionnalite

3. Effectuez vos modifications et ajoutez des tests.

4. Soumettez une Pull Request.

Roadmap

• Historique des transactions

• Documentation en plusieurs langues

Licence

Ce package est sous licence MIT. Consultez le fichier LICENSE pour plus d'informations.

Liens utiles

• Documentation officielle de Lengo Pay

• Flutter Documentation

• Dart API

Si vous avez des questions ou des suggestions, n'hésitez pas à ouvrir une issue sur GitHub.

Made with ❤️ by Anderson GOUMOU