ElyonPay Logo

    Documentation API ElyonPay

    Bienvenue dans la documentation technique de l'API ElyonPay. Cette référence vous permet d'intégrer les paiements Mobile Money, Visa, Mastercard et virements dans votre application en quelques lignes de code.

    URL de base : https://api.elyonpay.org/api
    Toutes les requêtes doivent être envoyées en HTTPS. Les requêtes HTTP non sécurisées sont refusées.

    Fonctionnalités clés

    • Mobile Money unifiéMTN MoMo, Orange Money, Wave, Moov, Airtel Money
    • Cartes bancairesVisa, Mastercard avec 3D Secure, conformité PCI DSS niveau 1
    • Intégration simpleLien de paiement + iframe, vérification active du statut
    • Sandbox completTestez sans frais avec des données simulées
    • Multi-devisesXAF, XOF, EUR, USD, GBP, NGN, CDF, KES
    • SDKs officielsJavaScript, PHP, Python, Java, React Native, Flutter

    Démarrage rapide

    Suivez ces 3 étapes pour effectuer votre premier paiement :

    1. Contactez-nous pour obtenir votre clé API
    2. Installez le SDK de votre langage ou utilisez cURL directement
    3. Appelez POST /api/request-to-pay/payment/link avec le montant et les URLs de redirection
    bash
    curl -X POST https://api.elyonpay.org/api/request-to-pay/payment/link \
      -H "Authorization: Bearer <your_jwt_token>" \
      -H "Content-Type: application/json" \
      -H "language: fr" \
      -d '{
        "amount": 15000,
        "user_lang": "fr",
        "msisdn": "+237600000000",
        "success": "https://yoursite.com/success",
        "error": "https://yoursite.com/error"
      }'

    Authentification

    L'API ElyonPay utilise l'authentification JWT (JSON Web Token). Obtenez votre token via l'endpoint de login, puis incluez-le dans chaque requête.

    POST/api/login
    ParamètreTypeRequisDescription
    usernamestringRequisEmail du compte marchand
    passwordstringRequisMot de passe du compte
    rolestringRequisROLE_MERCHANT_ADMIN
    bash
    curl -X POST https://api.elyonpay.org/api/login \
      -H "Content-Type: application/json" \
      -d '{
        "username": "you@example.com",
        "password": "***",
        "role": "ROLE_MERCHANT_ADMIN"
      }'

    Réponse

    json
    {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...."
    }

    Utilisation dans l'en-tête HTTP

    bash
    Authorization: Bearer <your_jwt_token>
    Sécurité : Ne jamais exposer votre token JWT côté client (JavaScript navigateur). Effectuez toujours les appels depuis votre serveur backend. Le token expire après un délai configurable — pensez à le renouveler.

    Environnements

    ElyonPay propose deux environnements distincts pour vous permettre de développer et tester en toute sécurité avant la mise en production.

    URLs de base

    EnvironnementURL de baseDescription
    Sandboxhttps://api.elyonpay.net/apiAucun débit réel — données simulées
    Productionhttps://api.elyonpay.org/apiTransactions réelles
    Utilisez l'environnement Sandbox pour le développement et les tests. Passez sur l'URL de production uniquement lorsque vous êtes prêt à traiter de vrais paiements.

    Numéros de test Mobile Money

    NuméroRéseauComportement simulé
    +237600000001MTN MoMoPaiement réussi
    +237600000002MTN MoMoSolde insuffisant
    +237690000001Orange MoneyPaiement réussi
    +237690000002Orange MoneyTimeout simulé
    +221700000001WavePaiement réussi

    Format des requêtes

    Toutes les requêtes et réponses utilisent le format JSON. L'en-tête Content-Type: application/json est obligatoire pour les requêtes avec un body.

    En-têtes requis

    En-têteValeurObligatoire
    AuthorizationBearer {votre_token_jwt}Requis
    Content-Typeapplication/jsonRequis (POST)
    Acceptapplication/jsonOptionnel
    Idempotency-KeyUUID uniqueRecommandé

    Format de réponse standard

    json
    {
      "success": true,
      "data": {
        "id": "pay_1A2B3C4D5E6F",
        "status": "pending",
        "amount": 15000,
        "currency": "XAF"
      },
      "meta": {
        "request_id": "req_xxxxxxx",
        "timestamp": "2024-03-24T10:15:00Z"
      }
    }

    Créer un paiement

    Génère un lien de paiement sécurisé. Le client est redirigé vers ce lien pour choisir sa méthode de paiement (Mobile Money, carte bancaire) et finaliser la transaction.

    POST/api/request-to-pay/payment/link

    Paramètres du body

    ParamètreTypeRequisDescription
    amountnumberRequisMontant du paiement
    user_langstringRequisLangue de l'interface de paiement (fr, en)
    msisdnstringRequisNuméro de téléphone au format international : +237600000000
    successstringRequisURL de redirection en cas de succès
    errorstringRequisURL de redirection en cas d'erreur

    Réponse

    json
    {
      "url": "https://app.elyonpay.org/t/CI032667e43abf11?success=https://www.success.com&error=https://www.error.com"
    }

    Exemples de code

    cURL

    bash
    curl -X POST https://api.elyonpay.org/api/request-to-pay/payment/link \
      -H "Authorization: Bearer <your_jwt_token>" \
      -H "Content-Type: application/json" \
      -H "language: fr" \
      -d '{
        "amount": 15000,
        "user_lang": "fr",
        "msisdn": "+237600000001",
        "success": "https://yoursite.com/success",
        "error": "https://yoursite.com/error"
      }'

    Node.js / JavaScript

    javascript
    const response = await fetch('https://api.elyonpay.org/api/request-to-pay/payment/link', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json',
        'language': 'fr'
      },
      body: JSON.stringify({
        amount: 15000,
        user_lang: 'fr',
        msisdn: '+237600000001',
        success: 'https://yoursite.com/success',
        error: 'https://yoursite.com/error'
      })
    });
    
    const data = await response.json();
    console.log(data.url); // Payment link to redirect the customer

    PHP

    php
    $ch = curl_init('https://api.elyonpay.org/api/request-to-pay/payment/link');
    curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'language: fr'
      ],
      CURLOPT_POSTFIELDS => json_encode([
        'amount'    => 15000,
        'user_lang' => 'fr',
        'msisdn'    => '+237600000001',
        'success'   => 'https://yoursite.com/success',
        'error'     => 'https://yoursite.com/error'
      ])
    ]);
    
    $response = json_decode(curl_exec($ch), true);
    echo $response['url']; // Payment link

    Transactions

    Récupérez l'historique complet de vos transactions : paiements reçus, remboursements, frais.

    GET/api/transactions

    Retourne la liste paginée de toutes vos transactions. Vous pouvez également récupérer le détail d'une transaction spécifique via son identifiant.

    Détail d'une transaction

    GET/api/transactions/{id}
    bash
    curl -X GET https://api.elyonpay.org/api/transactions/1553 \
      -H "Authorization: Bearer <your_jwt_token>" \
      -H "Accept: application/json"

    Exemple de réponse

    json
    {
      "id": 1553,
      "PSPid": "FR033169cbd9c1f1",
      "uuid": "FR033169cbd9c1f1",
      "creation_date": "2026-03-31T14:27:13+00:00",
      "validation_date": null,
      "delivery_date": null,
      "amount": 100,
      "totalCustomer": 100,
      "state": "CREATED",
      "ticket_type": "SMS_EMAIL",
      "operation_code": "03",
      "payer_phone_number": "+33782112127",
      "beneficiary_phone_number": "+33782112127",
      "payer_currency": "EUR",
      "beneficiary_currency": "EUR",
      "payer_country": "FR",
      "beneficiary_country": "FR",
      "payment": {
        "name": "MOLLIE"
      },
      "customer": {
        "phoneNumber": "+33782112127",
        "email": "client@example.com"
      },
      "merchant": {
        "id": 258,
        "name": "Ma Boutique",
        "city": "Paris",
        "address": "10 Rue de la Paix",
        "zipCode": "75002",
        "type": "individual",
        "country_code": "FR",
        "country": "France"
      },
      "transactionStates": [
        {
          "state": "CREATED",
          "date": "2026-03-31T14:27:14+00:00"
        }
      ],
      "commission_operateur": 0,
      "commission_marchand": 0,
      "commission_pays": 0,
      "commission_customer": 0,
      "deliveryPrice": 0
    }

    Champs de la réponse

    ChampTypeDescription
    idintegerIdentifiant interne de la transaction
    PSPidstringIdentifiant unique ElyonPay (ex : FR033169cbd9c1f1)
    uuidstringIdentifiant unique — même valeur que PSPid
    creation_datedatetimeDate de création (ISO 8601 avec timezone)
    validation_datedatetime|nullDate de validation du paiement — null si non encore validé
    delivery_datedatetime|nullDate de livraison — null si non applicable
    amountnumberMontant de la transaction dans la devise du bénéficiaire
    totalCustomernumberMontant total facturé au client (commissions incluses)
    statestringStatut actuel : CREATED, PENDING, SUCCESSFUL, FAILED, EXPIRED
    ticket_typestringType de notification : SMS_EMAIL, SMS, EMAIL
    operation_codestringCode d'opération interne
    payer_phone_numberstringNuméro de téléphone du payeur (format international)
    beneficiary_phone_numberstringNuméro de téléphone du bénéficiaire
    payer_currencystringDevise du payeur (code ISO 4217 : EUR, XAF, XOF...)
    beneficiary_currencystringDevise du bénéficiaire
    payer_countrystringCode pays du payeur (ISO 3166 : FR, CM, CI...)
    beneficiary_countrystringCode pays du bénéficiaire
    payment.namestringFournisseur de paiement utilisé (MOLLIE, MTN, ORANGE...)

    Objet customer

    ChampTypeDescription
    phoneNumberstringNuméro de téléphone du client
    emailstringAdresse email du client

    Objet merchant

    ChampTypeDescription
    idintegerIdentifiant du marchand
    namestringNom du marchand ou de l'enseigne
    citystringVille du marchand
    addressstringAdresse postale
    zipCodestringCode postal
    typestringType de compte : individual, company
    country_codestringCode pays ISO 3166 (FR, CM, CI...)
    countrystringNom du pays

    Tableau transactionStates

    Historique des changements de statut de la transaction, du plus ancien au plus récent.

    ChampTypeDescription
    statestringStatut à cet instant (CREATED, PENDING, SUCCESSFUL, FAILED...)
    datedatetimeDate du changement de statut

    Commissions

    ChampTypeDescription
    commission_operateurnumberCommission opérateur télécom
    commission_marchandnumberCommission marchand
    commission_paysnumberCommission pays
    commission_customernumberCommission appliquée au client
    deliveryPricenumberFrais de livraison

    SDKs officiels

    Des SDKs officiels sont disponibles pour les principaux langages et frameworks. Ils gèrent automatiquement l'authentification et les erreurs.

    JavaScript
    npm install elyonpay-sdk
    PHP
    composer require elyonpay/php-sdk
    Python
    pip install elyonpay
    Java
    Maven / Gradle
    React Native
    npm install @elyonpay/rn
    Flutter
    pub add elyonpay_flutter

    Flux d'intégration

    ElyonPay utilise un modèle en 6 étapes basé sur un lien de paiement et une vérification active du statut (modèle pull). Aucune infrastructure webhook n'est nécessaire.

    1

    Obtenir un lien de paiement

    Votre backend appelle POST /api/request-to-pay/payment/link avec le montant et les URLs de redirection (success / error). L'API retourne une URL de paiement unique.

    2

    Afficher l'iframe de paiement

    Redirigez le client vers l'URL retournée, ou intégrez-la dans une iframe. Le client choisit sa méthode de paiement (Mobile Money, carte bancaire) et saisit ses informations.

    3

    Validation du paiement

    Le client confirme le paiement côté opérateur (code USSD Mobile Money, 3D Secure carte). ElyonPay traite la transaction.

    4

    Redirection vers votre backend

    Une fois le paiement traité, le client est redirigé vers votre URL success ou error selon le résultat. L'UUID de la transaction est transmis dans l'URL de redirection.

    5

    Vérifier le statut de la transaction

    Votre backend appelle GET /api/transactions/{uuid} pour récupérer le statut définitif de la transaction. Cette vérification côté serveur est indispensable — ne vous fiez jamais uniquement à l'URL de redirection.

    6

    Afficher la confirmation au client

    Selon le statut retourné (SUCCESSFUL, FAILED, EXPIRED...), affichez la page de confirmation ou d'erreur appropriée à votre client.

    Modèle pull : Pas de webhook à exposer, pas de signature à vérifier, pas de retry à gérer. Votre backend contrôle le timing de la vérification.

    Diagramme — Initiation du paiement

    sequenceDiagram
      participant Customer
      participant Merchant
      participant ElyonPay
    
      Customer->>Merchant: Finalizes cart
      Customer->>Merchant: Selects "Pay"
      Merchant->>ElyonPay: POST /api/login
      ElyonPay-->>Merchant: Returns JWT token
      Merchant->>ElyonPay: POST /api/request-to-pay/payment/link
      ElyonPay-->>Merchant: Returns payment URL
      Merchant->>Customer: Displays payment page (iframe or redirect)
      Customer->>ElyonPay: Selects payment method
      Customer->>ElyonPay: Completes transaction
      ElyonPay-->>Customer: Shows confirmation popup
          

    Diagramme — Résultat du paiement

    sequenceDiagram
      participant Customer
      participant Merchant
      participant ElyonPay
    
      Customer->>ElyonPay: Transaction completed
      alt Successful payment
          ElyonPay->>Merchant: Redirect to success URL
      else Failed payment
          ElyonPay->>Merchant: Redirect to error URL
      end
      Merchant->>ElyonPay: GET /api/transactions/[ID_TRANSACTION]
      ElyonPay-->>Merchant: Returns transaction status
      Merchant->>Merchant: Updates order status
      Merchant->>Customer: Shows order confirmation
          

    Exemple d'implémentation (étapes 1 → 5)

    Node.js / Express

    javascript
    // 1. Create payment link
    app.post('/checkout', async (req, res) => {
      const response = await fetch('https://api.elyonpay.org/api/request-to-pay/payment/link', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer ' + token,
          'Content-Type': 'application/json',
          'language': 'fr'
        },
        body: JSON.stringify({
          amount: req.body.amount,
          user_lang: 'fr',
          msisdn: req.body.phone,
          success: 'https://yoursite.com/payment/done',
          error: 'https://yoursite.com/payment/error'
        })
      });
      const { url } = await response.json();
      res.redirect(url); // 2. Redirect customer to payment page
    });
    
    // 4 → 5. Handle redirect & verify status
    app.get('/payment/done', async (req, res) => {
      // The transaction uuid is available from your order context
      const tx = await fetch(`https://api.elyonpay.org/api/transactions/${uuid}`, {
        headers: { 'Authorization': 'Bearer ' + token }
      }).then(r => r.json());
    
      if (tx.state === 'SUCCESSFUL') {
        // 6. Show confirmation
        res.render('success', { transaction: tx });
      } else {
        res.render('pending', { transaction: tx });
      }
    });
    Ne vous fiez jamais uniquement à l'URL de redirection (success/error) pour confirmer un paiement. Un utilisateur peut modifier l'URL manuellement. Vérifiez toujours le statut côté serveur via GET /api/transactions/{uuid}.

    Mobile Money

    ElyonPay unifie 5 réseaux Mobile Money africains sous une seule API. Chaque réseau possède ses propres codes opérateurs et pays de couverture.

    Réseaux supportés

    Code méthodeRéseauPaysDevises
    mtn_mobile_moneyMTN MoMoCM, NG, CI, GH, UGXAF, NGN, XOF
    orange_moneyOrange MoneyCM, CI, SN, MLXAF, XOF
    waveWaveSN, CI, BF, MLXOF
    moov_moneyMoov AfricaBJ, TG, BF, NEXOF
    airtel_moneyAirtel MoneyKE, TZ, UG, ZM, CDKES, TZS, UGX, CDF

    Couverture : Cameroun, Nigeria, Côte d'Ivoire, Ghana, Ouganda, Sénégal, Mali, Burkina Faso, Bénin, Togo, Niger, Kenya, Tanzanie, Zambie, République Démocratique du Congo.

    Cartes bancaires

    Acceptez les paiements Visa et Mastercard avec 3D Secure, tokenisation et conformité PCI DSS niveau 1.

    Cartes de test (Sandbox)

    Numéro de carteExpirationCVVComportement
    4242 4242 4242 424212/28123Paiement réussi
    4000 0000 0000 000212/28123Carte refusée
    4000 0000 0000 322012/281233D Secure requis
    5555 5555 5555 444412/28123Mastercard réussi

    Statuts des paiements

    Chaque paiement passe par plusieurs statuts au cours de son cycle de vie.

    CREATED
    Transaction créée
    PENDING
    Paiement initié, en attente
    WAITING_FOR_PAYMENT
    En attente du paiement client
    ACCEPTED
    Paiement confirmé
    DELIVERED
    Fonds transférés au marchand
    REJECTED
    Validation échouée
    DECLINED
    Paiement refusé
    CANCELLED
    Annulé par l'utilisateur ou l'admin

    Diagramme des transitions d'état

    stateDiagram-v2
      [*] --> CREATED
      CREATED --> PENDING: Payment initiated
      PENDING --> WAITING_FOR_PAYMENT: Awaiting customer
      WAITING_FOR_PAYMENT --> ACCEPTED: Payment confirmed
      PENDING --> ACCEPTED: Direct approval
      PENDING --> REJECTED: Validation failed
      PENDING --> DECLINED: Payment issue
      WAITING_FOR_PAYMENT --> DECLINED: Payment issue
      WAITING_FOR_PAYMENT --> CANCELLED: User cancellation
      ACCEPTED --> DELIVERED: Funds transferred
      ACCEPTED --> CANCELLED: Administrative action
      REJECTED --> [*]
      DECLINED --> [*]
      CANCELLED --> [*]
      DELIVERED --> [*]
          

    Codes d'erreur

    En cas d'erreur, l'API retourne un objet JSON avec un code d'erreur machine et un message lisible.

    json
    {
      "success": false,
      "error": {
        "code": "INSUFFICIENT_FUNDS",
        "message": "Le solde Mobile Money du client est insuffisant.",
        "http_status": 402
      }
    }

    Table des erreurs

    Code erreurHTTPDescription
    UNAUTHORIZED401Clé API manquante ou invalide
    INVALID_AMOUNT400Montant invalide ou inférieur au minimum autorisé
    CURRENCY_NOT_SUPPORTED400Devise non supportée pour ce réseau
    PHONE_INVALID400Numéro de téléphone invalide ou non enregistré
    INSUFFICIENT_FUNDS402Solde insuffisant côté client
    OPERATOR_TIMEOUT408L'opérateur Mobile Money n'a pas répondu dans les délais
    DUPLICATE_REQUEST409Requête dupliquée — utiliser Idempotency-Key
    PAYMENT_NOT_FOUND404Paiement introuvable
    RATE_LIMIT_EXCEEDED429Trop de requêtes — réessayez dans quelques secondes
    INTERNAL_ERROR500Erreur interne ElyonPay — contactez le support

    Devises supportées

    CodeDeviseMontant minimumMéthodes
    XAFFranc CFA BEAC100 XAFMTN MoMo, Orange Money, Carte
    XOFFranc CFA BCEAO100 XOFWave, Moov, Orange Money, MTN, Carte
    EUREuro0,50 EURCarte (Visa, Mastercard), PayPal
    USDDollar américain0,50 USDCarte, PayPal
    GBPLivre sterling0,30 GBPCarte
    NGNNaira nigérian100 NGNMTN MoMo NG
    KESShilling kenyan10 KESAirtel Money
    CDFFranc congolais500 CDFAirtel Money

    Sandbox & Tests

    L'environnement sandbox vous permet de tester l'intégration complète sans effectuer de vrais paiements. Connectez-vous sur api.elyonpay.net — aucun débit réel ne sera effectué.

    Accédez au tableau de bord sur dashboard.elyonpay.org pour visualiser vos transactions en temps réel.

    Comptes de test par pays

    Utilisez ces identifiants pour tester l'intégration sur l'environnement sandbox. Chaque compte est associé à un pays et une devise spécifiques.

    🇨🇲CamerounXAF
    TéléphoneEmailMot de passe
    +237683191284demo+23733@elyonpay.comCompteDemo1
    🇨🇮Côte d'IvoireXOF
    TéléphoneEmailMot de passe
    +2250758789285demo+225@elyonpay.comCompteDemo1
    🇫🇷FranceEUR
    TéléphoneEmailMot de passe
    +33895555555demo+33@elyonpay.comCompteDemo1

    Limites du sandbox

    • Les transactions sandbox n'engendrent aucuns frais
    • Les données sont réinitialisées tous les 30 jours
    • Limite de 1 000 requêtes/heure par clé test

    Passer en production

    1. Complétez la vérification KYB (Know Your Business) dans votre tableau de bord
    2. Changez l'URL de base de api.elyonpay.net vers api.elyonpay.org
    3. Vérifiez votre callback_url en HTTPS
    4. Configurez vos alertes de solde bas
    En production, assurez-vous que votre callback_url retourne un HTTP 200 dans les 10 secondes. En cas d'échec, ElyonPay retente 3 fois avec un délai exponentiel.