Intégrer l'API ElyonPay avec JavaScript (Node.js)

1Pourquoi utiliser l'API ElyonPay

L'API ElyonPay permet aux développeurs d'intégrer des paiements Mobile Money et carte bancaire dans leurs applications web ou mobiles. L'API utilise un modèle de lien de paiement (payment link) : vous créez un lien côté serveur, puis vous redirigez le client vers ce lien pour qu'il effectue le paiement sur une page sécurisée ElyonPay.

Ce modèle offre plusieurs avantages : la gestion de la conformité PCI DSS est prise en charge par ElyonPay, vous n'avez pas besoin de manipuler les données sensibles du client, et l'expérience de paiement est optimisée pour chaque opérateur Mobile Money (MTN MoMo, Orange Money, Wave, Moov Africa, Airtel Money) ainsi que pour les paiements par carte Visa et Mastercard avec 3D Secure.

L'API est RESTful et disponible en environnement sandbox pour les tests. Elle supporte les paiements dans 14 pays africains et les devises XAF, XOF, EUR, USD, GBP, NGN, KES et CDF. Si vous ciblez spécifiquement le marché camerounais, consultez notre guide complet des passerelles de paiement au Cameroun pour comparer les différentes solutions disponibles.

2Prérequis et environnements

Avant de commencer, vous aurez besoin d'un compte marchand ElyonPay avec les identifiants de connexion API (username et password fournis lors de l'inscription). L'API ElyonPay utilise deux environnements distincts avec des URLs de base différentes :

Toutes les requêtes doivent utiliser HTTPS — les requêtes HTTP non sécurisées sont rejetées. Pour ce tutoriel, nous utiliserons Node.js avec le module natif fetch (Node.js 18+) ou la bibliothèque axios. Aucun SDK propriétaire n'est nécessaire pour interagir avec l'API.

# Optionnel : installer axios si vous n'utilisez pas fetch natif
npm install axios

Créez un fichier .env pour stocker vos identifiants de manière sécurisée. Ne commettez jamais ce fichier dans votre dépôt de code source.

ELYONPAY_API_URL=https://api.elyonpay.net/api
ELYONPAY_USERNAME=votre_username
ELYONPAY_PASSWORD=votre_password

3Authentification JWT

L'API ElyonPay utilise l'authentification JWT (JSON Web Token). Vous devez d'abord obtenir un token en appelant l'endpoint de login avec vos identifiants marchand, puis inclure ce token dans l'en-tête Authorization de toutes vos requêtes suivantes.

const API_URL = process.env.ELYONPAY_API_URL;

async function getToken() {
    const response = await fetch(`${API_URL}/login`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            username: process.env.ELYONPAY_USERNAME,
            password: process.env.ELYONPAY_PASSWORD,
            role: 'ROLE_MERCHANT_ADMIN'
        })
    });

    if (!response.ok) {
        throw new Error(`Login failed: ${response.status}`);
    }

    const data = await response.json();
    return data.token;
}

Le token JWT a une durée de vie limitée. En production, implémentez un mécanisme de renouvellement automatique : stockez le token en mémoire et regénérez-le avant son expiration. Le rôle ROLE_MERCHANT_ADMIN donne accès à l'ensemble des opérations de paiement.

4Créer un lien de paiement

L'opération centrale de l'API est la création d'un lien de paiement via l'endpoint POST /api/request-to-pay/payment/link. Vous envoyez le montant, le numéro de téléphone du client, la langue et les URLs de redirection. L'API retourne une URL de paiement vers laquelle vous redirigez le client.

async function createPaymentLink(token, orderData) {
    const response = await fetch(`${API_URL}/request-to-pay/payment/link`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json',
            'Idempotency-Key': orderData.orderId // évite les doublons
        },
        body: JSON.stringify({
            amount: orderData.amount,
            user_lang: 'fr',
            msisdn: orderData.phone,
            success_url: 'https://votresite.com/paiement-reussi',
            error_url: 'https://votresite.com/paiement-echec'
        })
    });

    if (!response.ok) {
        const error = await response.json();
        throw new Error(`Payment link creation failed: ${error.message}`);
    }

    const data = await response.json();
    return data.data.payment_url;
}

// Utilisation
const token = await getToken();
const paymentUrl = await createPaymentLink(token, {
    amount: 5000,
    phone: '+237691234567',
    orderId: 'CMD-2026-001'
});

console.log('Rediriger le client vers:', paymentUrl);

L'en-tête Idempotency-Key est fortement recommandé : il garantit qu'une même requête ne sera pas traitée deux fois en cas de problème réseau. Utilisez un identifiant unique par commande (votre référence de commande par exemple).

Le paramètre user_lang accepte fr ou en et détermine la langue de la page de paiement présentée au client. Le champ msisdn est le numéro de téléphone du client au format international. Les URLs success_url et error_url sont les pages vers lesquelles le client sera redirigé après le paiement.

5Rediriger le client et vérifier la transaction

Une fois le lien de paiement obtenu, redirigez le client vers cette URL. Il effectue le paiement sur la page sécurisée ElyonPay, puis est redirigé vers votre success_url ou error_url. L'API ElyonPay utilise un modèle « pull » : c'est à vous de vérifier le statut de la transaction côté serveur, plutôt que d'attendre un webhook.

async function getTransaction(token, transactionId) {
    const response = await fetch(`${API_URL}/transactions/${transactionId}`, {
        method: 'GET',
        headers: {
            'Authorization': `Bearer ${token}`,
            'Accept': 'application/json'
        }
    });

    if (!response.ok) {
        throw new Error(`Transaction fetch failed: ${response.status}`);
    }

    return await response.json();
}

// Vérifier le statut après redirection du client
const transaction = await getTransaction(token, transactionId);
console.log('Statut:', transaction.data.state);
// Statuts possibles : CREATED, PENDING, WAITING_FOR_PAYMENT,
//                     ACCEPTED, DELIVERED, REJECTED, DECLINED, CANCELLED

Les statuts suivent un cycle de vie précis : CREATED → PENDING → WAITING_FOR_PAYMENT → ACCEPTED → DELIVERED. Les statuts alternatifs sont REJECTED, DECLINED et CANCELLED. Ne considérez un paiement comme réussi qu'au statut DELIVERED.

Vous pouvez également lister toutes vos transactions avec pagination via GET /api/transactions pour la réconciliation comptable ou l'affichage dans votre tableau de bord.

6Gérer les erreurs

L'API retourne des erreurs au format JSON avec des codes machine lisibles et des codes HTTP standards. Implémentez une gestion robuste des erreurs pour offrir une bonne expérience utilisateur.

async function safeApiCall(url, options) {
    try {
        const response = await fetch(url, options);

        if (!response.ok) {
            const error = await response.json();

            switch (error.code) {
                case 'INSUFFICIENT_FUNDS':
                    throw new Error('Solde insuffisant sur le compte du client');
                case 'PHONE_INVALID':
                    throw new Error('Numéro de téléphone invalide');
                case 'AMOUNT_TOO_LOW':
                    throw new Error('Montant inférieur au minimum autorisé');
                case 'TOKEN_EXPIRED':
                    // Renouveler le token et réessayer
                    return await retryWithNewToken(url, options);
                default:
                    throw new Error(`Erreur API: ${error.message}`);
            }
        }

        return await response.json();
    } catch (err) {
        if (err.name === 'TypeError') {
            // Erreur réseau (pas de connexion)
            throw new Error('Impossible de contacter le serveur ElyonPay');
        }
        throw err;
    }
}

Les erreurs les plus courantes sont INSUFFICIENT_FUNDS (solde insuffisant), PHONE_INVALID (numéro incorrect ou non enregistré), et TOKEN_EXPIRED (token JWT expiré). Pour cette dernière, implémentez un renouvellement automatique du token et réessayez la requête.

Adaptez toujours les messages d'erreur pour l'utilisateur final. Un message clair — « Votre solde Mobile Money est insuffisant, veuillez recharger votre compte » — est plus utile qu'un code technique brut.

7Passer en production

Une fois votre intégration testée en sandbox, le passage en production consiste à changer l'URL de base de l'API de https://api.elyonpay.net/api (sandbox) vers https://api.elyonpay.org/api (production) et à utiliser vos identifiants de production.

// Production
const API_URL = 'https://api.elyonpay.org/api';

// Effectuer une première transaction test avec un petit montant
const token = await getToken();
const testUrl = await createPaymentLink(token, {
    amount: 100,  // montant minimum pour test
    phone: '+237691234567',
    orderId: 'TEST-PROD-001'
});
console.log('Test de production:', testUrl);

Le sandbox ElyonPay fournit des numéros de téléphone de test avec des comportements simulés (succès, fonds insuffisants, timeout) ainsi que des numéros de carte de test pour valider différents scénarios. Exploitez-les pour tester exhaustivement votre intégration avant le passage en production.