Skip to content

MVola API Library

Bienvenue dans la documentation de la bibliothèque MVola API.

Introduction

MVola API Library est une bibliothèque Python robuste conçue pour faciliter l'intégration des services de paiement mobile MVola dans vos applications. Cette bibliothèque vous permet d'interagir avec les API de MVola de manière simple et intuitive, en gérant automatiquement l'authentification, la validation des paramètres, et le traitement des erreurs.

Documentation complète de l'API

La documentation complète de l'API MVola est disponible ici.

Cette documentation détaillée contient: - Configuration du portail développeur - Endpoints d'API et paramètres - Structures de requêtes et réponses - Codes d'erreur - Bonnes pratiques - Environnement de test

Installation

pip install mvola-api-lib

Fonctionnalités principales

  • ✅ Gestion des jetons d'authentification avec scope EXT_INT_MVOLA_SCOPE
  • ✅ Paiements marchands (initiation, statut, détails)
  • ✅ Support des environnements Sandbox et Production
  • ✅ Validation des paramètres
  • ✅ Gestion robuste des erreurs
  • ✅ Journalisation intégrée
  • ✅ Support des variables d'environnement pour une meilleure sécurité

Utilisation rapide

Pour un démarrage rapide, consultez les exemples dans la section Guide d'utilisation.

Formats de documentation

La documentation est disponible en plusieurs formats:

Support

Pour toute question technique, contactez: - Le support MVola via le portail développeur - Créez une issue sur GitHub

Fonctionnalités

  • ✅ API simple et intuitive pour l'intégration des paiements MVola
  • ✅ Gestion automatique des tokens d'authentification
  • ✅ Support complet des opérations de paiement marchand
  • ✅ Gestion complète des erreurs et validation des paramètres
  • ✅ Support de journalisation
  • ✅ Compatible avec les environnements sandbox et production

Démarrage rapide

"""
MVola API Library - Guide de démarrage rapide

Ce script démontre comment utiliser la bibliothèque MVola API pour:
1. Initialiser un client MVola
2. Générer un token d'authentification
3. Initier un paiement
4. Suivre l'état d'une transaction
5. Obtenir les détails d'une transaction

Pour plus d'informations, consultez la documentation complète: 
https://github.com/Niainarisoa01/Mvola_API_Lib
"""

from mvola_api import MVolaClient
import time
from dotenv import load_dotenv

# ======================================================
# 1. INITIALISATION DU CLIENT
# ======================================================

# Méthode 1: Utilisation des variables d'environnement (recommandée)
# Chargez le fichier .env contenant vos credentials
load_dotenv()

# Création du client à partir des variables d'environnement
client = MVolaClient.from_env()

# Méthode 2: Initialisation directe
# client = MVolaClient(
#    consumer_key="your_consumer_key",  # Obtenu du portail développeur MVola
#    consumer_secret="your_consumer_secret",  # Obtenu du portail développeur MVola
#    partner_name="nom de votre entreprise",  # Nom de votre application/entreprise
#    partner_msisdn="0343500004",  # En sandbox, utilisez uniquement 0343500004
#    sandbox=True  # True pour sandbox, False pour production
# )

# ======================================================
# 2. AUTHENTIFICATION - GÉNÉRATION DE TOKEN
# ======================================================
# Un token est valide pendant 1 heure
# La bibliothèque gère automatiquement le renouvellement
token_data = client.generate_token()
print(f"Token généré: {token_data['access_token'][:10]}...")  # Ne jamais afficher le token complet

# ======================================================
# 3. INITIER UN PAIEMENT
# ======================================================
# REMARQUE IMPORTANTE: Dans l'environnement sandbox MVola:
# - Utilisez uniquement 0343500003 et 0343500004
result = client.initiate_payment(
    amount=1000,  # Montant en Ariary (minimum 100)
    currency="Ar",  # Devise (Ariary)
    debit_msisdn="0343500003",  # Numéro du débiteur (celui qui paie)
    credit_msisdn="0343500004",  # Numéro du créditeur (celui qui reçoit)
    description="Test Transaction",  # Description de la transaction (max 50 caractères)
    callback_url="https://example.com/callback"  # URL où MVola enverra des notifications (recommandé)
)

# ======================================================
# 4. SUIVI DE LA TRANSACTION
# ======================================================
# L'ID de corrélation est nécessaire pour suivre l'état de la transaction
server_correlation_id = result['response']['serverCorrelationId']
print(f"Transaction initiée avec l'ID de corrélation: {server_correlation_id}")

# 4.1 Vérification initiale du statut
print("\n=== Test de get_transaction_status (statut initial) ===")
status_result = client.get_transaction_status(server_correlation_id)
print(f"Statut de la transaction: {status_result['response']['status']}")

# 4.2 Suivi automatique du statut - boucle de vérification
# La transaction peut prendre du temps pour être traitée
print("\n=== Boucle de vérification du statut ===")
max_attempts = 10  # Maximum d'essais
waiting_time = 3   # Secondes entre chaque vérification
current_attempt = 1
transaction_status = status_result['response']['status']

# La boucle continue jusqu'à ce que le statut change ou le nombre max de tentatives soit atteint
while transaction_status == "pending" and current_attempt <= max_attempts:
    print(f"Tentative {current_attempt}/{max_attempts} - Statut actuel: {transaction_status}")
    print(f"Attente de {waiting_time} secondes avant nouvelle vérification...")
    time.sleep(waiting_time)

    # Vérification périodique du statut
    status_result = client.get_transaction_status(server_correlation_id)
    transaction_status = status_result['response']['status']
    current_attempt += 1

print(f"\nStatut final après {current_attempt-1} vérifications: {transaction_status}")

# 4.3 Interprétation du statut final
# Les statuts possibles sont: pending, completed, failed
if transaction_status == "pending":
    print("En attente d'approbation")
    print("La transaction est toujours en attente après toutes les tentatives de vérification.")
    print("Vous devrez peut-être l'approuver manuellement dans le portail développeur MVola.")
elif transaction_status == "completed":
    print("La transaction est Réussie")
    print("Le paiement a été approuvé et traité avec succès.")
elif transaction_status == "failed":
    print("Échec de transaction")
    print("Le paiement a été rejeté ou a échoué pendant le traitement.")
else:
    print(f"Statut final: {transaction_status}")
    print("Statut non reconnu ou en cours de traitement.")

# ======================================================
# 5. DÉTAILS DE LA TRANSACTION
# ======================================================
# Obtient des informations complètes sur la transaction
print("\n=== Test de get_transaction_details ===")

# L'objectReference est l'ID unique de la transaction, nécessaire pour obtenir les détails
transaction_id = status_result['response'].get('objectReference')

if transaction_id and transaction_id.strip():
    print(f"ID de transaction obtenu: {transaction_id}")

    try:
        # Récupération des détails complets
        details_result = client.get_transaction_details(transaction_id)
        print(f"Détails de la transaction: {details_result}")

        # Accès aux détails spécifiques
        amount = details_result.get('amount')
        currency = details_result.get('currency')
        transaction_status = details_result.get('transactionStatus')

        print(f"Montant: {amount} {currency}")
        print(f"Statut: {transaction_status}")
    except Exception as e:
        print(f"Erreur lors de la récupération des détails: {str(e)}")
else:
    print("L'objectReference est vide ou non disponible")

    # Explication selon le statut actuel
    if transaction_status == "pending":
        print("La transaction est encore en attente d'approbation")
        print("\nNote: Dans l'environnement sandbox, les transactions restent souvent en état 'pending'")
        print("Pour les tests, vous devriez approuver manuellement la transaction dans le portail développeur MVola")
    elif transaction_status == "completed":
        print("La transaction est complétée mais l'ID de référence n'est pas disponible")
        print("C'est inhabituel - vérifiez dans le portail développeur MVola")
    elif transaction_status == "failed":
        print("La transaction a échoué. Aucun ID de référence n'est généré pour les transactions échouées")
        print("Vérifiez les détails de l'échec dans le portail développeur MVola")
    else:
        print(f"La transaction a un statut inhabituel: {transaction_status}")
        print("Vérifiez le portail développeur MVola pour plus de détails")

# ======================================================
# REMARQUES SUPPLÉMENTAIRES
# ======================================================
# 1. En environnement sandbox, vous devrez approuver manuellement les transactions
#    dans le portail développeur MVola pour qu'elles passent à l'état "completed"
# 
# 2. Cette bibliothèque gère automatiquement:
#    - Le renouvellement du token d'authentification
#    - Le formatage des requêtes selon les attentes de l'API MVola
#    - La gestion des erreurs et exceptions
#
# 3. Pour l'environnement de production:
#    - Utilisez l'URL "https://api.mvola.mg" lors de l'initialisation du client
#    - Utilisez vos véritables numéros de téléphone MVola
#    - Assurez-vous d'avoir les autorisations nécessaires

Tests en sandbox

Pour les tests en sandbox, utilisez les numéros de téléphone de test suivants : - 0343500003 - 0343500004

Endpoints d'API

La bibliothèque prend en charge les endpoints suivants :

  1. Authentification : POST /token (avec scope EXT_INT_MVOLA_SCOPE)
  2. Paiement marchand : POST /mvola/mm/transactions/type/merchantpay/1.0.0/
  3. Détails de transaction : GET /mvola/mm/transactions/type/merchantpay/1.0.0/{{transID}}
  4. Statut de transaction : GET /mvola/mm/transactions/type/merchantpay/1.0.0/status/{{serverCorrelationId}}

Structure de la documentation

Cette documentation a été structurée selon le framework Diátaxis, qui organise l'information en quatre sections distinctes :

  1. Guides d'utilisation - Orientés apprentissage, pour vous aider à comprendre les concepts
  2. Exemples - Orientés problèmes, pour résoudre des cas d'utilisation spécifiques
  3. Référence API - Orientés information, documentation technique détaillée
  4. Explication - Orientés compréhension, pour expliquer les choix et l'architecture

Contribution

Les contributions sont les bienvenues ! Consultez notre guide de contribution pour plus d'informations.

Licence

Ce projet est sous licence MIT.