Documentation de l'API MVola

Cette documentation décrit l'intégration des services de paiement mobile MVola dans vos applications. MVola est un service de paiement mobile opéré par Telma Madagascar permettant aux entreprises de recevoir des paiements électroniques.

1. Portail développeur MVola
2. Configuration de l'API
3. API d'authentification
4. API de paiement marchand
5. Codes d'erreur
6. Environnement de test
7. Bonnes pratiques

1. Accédez au portail MVola Developer et cliquez sur "Connectez-vous".
2. Pour créer un compte:
   • Saisissez une adresse email valide
   • Remplissez vos informations personnelles
   • Acceptez les conditions d'utilisation
   • Confirmez via le lien envoyé par email

1. Une fois connecté, déclarez votre application.
2. Fournissez des informations précises et complètes.
3. Attendez la validation par l'équipe MVola.

1. Après validation de votre application, accédez à l'onglet "Subscriptions".
2. Abonnez-vous aux API MVola pour recevoir vos clés d'accès.
3. Un email de confirmation vous sera envoyé.

1. Dans la section "SUBSCRIPTIONS", cliquez sur "SANDBOX KEYS".
2. Décochez tous les "grant types" sauf "Client Credentials".
3. Vous obtiendrez votre Consumer Key et Consumer Secret.

Pour passer en production:

1. Cliquez sur "GO LIVE" dans le portail développeur.
2. Suivez les étapes de validation.
3. Utilisez les clés de production une fois approuvées.

curl --location --request POST 'https://devapi.mvola.mg/token' \
--header 'Authorization: Basic Base64(consumer-key:consumer-secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=EXT_INT_MVOLA_SCOPE'

{
  "access_token": "<ACCESS_TOKEN>",
  "scope": "EXT_INT_MVOLA_SCOPE",
  "token_type": "Bearer",
  "expires_in": 3600
}

Notes:

• Le token expire après 3600 secondes (1 heure)
• L'encodage Base64 utilise le format consumer-key:consumer-secret avec un deux-points (:)

En-têtes additionnels:

• X-Callback-URL: URL pour notifications (optionnel)

Corps de la requête:

{  
  "amount": "10000",  
  "currency": "Ar",  
  "descriptionText": "Paiement Marchand",  
  "requestDate": "2023-10-05T14:30:00.000Z",  
  "debitParty": [{"key": "msisdn", "value": "0340017983"}],  
  "creditParty": [{"key": "msisdn", "value": "0340017984"}],  
  "metadata": [  
    {"key": "partnerName", "value": "MonEntreprise"},  
    {"key": "fc", "value": "USD"},  
    {"key": "amountFc", "value": "10"}  
  ]  
}

Réponse (succès):

{  
  "status": "pending",  
  "serverCorrelationId": "421a22a2-effd-42bc-9452-f4939a3d5cdf",  
  "notificationMethod": "callback"  
}

Requête:

GET /mvola/mm/transactions/type/merchantpay/1.0.0/{transID}

Réponse (succès):

{  
  "amount": "10000",  
  "currency": "Ar",  
  "transactionReference": "123456",  
  "transactionStatus": "completed",  
  "debitParty": [{"key": "msisdn", "value": "0340017983"}],  
  "creditParty": [{"key": "msisdn", "value": "0340017984"}]  
}

Requête:

GET /mvola/mm/transactions/type/merchantpay/1.0.0/status/{serverCorrelationId}

Réponse (succès):

{  
  "status": "completed",  
  "serverCorrelationId": "421a22a2-effd-42bc-9452-f4939a3d5cdf",  
  "notificationMethod": "polling",  
  "objectReference": "123456"  
}

{  
  "ErrorCategory": "Transaction",  
  "ErrorCode": "5001",  
  "ErrorDescription": "Solde insuffisant",  
  "ErrorDateTime": "2023-10-05T12:34:56Z",  
  "ErrorParameters": {"param": "value"}  
}

Erreur d'authentification:

{  
  "fault": {  
    "code": 900901,  
    "message": "Invalid Credentials",  
    "description": "Invalid Credentials. Make sure you have given the correct access token."  
  }  
}

Pour l'environnement Sandbox, utilisez uniquement:

• 0343500003
• 0343500004

1. Dans le portail développeur MVola, section "TRY OUT":

   • Sélectionnez votre application
   • Générez une clé de test

2. Exécutez vos requêtes de test

3. Approuvez les transactions en attente via "Transaction Approvals"

1. Gestion des tokens

   • Stockez le token de manière sécurisée
   • Intégrez un mécanisme de rafraîchissement automatique (avant expiration)

2. Validation des paramètres

   • Vérifiez les numéros de téléphone (format valide)
   • Évitez les caractères spéciaux dans les descriptions

3. Dates et formats

   • Format des dates: ISO 8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
   • Utilisez UTC pour éviter les problèmes de fuseau horaire

4. Suivi des transactions

   • Conservez le serverCorrelationId pour suivre les statuts
   • Implémentez un système de webhook pour les notifications

5. Sécurité

   • Utilisez HTTPS pour toutes les communications
   • Ne stockez jamais les credentials en clair
   • Implémentez une rotation régulière des clés d'API

Pour toute question technique, contactez MVola via le portail développeur ou à l'adresse support-api@mvola.mg.