Guide Complet : Intégration API Orange Money et Wave en PHP

1Pourquoi intégrer Orange Money et Wave dans votre application

Orange Money et Wave dominent le marché du paiement mobile en Afrique francophone. Orange Money compte plus de 30 millions d'utilisateurs actifs en Côte d'Ivoire, au Cameroun, au Sénégal et au Mali. Wave, avec ses frais réduits à seulement 1%, a révolutionné le marché et capte une part croissante des transactions. Pour un e-commerçant, ne pas proposer ces moyens de paiement signifie perdre la majorité de vos clients potentiels. L'intégration API permet d'automatiser complètement le processus de paiement, de la collecte au remboursement, tout en offrant une expérience utilisateur fluide.

2Prérequis pour l'intégration API

Avant de commencer l'intégration, assurez-vous d'avoir :

1. Un compte marchand ElyonPay (inscription gratuite sur elyonpay.com/register)
2. Vos clés API (API Key et Secret disponibles dans votre dashboard)
3. PHP 7.4 ou supérieur installé sur votre serveur
4. Composer pour la gestion des dépendances
5. Un certificat SSL valide (obligatoire pour recevoir les webhooks de confirmation)

Une fois votre compte créé, accédez à votre dashboard marchand pour récupérer vos clés API en mode sandbox — vous pourrez tester sans frais réels.

3Installation du SDK ElyonPay PHP

L'installation se fait simplement via Composer :

composer require elyonpay/elyonpay-php

Ensuite, initialisez le client dans votre code :

$client = new ElyonPay\Client('VOTRE_API_KEY');

Pour les tests, le SDK utilise automatiquement l'environnement sandbox. En production, ajoutez le paramètre :

$client = new ElyonPay\Client('VOTRE_API_KEY', [
    'environment' => 'production'
]);

Le SDK gère automatiquement l'authentification, les retries en cas d'erreur réseau, et la sérialisation des réponses.

4Votre première requête - Vérification de connexion

Avant d'initier des paiements, vérifiez que votre intégration fonctionne correctement :

$balance = $client->account->balance();
echo 'Solde disponible: ' . $balance->available . ' ' . $balance->currency;

Si vous recevez une réponse valide avec votre solde (0 FCFA en sandbox), votre configuration est correcte et vous pouvez passer à l'étape suivante.

5Initier un paiement Orange Money - Code complet

Pour initier un paiement Orange Money, créez une requête avec les paramètres requis :

$payment = $client->payments->create([
    'amount'       => 5000,
    'currency'     => 'XOF',
    'provider'     => 'orange_money',
    'phone'        => '+2250701234567',
    'description'  => 'Commande #12345',
    'callback_url' => 'https://votresite.com/webhook'
]);

Le client recevra immédiatement une notification push sur son téléphone pour confirmer le paiement avec son code PIN. Une fois confirmé, votre webhook recevra la notification de succès.

6Initier un paiement Wave - Code complet

L'intégration Wave est similaire mais utilise le provider wave. Wave génère un lien de paiement que vous pouvez rediriger vers le client ou afficher en QR code :

$payment = $client->payments->create([
    'amount'      => 5000,
    'currency'    => 'XOF',
    'provider'    => 'wave',
    'phone'       => '+2250701234567',
    'description' => 'Commande #12345'
]);

La réponse inclut un payment_url que vous pouvez utiliser pour rediriger le client vers l'application Wave. Le processus est particulièrement adapté aux paiements en personne via QR code.

7Implémentation des webhooks et callbacks

Les webhooks sont essentiels pour recevoir les confirmations de paiement en temps réel. Configurez votre URL de webhook dans le dashboard ElyonPay sous Paramètres > Webhooks. Votre endpoint doit :

1. Vérifier la signature du webhook avec le header X-ElyonPay-Signature
2. Traiter les événements payment.success, payment.failed et payment.refunded
3. Retourner un code HTTP 200 pour confirmer la réception

8Gestion des erreurs et cas limites

Les paiements Mobile Money peuvent échouer pour diverses raisons :

• Solde insuffisant (INSUFFICIENT_BALANCE)
• Numéro invalide (INVALID_PHONE)
• Timeout réseau (TIMEOUT)
• Refus utilisateur (USER_CANCELLED)

Implémentez une gestion d'erreur robuste avec des messages utilisateur clairs en français. Prévoyez un mécanisme de retry pour les erreurs temporaires (maximum 3 tentatives avec délai exponentiel). Stockez l'état de chaque transaction dans votre base de données pour faciliter la réconciliation.

9Mode Sandbox vs Production

Le mode sandbox permet de tester votre intégration sans frais réels. Utilisez les numéros de test fournis dans la documentation :

Avant de passer en production, vérifiez :

1. Tous les cas d'erreur sont gérés
2. Les webhooks fonctionnent correctement
3. Les logs sont adéquats pour le debugging
4. La réconciliation est automatisée

Contactez le support ElyonPay pour activer votre compte production.

10Bonnes pratiques de sécurité

Sécurisez votre intégration en suivant ces règles :

1. Ne committez jamais vos clés API dans votre code source - utilisez des variables d'environnement
2. Validez toutes les entrées utilisateur avant de les envoyer à l'API
3. Utilisez exclusivement HTTPS pour toutes les communications
4. Implémentez une vérification de signature sur tous les webhooks
5. Limitez les tentatives de paiement par IP pour prévenir les abus
6. Gardez le SDK à jour pour bénéficier des correctifs de sécurité