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.

    URLs de base : https://api.elyonpay.net/api (Sandbox) / https://api.elyonpay.org/api (Production)
    Toutes les requêtes doivent être envoyées en HTTPS. Les requêtes HTTP non sécurisées sont refusées. Voir la section Environnements pour plus de détails.

    Fonctionnalités clés

    • Mobile Money unifié — MTN MoMo, Orange Money, Wave, Moov, Airtel Money
    • Cartes bancaires — Visa, Mastercard avec 3D Secure, conformité PCI DSS niveau 1
    • Intégration simple — Lien de paiement + iframe, vérification active du statut
    • Sandbox complet — Testez sans frais avec des données simulées
    • Multi-devises — XAF, XOF, EUR, USD, GBP, NGN, CDF, KES
    • SDKs officiels — JavaScript, 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.

    Clé API (accès scopé)

    En alternative au JWT, une clé API serveur-à-serveur authentifie vos appels de paiement. Elle est disponible pour tous les comptes marchands et se récupère — ou se régénère — depuis votre tableau de bord.

    bash
    Authorization: Bearer pk_live_...
    Portée limitée : Pour votre sécurité, une clé API n'a accès qu'aux endpoints de paiement et de transaction (Bankcard, Cash, Mobile Money, Request-to-Pay, wallet et décaissements, ainsi que la consultation des transactions). Tout autre endpoint renvoie une erreur 403. La gestion du compte et du tableau de bord requiert un JWT.

    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

    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 que vos URLs de redirection (success / error) sont en HTTPS
    4. Configurez vos alertes de solde bas
    ElyonPay utilise un modèle pull : après la redirection du client, votre serveur doit appeler GET /api/transactions/{uuid} pour obtenir le statut définitif. En complément, des webhooks optionnels peuvent notifier votre serveur en temps réel.

    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
    webhookstringOptionnelURL HTTPS notifiée à chaque changement d'état de la transaction (voir la section Webhooks)
    external_idstringOptionnelVotre référence de commande, 1 à 64 caractères, unique par marchand. Renvoyée dans GET /api/transactions/{uuid} (externalId) et dans les webhooks (data.external_id)
    customerobjectOptionnelVotre client final, en un bloc : { account_ref, name, email, phone, locale }. Le même bloc est accepté sur tous les endpoints d'encaissement ; renvoyé dans GET /api/transactions/{uuid} (accountRef, accountName, customerEmail) et dans les webhooks (data.customer)
    customer.account_refstringOptionnelIdentifiant du client chez vous (abonné, compte, n° client…), 1 à 64 caractères : une étiquette que nous vous rendons dans les réponses et les webhooks
    customer.namestringOptionnelNom déclaré du client, 128 caractères au plus. Affiché dans votre espace marchand ; jamais utilisé comme clé.
    customer.emailstringOptionnelE-mail du client, 190 caractères au plus, validé (422 sinon). Conservé sur la transaction pour les messages qui lui sont adressés
    customer.phonestringOptionnelNuméro déclaré du client, au format international. Équivalent de msisdn : l'un des deux suffit. Au paiement, le numéro réellement débité le remplace
    customer.localestringOptionnelLangue des messages adressés au client (fr, en, en-GB…)
    onbehalfofstring | numberOptionnelEncaisser pour le compte d'un sous-marchand : son id ou son code partner. Réservé aux marchands plateforme (voir la section Paiements plateforme)
    feesnumberOptionnelCommission plateforme à prélever (même unité que amount). Si absent, les frais par défaut du sous-marchand puis de la plateforme s'appliquent
    Champs renommés : player_ref et player_name ne sont plus acceptés. Envoyez customer.account_ref et customer.name. Une requête qui contient encore l'ancien nom est refusée sur tous les endpoints de paiement : 422 PLAYER_REF_REMOVED ou PLAYER_NAME_REMOVED, avec le nom qui le remplace.

    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",
        "webhook": "https://yoursite.com/webhooks/elyonpay",
        "external_id": "CMD-2026-0042",
        "customer": {
          "account_ref": "CLT-1001",
          "name": "Jean Mballa",
          "email": "jean@example.com"
        }
      }'

    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',
        webhook: 'https://yoursite.com/webhooks/elyonpay',
        external_id: 'CMD-2026-0042',
        customer: {
          account_ref: 'CLT-1001',
          name: 'Jean Mballa',
          email: 'jean@example.com'
        }
      })
    });
    
    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',
        'webhook'   => 'https://yoursite.com/webhooks/elyonpay',
        'external_id' => 'CMD-2026-0042',
        'customer'  => [
          'account_ref' => 'CLT-1001',
          'name'        => 'Jean Mballa',
          'email'       => 'jean@example.com'
        ]
      ])
    ]);
    
    $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, WAITING_FOR_PAYMENT, ACCEPTED, DELIVERED, REJECTED, DECLINED, CANCELLED
    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)
    externalIdstring|nullVotre référence de commande (external_id), telle que fournie à la création
    accountRefstring|nullIdentifiant de votre client final (customer.account_ref), tel que fourni à la création
    accountNamestring|nullNom déclaré du client final (customer.name)
    customerEmailstring|nullE-mail déclaré du client final (customer.email)
    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, WAITING_FOR_PAYMENT, ACCEPTED, DELIVERED...)
    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

    Custom Checkout

    Le Custom Checkout vous permet de construire votre propre interface de paiement tout en utilisant les APIs ElyonPay. Contrairement au lien de paiement simple (redirect), vous gardez le contrôle complet de l'expérience utilisateur.

    Quand utiliser le Custom Checkout ? Utilisez cette approche si vous avez besoin d'une interface personnalisée ou d'un contrôle total sur le flux de paiement. Pour un paiement simple à montant fixe, le lien de paiement (section Créer un paiement) est plus rapide à intégrer.

    Flux en 4 étapes

    1

    Récupérer les méthodes de paiement

    Appelez GET /api/public/configuration/payments/{countryCode} pour obtenir la liste des méthodes disponibles dans le pays du client.

    2

    Afficher votre checkout

    Présentez le récapitulatif et les méthodes de paiement dans votre propre interface. Le client choisit comment payer.

    3

    Initier le paiement

    Envoyez la requête de paiement direct (Mobile Money ou carte bancaire) avec la méthode choisie.

    4

    Suivre le statut

    Interrogez GET /api/transactions/{id} toutes les 3 à 5 secondes jusqu'à obtenir un statut terminal (DELIVERED, FAILED, CANCELLED).

    Diagramme de séquence

    sequenceDiagram
      participant Customer
      participant Merchant
      participant ElyonPay
    
      Customer->>Merchant: Browses products
      Merchant->>ElyonPay: GET /api/public/configuration/payments/{country}
      ElyonPay-->>Merchant: Available payment methods
      Customer->>Merchant: Selects payment method
      Merchant->>ElyonPay: POST /api/mobile-money/payment/request
      ElyonPay-->>Merchant: PaymentResult (transactionId, state)
      loop Poll every 3-5s (max 2 min)
        Merchant->>ElyonPay: GET /api/transactions/{id}
        ElyonPay-->>Merchant: Transaction state
      end
      Merchant->>Customer: Displays confirmation or error
          

    Méthodes de paiement

    Récupérez dynamiquement la liste des méthodes de paiement disponibles dans un pays donné. Cet endpoint est public — aucune authentification n'est requise.

    GET/api/public/configuration/payments/{countryCode}

    Paramètre de chemin

    ParamètreTypeRequisDescription
    countryCodestringRequisCode pays ISO 3166 — voir le tableau ci-dessous

    Codes pays supportés

    CodePays
    CMCameroun
    CICôte d'Ivoire
    GAGabon
    FRFrance
    TGTogo
    BJBénin
    Endpoint public : Cet endpoint ne nécessite aucune authentification. Vous pouvez l'appeler directement depuis le frontend pour adapter dynamiquement votre interface de paiement.

    Exemple de réponse

    json
    {
      "payments": [
        {
          "name": "ORANGE_MONEY",
          "label": "Orange Money",
          "type": "MOBILE_MONEY",
          "available": true
        },
        {
          "name": "MTN_MONEY",
          "label": "MTN Mobile Money",
          "type": "MOBILE_MONEY",
          "available": true
        },
        {
          "name": "STRIPE",
          "label": "Carte bancaire (Visa / Mastercard)",
          "type": "CARD",
          "available": true
        }
      ]
    }
    bash
    curl https://api.elyonpay.org/api/public/configuration/payments/CM

    Paiement direct

    Initiez un paiement directement depuis votre serveur sans redirection vers une page ElyonPay. Le client reste sur votre site pendant toute la transaction.

    Mobile Money

    POST/api/mobile-money/payment/request

    Paramètres du body

    ParamètreTypeRequisDescription
    amountnumberRequisMontant du paiement dans la devise locale
    user_langstringRequisLangue de l'utilisateur (fr, en)
    merchant_namestringRequisNom du marchand affiché au client
    merchant_idintegerRequisIdentifiant du marchand
    currencystringRequisCode devise ISO 4217 (XAF, XOF, EUR...)
    country_namestringRequisNom du pays du client
    payment_methodstringRequisDoit correspondre au champ name retourné par GET /api/public/configuration/payments/{countryCode}
    msisdnstringRequisNuméro de téléphone du client (format international)
    transactionstringOptionnelRéférence de transaction externe (optionnel)

    cURL

    bash
    curl -X POST https://api.elyonpay.org/api/mobile-money/payment/request \
      -H "Authorization: Bearer <your_jwt_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 15000,
        "user_lang": "fr",
        "merchant_name": "Ma Boutique",
        "merchant_id": 207,
        "currency": "XAF",
        "country_name": "Cameroon",
        "payment_method": "ORANGE_MONEY",
        "msisdn": "+237690000001"
      }'

    Node.js / JavaScript

    javascript
    const response = await fetch('https://api.elyonpay.org/api/mobile-money/payment/request', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount: 15000,
        user_lang: 'fr',
        merchant_name: 'Ma Boutique',
        merchant_id: 207,
        currency: 'XAF',
        country_name: 'Cameroon',
        payment_method: 'ORANGE_MONEY',
        customer_msisdn: '+237690000001'
      })
    });
    
    const result = await response.json();
    // Start polling result.data.uuid for status

    PHP

    php
    $ch = curl_init('https://api.elyonpay.org/api/mobile-money/payment/request');
    curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
      ],
      CURLOPT_POSTFIELDS => json_encode([
        'amount'          => 15000,
        'user_lang'       => 'fr',
        'merchant_name'   => 'Ma Boutique',
        'merchant_id'     => 207,
        'currency'        => 'XAF',
        'country_name'    => 'Cameroon',
        'payment_method'  => 'ORANGE_MONEY',
        'customer_msisdn' => '+237690000001'
      ])
    ]);
    
    $response = json_decode(curl_exec($ch), true);
    // Start polling $response['data']['uuid'] for status

    Carte bancaire

    POST/api/bankcard/payment/request

    Même payload que le paiement Mobile Money, à une exception près : payment_method ne désigne pas un opérateur mais le prestataire qui traite la carte. S'y ajoutent deux paramètres pour contrôler la redirection après paiement.

    Paramètres supplémentaires

    ParamètreTypeRequisDescription
    payment_methodstringRequisMOLLIE ou STRIPE — le prestataire qui traite la carte. Ce sont les deux seules valeurs acceptées : toute autre valeur est refusée en 422.
    successstringOptionnelURL de redirection après un paiement réussi. Le client sera redirigé vers {success}?id={uuid}&status=pending
    errorstringOptionnelURL de redirection après un paiement échoué ou annulé. Le client sera redirigé vers {error}?id={uuid}&status=cancelled

    Si ces paramètres ne sont pas fournis, le client sera redirigé vers la page de transaction ElyonPay par défaut.

    Important : 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}.

    Réponse — PaymentResult

    json
    {
      "success": true,
      "data": {
        "PSPid": "tr_aHYQAw4rudrttLDwtdKTJ",
        "PSPnotifyId": "tr_aHYQAw4rudrttLDwtdKTJ",
        "PSPtxnId": "tr_aHYQAw4rudrttLDwtdKTJ",
        "url": "https://www.mollie.com/checkout/credit-card/session/aHYQAw4rudrttLDwtdKTJ",
        "uuid": "CM06306a438d0958",
        "PSPMessage": null,
        "PSPstatus": ""
      }
    }

    Champs de la réponse

    ChampTypeDescription
    successbooleanIndique si la requête a réussi
    data.PSPidstringIdentifiant du prestataire de paiement (PSP)
    data.PSPnotifyIdstringIdentifiant de notification PSP
    data.PSPtxnIdstringIdentifiant de transaction PSP
    data.urlstringURL de paiement (redirection carte bancaire si applicable)
    data.uuidstringIdentifiant unique ElyonPay — utilisez-le pour le polling
    data.PSPMessagestring|nullMessage retourné par le PSP (null si aucun)
    data.PSPstatusstringStatut retourné par le PSP

    Suivi du statut

    Après avoir initié un paiement direct, interrogez périodiquement l'API pour connaître le résultat de la transaction. Le polling est le mécanisme de référence ; des webhooks optionnels sont également disponibles pour être notifié en temps réel.

    États terminaux

    ÉtatRésultatDescription
    DELIVEREDSuccèsPaiement confirmé, fonds transférés
    FAILEDÉchecPaiement échoué (solde insuffisant, erreur réseau...)
    DECLINEDÉchecPaiement refusé par l'opérateur
    CANCELLEDÉchecAnnulé par le client ou le système
    PENDINGPayéPaiement confirmé. Malgré son nom, cet état signifie que l'argent est encaissé : vous pouvez honorer la commande. Il n'attend plus que la livraison, pas le paiement.
    Changement à venir : PENDING sera renommé WAITING_FOR_DELIVERY

    Le mot « pending » prête à confusion : chez la plupart des prestataires de paiement il signifie « en cours, rien n'est décidé », alors qu'ici il signifie l'inverse — le paiement est encaissé. Nous le renommons donc en WAITING_FOR_DELIVERY, qui dit ce qu'il attend réellement.

    Aujourd'hui : rien ne change. L'API et les webhooks continuent d'envoyer state = "PENDING" et l'événement transaction.pending. Vos intégrations existantes fonctionnent sans modification.

    Pour vous préparer : acceptez dès maintenant les deux valeurs, PENDING et WAITING_FOR_DELIVERY, ainsi que les deux noms d'événement. Traitez-les comme un paiement confirmé et non comme une transaction en cours. La bascule sera annoncée à l'avance et ne se fera pas avant que vous ayez eu le temps de migrer.

    Délai de polling : Interrogez toutes les 3 à 5 secondes. Définissez un timeout maximum d'environ 2 minutes — au-delà, considérez la transaction comme expirée et affichez un message adapté au client.

    Exemple complet — Node.js / Express

    Cet exemple couvre les 4 étapes du Custom Checkout : méthodes de paiement, affichage, paiement direct et polling du statut.

    javascript
    const express = require('express');
    const app = express();
    app.use(express.json());
    
    const API = 'https://api.elyonpay.org/api';
    let token = ''; // Obtained via POST /api/login
    
    // Helper: poll transaction status
    async function pollStatus(txId, maxMs = 120000, intervalMs = 4000) {
      const start = Date.now();
      while (Date.now() - start < maxMs) {
        const res = await fetch(`${API}/transactions/${txId}`, {
          headers: { 'Authorization': 'Bearer ' + token }
        });
        const tx = await res.json();
        const terminal = ['DELIVERED', 'FAILED', 'DECLINED', 'CANCELLED'];
        if (terminal.includes(tx.state)) return tx;
        await new Promise(r => setTimeout(r, intervalMs));
      }
      throw new Error('Polling timeout');
    }
    
    // Step 1 — Get payment methods for customer's country
    app.get('/payment-methods/:country', async (req, res) => {
      const methods = await fetch(
        `${API}/public/configuration/payments/${req.params.country}`
      ).then(r => r.json());
      res.json(methods);
    });
    
    // Steps 2-3-4 — Customer picks method, initiate payment, poll result
    app.post('/pay', async (req, res) => {
      const { payment_method, phone, merchant_id, amount } = req.body;
    
      // Step 3 — Initiate direct payment
      const payment = await fetch(`${API}/mobile-money/payment/request`, {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer ' + token,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          amount,
          user_lang: 'fr',
          merchant_name: 'Ma Boutique',
          merchant_id,
          currency: 'XAF',
          country_name: 'Cameroon',
          payment_method,
          customer_msisdn: phone
        })
      }).then(r => r.json());
    
      // Step 4 — Poll for terminal state
      try {
        const tx = await pollStatus(payment.data.uuid);
        if (tx.state === 'DELIVERED') {
          res.json({ success: true, transaction: tx });
        } else {
          res.json({ success: false, state: tx.state, transaction: tx });
        }
      } catch (err) {
        res.status(408).json({ success: false, error: 'Payment timeout' });
      }
    });
    
    app.listen(3000);

    Preuve de livraison

    Des champs supplémentaires, ajoutés à vos appels de paiement existants, pour constituer automatiquement un dossier lorsqu'un porteur de carte conteste avoir reçu un bien ou service numérique. Aucun nouvel endpoint à intégrer : les champs viennent s'ajouter au paiement que vous envoyez déjà.

    Bientôt disponible : Ces champs ne sont pas encore traités par l'API. Vous pouvez déjà les envoyer sans provoquer d'erreur, mais ils n'ont aujourd'hui aucun effet : rien n'est encore enregistré ni contrôlé de notre côté. Quand cette fonctionnalité entrera en service, un champ manquant sera d'abord signalé dans la réponse — jamais rejeté du jour au lendemain. Vous aurez le temps de vous mettre en conformité avant qu'un champ ne devienne réellement obligatoire, et nous annoncerons la date à l'avance.

    Où ces champs s'appliqueront

    Sur les paiements par carte, où une contestation est possible. Les paiements Mobile Money et Cash restent inchangés : irrévocables, ils ne peuvent pas faire l'objet d'un litige.

    EndpointRailStatut prévu
    /stripe/payment/requestCarteRequis
    /bankcard/payment/requestCarteRequis
    /request-to-pay/payment/requestCarte possibleRequis
    /request-to-pay/payment/initializeCarte possibleRequis
    /request-to-pay/payment/linkCarte, payée plus tardRequis
    /mobile-money/payment/request, /cash/payment/requestIrrévocableAccepté, jamais requis

    Champs

    Tous s'ajoutent au premier niveau du corps de la requête, à côté de amount, merchant_id, etc. — pas de bloc imbriqué.

    ParamètreTypeRequisDescription
    external_idstringRequisVotre référence de commande. C'est ce qui vous permet de rapprocher nos transactions des vôtres — nous ne pouvons pas l'inventer à votre place.
    product_typestring (enum)RequisCe que vous livrez : DIGITAL_DOWNLOAD, DIGITAL_ACCESS, SERVICE ou PHYSICAL. Détermine automatiquement le mode de confirmation (voir ci-dessous) — vous ne le choisissez pas séparément.
    service_descriptionstringRequisUne phrase décrivant ce qui est vendu. C'est ce que lira l'analyste du réseau de carte en cas de litige.
    terms.accepted_atstring (ISO 8601)RequisHorodatage d'acceptation de vos CGV par le client.
    terms.versionstringRequisLa version des CGV acceptée.
    customer.emailstringConditionnelE-mail du payeur. Au moins l'un des deux — email ou phone — sera exigé ; les deux peuvent être fournis.
    customer.phonestringConditionnelTéléphone du payeur. Sur /stripe/payment/request et /bankcard/payment/request, peut aussi être fourni via le champ existant customer_msisdn, qui restera pris en charge — vous n'êtes pas obligé de migrer avant la date d'activation.
    customer.account_refstringOptionnelIdentifiant du client chez vous, 1 à 64 caractères. C'est le même bloc customer que sur le lien de paiement : il est déjà accepté aujourd'hui, avec customer.name, customer.email et customer.locale.
    customer.namestringOptionnelNom déclaré du client, 128 caractères au plus.

    Sur /request-to-pay/payment/request, /initialize et /link, le téléphone du payeur est déjà connu (le msisdn transmis) : rien à ajouter pour satisfaire la condition email/phone, sauf si vous voulez aussi fournir l'e-mail.

    Valeurs de product_type

    ValeurExempleMode de confirmation
    DIGITAL_DOWNLOADFilm, PDF, formation à téléchargerLien signé — le clic vaut confirmation
    DIGITAL_ACCESSAbonnement, accès ouvert dans un système tiersValidation par votre système
    SERVICEPrestation de serviceQR code présenté à la remise
    PHYSICALBien physique remis en main propreQR code présenté à la remise

    Aperçu du payload

    Sur /bankcard/payment/request, à titre d'illustration — les cinq derniers champs n'ont aujourd'hui aucun effet (voir l'encart ci-dessus).

    json
    {
      "amount": 15000,
      "merchant_id": 4821,
      "operation_code": "33",
      "currency": "XAF",
      "payment_method": "MOLLIE",
      "user_lang": "fr",
      "customer_msisdn": "+24106000000",
    
      "external_id": "CMD-88213",
      "product_type": "DIGITAL_DOWNLOAD",
      "service_description": "Formation Trésorerie PME, 4 modules vidéo",
      "customer": { "email": "jean@example.com", "phone": "+24106000000" },
      "terms": { "accepted_at": "2026-09-06T10:00:00Z", "version": "cgv-2026-03" }
    }

    SDKs & plugins officiels

    Des SDKs et plugins officiels sont disponibles pour intégrer ElyonPay dans vos projets. Ils gèrent automatiquement l'authentification, les appels API et la vérification du statut des paiements.

    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 requise — des webhooks optionnels sont toutefois disponibles en complément.

    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é (DELIVERED, REJECTED, CANCELLED...), affichez la page de confirmation ou d'erreur appropriée à votre client.

    Modèle pull : Aucun webhook n'est obligatoire : votre backend contrôle le timing de la vérification. Pour être notifié en temps réel, vous pouvez en plus fournir une URL de webhook — voir la section Webhooks.

    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 === 'DELIVERED') {
        // 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

    Paiements plateforme (Split)

    Une plateforme (marketplace) peut encaisser un paiement pour le compte de ses marchands. ElyonPay répartit automatiquement les fonds entre le sous-marchand et la plateforme : le sous-marchand reçoit le montant net et la plateforme prélève sa commission, en une seule transaction côté client. La répartition peut aussi viser plusieurs bénéficiaires à la fois, avec le paramètre splits.

    Fonctionnalité soumise à activation et contrat : Les paiements split ne sont pas ouverts par défaut. Cette fonctionnalité doit être activée par notre équipe commerciale pour apparaître dans votre interface, et son accès est conditionné à la signature explicite d'un contrat partenaire par le marchand. Tant que le contrat n'est pas signé et le mode plateforme activé sur votre compte, les endpoints et écrans décrits ci-dessous restent indisponibles. Contactez notre équipe commerciale pour lancer la démarche.

    Étape 1 — Créer vos sous-marchands

    Avant d'encaisser pour le compte d'un marchand, vous devez le déclarer comme sous-marchand de votre plateforme. Deux méthodes sont disponibles :

    • Depuis le dashboard — dans la section Sous-marchands de votre tableau de bord plateforme, ajoutez un marchand via le formulaire (identité, pays, frais par défaut). Idéal pour une gestion manuelle.
    • Via l'API — créez vos sous-marchands par programmation avec l'endpoint dédié ci-dessous. Idéal pour un onboarding automatisé.
    POST/api/merchant/sub-merchants

    Paramètres du body

    ParamètreTypeRequisDescription
    namestringRequisNom commercial du sous-marchand
    country_codestringRequisCode pays ISO 3166 (ex. CM)
    citystringRequisVille
    addressstringRequisAdresse
    typestringRequisType d'activité (ex. RETAIL)
    owner_emailstringRequisE-mail du propriétaire du compte
    owner_phone_numberstringRequisTéléphone du propriétaire
    owner_first_namestringRequisPrénom du propriétaire
    owner_last_namestringRequisNom du propriétaire
    owner_passwordstringRequisMot de passe initial du compte propriétaire
    default_marketplace_fee_percentnumberOptionnelCommission par défaut (%) prélevée sur les paiements de ce sous-marchand. Sinon, les frais par défaut de la plateforme s'appliquent
    bash
    curl -X POST https://api.elyonpay.org/api/merchant/sub-merchants \
      -H "Authorization: Bearer <your_jwt_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Boutique ABC",
        "country_code": "CM",
        "city": "Douala",
        "address": "123 Rue Commerce",
        "type": "RETAIL",
        "owner_email": "owner@boutique-abc.com",
        "owner_phone_number": "+237600000000",
        "owner_first_name": "Jean",
        "owner_last_name": "Dupont",
        "owner_password": "s3cur3-p4ssword",
        "default_marketplace_fee_percent": 5.00
      }'
    json
    {
      "merchant_id": 725,
      "uuid": "a1b2c3d4-...",
      "name": "Boutique ABC",
      "owner_email": "owner@boutique-abc.com",
      "owner_phone": "+237600000000",
      "kyb_required": true,
      "default_fee_percent": "5.00"
    }

    Notez le merchant_id retourné : c'est l'identifiant que vous passerez dans onbehalfof pour encaisser pour ce marchand. Le sous-marchand doit avoir un compte de payout configuré (pour recevoir les fonds) ; sa vérification KYB peut par ailleurs être requise avant la mise en production.

    Gérer vos sous-marchands

    MéthodeEndpointDescription
    GET/api/merchant/sub-merchantsLister vos sous-marchands
    GET/api/merchant/sub-merchants/{id}Détail d'un sous-marchand
    PATCH/api/merchant/sub-merchants/{id}/feesModifier sa commission par défaut

    Étape 2 — Encaisser pour un sous-marchand

    Créez le paiement normalement (voir Créer un paiement), en ajoutant le paramètre onbehalfof contenant l'id ou le code partner du sous-marchand. ElyonPay crée alors un paiement réparti.

    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",
        "webhook": "https://yoursite.com/webhooks/elyonpay",
        "onbehalfof": 725
      }'

    Comment la commission est calculée

    La commission prélevée par la plateforme est résolue dans cet ordre de priorité :

    1. Le paramètre fees fourni dans l'appel (montant exact, prioritaire s'il est présent).
    2. Sinon, la commission par défaut du sous-marchand (default_marketplace_fee_percent).
    3. Sinon, la commission par défaut configurée sur la plateforme.
    4. Si aucune source n'est disponible, la requête est rejetée (erreur 400).

    La commission doit être positive et strictement inférieure au montant, et respecter les plafonds définis sur la plateforme. Le sous-marchand reçoit amount − commission, la plateforme reçoit la commission.

    Exemple : pour amount = 15 000 XAF et une commission de 5 %, le sous-marchand reçoit 14 250 XAF et la plateforme 750 XAF. La répartition est disponible dans le détail de la transaction et dans le webhook (data.split).

    Sous-marchand encaissant directement

    Un sous-marchand peut aussi initier lui-même un paiement, avec sa propre clé API, sans passer par la plateforme. Dans ce cas, n'ajoutez pas onbehalfof : le split vers la plateforme parente s'applique automatiquement, avec les mêmes règles de commission.

    Répartir entre plusieurs bénéficiaires

    onbehalfof désigne un seul sous-marchand. Pour répartir un même encaissement entre plusieurs bénéficiaires, envoyez splits : un tableau d'entrées { merchant, percent }, où merchant est l'id ou le code partner du bénéficiaire. Disponible sur les liens de paiement (request-to-pay) et sur les paiements par carte. Les paiements en espèces ne sont pas répartis.

    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",
        "splits": [
          { "merchant": 725, "percent": 60 },
          { "merchant": "PART-EGT-00042", "percent": 25 }
        ]
      }'

    Le payeur paie 15 000 XAF : le premier bénéficiaire reçoit 9 000, le second 3 750, et la plateforme garde le reste, soit 2 250. Ce reste est une soustraction et non un pourcentage, ce qui rend la répartition exacte à l'unité sans règle d'arrondi : si trois parts de 33,33 % laissent une unité orpheline, elle reste à la plateforme.

    La plateforme doit toujours garder une part strictement positive. Ce n'est pas une règle commerciale : c'est sa part qui porte le coût réel de l'encaissement. Sans elle, ce coût tomberait sur un bénéficiaire qui n'a pas choisi le moyen de paiement.

    Ce que amount veut dire : split_mode

    Une seule question détermine tout le calcul : amount est-il ce que le payeur paie, ou ce que les destinataires reçoivent ?

    split_modeamountQuand l'utiliser
    SUBTRACTIVEdéfautCe que le payeur paie. Les parts sont prélevées dedans et leur somme égale le montant.Le cas courant : vous annoncez un prix à votre client, vous l'encaissez, vous le répartissez.
    ADDITIVECe que le destinataire principal reçoit. Les parts s'ajoutent par-dessus et le payeur paie davantage.Une somme due à un tiers qui n'a pas à supporter vos frais : une taxe, un reversement réglementaire. Le destinataire touche son montant nominal au franc près, quel que soit le barème appliqué autour.

    En mode ADDITIVE, deux champs supplémentaires sont nécessaires. principal nomme qui reçoit le montant lui-même — onbehalfof fait aussi l'affaire, puisqu'il dit déjà pour le compte de qui vous encaissez. Et votre plateforme doit figurer dans splits avec sa propre part : c'est elle qui absorbe l'écart entre le coût de rail estimé et le coût réel, connu seulement au règlement.

    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": 25000,
        "split_mode": "ADDITIVE",
        "principal": 931,
        "user_lang": "fr",
        "msisdn": "+237600000001",
        "success": "https://yoursite.com/success",
        "error": "https://yoursite.com/error",
        "splits": [
          { "merchant": 725, "percent": 8 }
        ]
      }'

    Le bénéficiaire 931 reçoit exactement 25 000 XAF. La plateforme 725 prend 8 % de ce montant, soit 2 000 XAF, en surcharge. Le payeur règle 27 000 XAF, plus les commissions ElyonPay, qui lui sont également imputées. En mode additif, aucun bénéficiaire autre que votre plateforme ne supporte nos frais : chacun touche sa part nominale.

    Règles de la répartition

    • Le compte appelant doit être une plateforme, et chaque bénéficiaire doit lui appartenir.
    • Chaque bénéficiaire doit avoir un compte de versement configuré, sans quoi sa part resterait impayable.
    • Un même bénéficiaire ne peut apparaître qu'une fois : additionnez ses pourcentages vous-même.
    • Chaque percent doit être strictement supérieur à 0, et la part qui en résulte doit valoir au moins une unité monétaire après arrondi.
    • En SUBTRACTIVE, la plateforme ne figure pas dans splits : elle reçoit le reste. En ADDITIVE, elle doit au contraire y figurer.
    • Si un plafond de commission est configuré sur votre plateforme, il s'applique à sa part, exactement comme aux frais de onbehalfof.

    Codes d'erreur

    SituationCode
    Le compte appelant n'est pas une plateforme, ou le sous-marchand appartient à une autre plateforme403
    Sous-marchand introuvable (id ou code partner)404
    Commission invalide (négative, ≥ montant, plafond dépassé) ou aucun compte de payout configuré400
    splits vide, percent ≤ 0, ou part arrondissant à zéro400
    Un même bénéficiaire apparaît deux fois dans splits400
    La somme des parts ne laisse rien à la plateforme, qui porte le coût de l'encaissement400
    Mode ADDITIVE sans principal, ou sans part pour la plateforme elle-même400
    Un bénéficiaire de splits n'appartient pas à la plateforme appelante403

    Versements

    Une fois un paiement livré, ElyonPay vous reverse votre part. Le moment où cet argent quitte nos comptes dépend du mode de versement réglé sur le vôtre.

    Le mode de versement est une condition commerciale, fixée par ElyonPay sur votre compte. Ce n'est pas un paramètre d'API : vous ne pouvez pas le choisir par requête, et il n'apparaît pas dans les réponses. Pour en changer, parlez-en à votre interlocuteur commercial.

    Les quatre modes de versement

    ModeQuand les fonds partentCe que cela implique
    INSTANTdéfautDès que possible après la livraison du paiement.Vous êtes payé au plus vite, au palier tarifaire instantané, qui est le plus cher.
    DELAYEDÀ la date de règlement de l'établissement de paiement, automatiquement.L'attente a une fin connue d'avance et personne n'a rien à faire pour qu'elle arrive. Palier tarifaire standard.
    MANUALQuand un opérateur ElyonPay libère le versement.Réservé aux comptes dont les versements font l'objet d'un contrôle avant départ. Palier tarifaire standard.
    WALLETJamais par vente. Le montant net est crédité à votre solde chez nous, et n'en sort que par vos demandes de décaissement.Pour les comptes dont les encaissements sont l'argent de leurs clients, reversé plus tard. Palier tarifaire standard.

    Un encaissement par virement bancaire prend toujours le palier standard, même sur un compte en mode INSTANT : un virement ne se règle pas instantanément, quel que soit le mode.

    Compte en mode wallet : consulter son solde

    Un compte en mode wallet dispose d'un endpoint dédié, appelable avec sa clé d'API comme ses encaissements.

    bash
    curl -X GET https://api.elyonpay.org/api/wallet/balance \
      -H "Authorization: Bearer <your_jwt_token>"
    json
    {
      "currency": "XAF",
      "balance": 1250000,
      "pending_release": 300000,
      "available": 950000,
      "release_delay_hours": 72,
      "as_of": "2026-10-20T17:12:04+00:00"
    }
    ChampSignification
    currencyLa devise du solde, celle du pays de votre compte.
    balanceTout ce que nous détenons pour vous, disponible ou non.
    pending_releaseLa part de ce solde issue de dépôts trop récents pour être décaissés.
    availableCe que vous pouvez décaisser maintenant : balance − pending_release.
    release_delay_hoursLe délai de disponibilité appliqué à votre compte, en heures.
    as_ofL'instant du calcul, au format ISO 8601.

    Le délai de disponibilité vaut 72 heures en production. Il est ramené à 0 en sandbox, pour que vous puissiez déposer et décaisser dans la même séance de tests.

    L'endpoint répond 404 si votre compte n'est pas en mode wallet, et 403 si la clé utilisée n'appartient pas à un marchand. Rappel : sur un compte en mode wallet, customer.account_ref est obligatoire à chaque encaissement, sans quoi le dépôt est refusé en 422 PLAYER_REF_REQUIRED — c'est lui qui lie le dépôt au client, puis le décaissement au numéro qui a déposé.

    Webhooks

    ElyonPay peut notifier votre serveur en temps réel à chaque changement d'état d'une transaction, via une requête HTTP POST (serveur à serveur). Les webhooks sont optionnels : ils complètent le modèle pull (polling) mais ne le remplacent pas.

    Activer les webhooks

    Aucune configuration globale n'est nécessaire : l'URL de webhook se fournit transaction par transaction, via le paramètre optionnel webhook lors de la création du paiement. L'URL doit être une URL HTTPS valide et accessible publiquement.

    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",
        "webhook": "https://yoursite.com/webhooks/elyonpay"
      }'

    Événements notifiés

    Une notification est envoyée à chaque fois que la transaction atteint l'un des états suivants :

    ÉvénementÉtatDescription
    transaction.pendingPENDINGPaiement initié, en attente de confirmation
    transaction.deliveredDELIVEREDPaiement confirmé, fonds transférés au marchand
    transaction.declinedDECLINEDPaiement refusé par l'opérateur
    transaction.cancelledCANCELLEDPaiement annulé par le client ou le système

    Format de la notification

    Chaque notification est une requête POST en JSON, accompagnée des en-têtes suivants :

    En-têteDescription
    Content-TypeToujours application/json
    X-Mip-EventNom de l'événement (ex. transaction.delivered)
    X-Mip-DeliveryIdentifiant unique de la notification — utilisez-le pour dédupliquer
    X-Mip-AttemptNuméro de la tentative (1 à 5)

    Exemple de payload

    json
    {
      "event": "transaction.delivered",
      "created_at": "2026-07-08T18:45:12+02:00",
      "data": {
        "transaction": "CI032667e43abf11",
        "state": "DELIVERED",
        "amount": 15000,
        "currency": "XAF",
        "operation_code": "OP-2026-000123",
        "merchant_id": 42,
        "external_id": "CMD-2026-0042",
        "customer": {
          "account_ref": "CLT-1001",
          "name": "Jean Mballa",
          "email": "jean@example.com",
          "phone": "+237670000001"
        },
        "creation_date": "2026-07-08T18:40:03+02:00",
        "validation_date": "2026-07-08T18:44:57+02:00",
        "delivery_date": "2026-07-08T18:45:10+02:00"
      }
    }

    Le payload reprend vos propres références quand vous les avez fournies à la création : external_id (votre commande) et le bloc customer (votre client final : account_ref, name, email ; phone est le numéro réellement débité). Les clés sont toujours présentes, nulles sinon.

    Pour les transactions marketplace (paiement réparti entre plusieurs marchands), le payload contient en plus un tableau data.split listant la part de chaque marchand (merchant_id, amount) — voir Paiements plateforme.

    Accusé de réception et retries

    Votre serveur doit répondre avec un code HTTP 2xx en moins de 10 secondes. Toute autre réponse (4xx, 5xx, timeout, erreur réseau) est considérée comme un échec et déclenche une nouvelle tentative selon le calendrier suivant :

    TentativeDélai après l'échec précédent
    1Immédiate (au changement d'état)
    23 secondes
    330 secondes
    460 secondes
    590 secondes

    Après 5 tentatives infructueuses, la notification est définitivement abandonnée. Le statut de la transaction reste toujours consultable via GET /api/transactions/{uuid}.

    Vérification obligatoire : Un webhook peut arriver en retard, en double ou dans le désordre. Avant de livrer un bien ou un service, confirmez toujours l'état de la transaction avec GET /api/transactions/{uuid} — ne vous fiez jamais uniquement au contenu du webhook.

    Exemple de réception (Node.js / Express)

    javascript
    app.post('/webhooks/elyonpay', express.json(), async (req, res) => {
      // 1. Acknowledge immediately — heavy processing must happen async
      res.sendStatus(200);
    
      const event = req.headers['x-mip-event'];       // e.g. "transaction.delivered"
      const deliveryId = req.headers['x-mip-delivery']; // unique per notification
    
      // 2. Deduplicate: the same delivery may be received more than once
      if (await alreadyProcessed(deliveryId)) return;
    
      // 3. Verify the state server-side before acting on it
      const { transaction } = req.body.data;
      const status = await fetch(
        'https://api.elyonpay.org/api/transactions/' + transaction,
        { headers: { Authorization: 'Bearer ' + token } }
      ).then((r) => r.json());
    
      if (status.state === 'DELIVERED') {
        await fulfillOrder(transaction);
      }
    });

    Bonnes pratiques

    • Répondez vite — Renvoyez le code 2xx avant tout traitement long : au-delà de 10 secondes, la notification est considérée comme échouée et sera rejouée.
    • Dédupliquez — Stockez l'en-tête X-Mip-Delivery et ignorez les notifications déjà traitées — les retries peuvent provoquer des doublons.
    • Vérifiez côté serveur — Utilisez le webhook comme un signal, puis confirmez l'état via GET /api/transactions/{uuid} avant toute action métier.
    • Gardez le polling en filet de sécurité — Si votre serveur est indisponible plus de ~3 minutes, la notification est abandonnée : le polling reste la source de vérité.

    Décaissements (wallet)

    En mode wallet, les dépôts de vos clients ne vous sont pas reversés un par un : ils créditent votre solde chez ElyonPay. Vous en faites ensuite sortir l'argent par API, vers le Mobile Money de vos clients (un retrait, un remboursement) ou vers votre propre compte (votre marge). Ce mode s'adresse aux marchands qui détiennent l'argent de leurs clients et le leur rendent plus tard.

    Fonctionnalité soumise à activation et contrat : le mode wallet n'est pas ouvert par défaut. Notre équipe l'active sur votre compte après signature d'un contrat, qui fixe aussi vos plafonds de décaissement. Contactez-nous pour l'ouvrir.

    Comment ça marche

    1. Dépôt. Votre client paie comme pour tout paiement (voir Créer un paiement), avec customer.account_ref si vous voulez retrouver ses dépôts. Une fois le paiement confirmé par l'opérateur, son montant net des frais est crédité sur votre solde.
    2. Disponibilité. Un dépôt devient décaissable 72 heures après son crédit en production, immédiatement en sandbox. Le délai en vigueur est renvoyé par GET /api/wallet/balance (release_delay_hours).
    3. Décaissement. Vous nommez le numéro Mobile Money à payer. Il doit vous avoir payé : un dépôt confirmé depuis ce numéro. ElyonPay le paie chez l'opérateur de ce dépôt, Orange Money ou MTN MoMo.
    4. Montant. Il quitte votre solde dès la demande, et n'y revient que si l'opérateur refuse le virement (statut FAILED). Le montant demandé est exactement celui qui est envoyé : les frais ont été prélevés au dépôt.

    Le numéro à payer

    ElyonPay ne garde pas de fiche de vos clients : chaque décaissement dit lui-même où va l'argent, et nous vérifions seulement que ce numéro vous a déjà payé. L'argent ne revient ainsi que vers un numéro qui vous a payé. Un client qui change de numéro dépose depuis le nouveau ; une fois ce dépôt confirmé, ce numéro est payable lui aussi. Un paiement par carte ne rend aucun numéro payable.

    Gardez le numéro de vos clients chez vous : prenez le numéro à payer dans le compte de votre client, authentifié chez vous, jamais dans une réponse ou un webhook d'ElyonPay. Un dépôt fait par quelqu'un d'autre sous l'account_ref d'un client ne détourne alors rien : c'est vous qui choisissez le numéro.

    Authentification

    Faire sortir de l'argent exige votre clé d'API, et elle seule : créer un décaissement, envoyer un lot ou relancer avec une session du tableau de bord ou un JWT renvoie 403 API_KEY_REQUIRED. Le solde et le journal se lisent avec la clé ou avec la session du titulaire du compte.

    bash
    Authorization: Bearer pk_live_...
    Bonnes pratiques : votre clé est dans votre tableau de bord, rubrique Développeur. Gardez-la sur votre serveur, jamais dans un navigateur ni dans une application mobile. Si elle a pu fuiter, régénérez-la : l'ancienne cesse aussitôt de fonctionner. ElyonPay exécute toute demande valide faite avec votre clé : validez vos demandes chez vous (double contrôle, confirmation) avant d'appeler l'API.

    Endpoints

    MéthodeCheminRôle
    GET/api/wallet/balanceSolde, en attente, disponible
    POST/api/wallet/payoutsCréer un décaissementClé d'API
    POST/api/wallet/payouts/batchEnvoyer un lot de décaissementsClé d'API
    GET/api/wallet/payoutsJournal, filtré et paginé
    GET/api/wallet/payouts/{id|reference}Un décaissement
    POST/api/wallet/payouts/{id|reference}/retryRelancer un décaissement FAILEDClé d'API

    Consulter le solde

    GET/api/wallet/balance
    json
    {
      "currency": "XAF",
      "balance": 1250000,
      "pending_release": 300000,
      "available": 950000,
      "release_delay_hours": 72,
      "as_of": "2026-11-02T17:12:04+00:00"
    }
    ChampDescription
    balanceCe que nous détenons pour vous.
    pending_releaseDépôts crédités depuis moins de release_delay_hours, pas encore décaissables.
    availableCe que vous pouvez décaisser maintenant : balance − pending_release.
    release_delay_hoursDélai avant qu'un dépôt devienne décaissable.
    as_ofInstant du calcul, ISO 8601.

    Les montants sont des entiers dans l'unité de la devise (XAF : le franc). Un compte qui n'est pas en mode wallet reçoit 404.

    Créer un décaissement

    POST/api/wallet/payouts
    ParamètreTypeRequisDescription
    referencestringRequisVotre identifiant unique du décaissement, 1 à 64 caractères. C'est votre clé d'idempotence : la même demande rejouée sous la même référence rend le décaissement existant au lieu d'en créer un second.
    beneficiary_typestringOptionnelCUSTOMER (défaut) pour un client, MERCHANT pour votre marge, versée sur votre compte de versement enregistré chez ElyonPay.
    msisdnstringConditionnelObligatoire pour CUSTOMER : le numéro Mobile Money à payer, sous toute forme (+237 6…, 2376…, 6…). Il doit avoir fait un dépôt confirmé chez vous ; il est payé chez l'opérateur de ce dépôt.
    account_refstringOptionnelVotre identifiant du client, 64 caractères au plus : une étiquette pour votre journal et vos filtres, jamais ce qui décide où part l'argent.
    beneficiary_namestringOptionnelNom du bénéficiaire, 128 caractères au plus. Sinon, le nom déclaré au dépôt de ce numéro.
    amountintegerRequisMontant, entier strictement positif, dans l'unité de la devise.
    descriptionstringOptionnel255 caractères au plus. Selon l'opérateur, reprise dans le SMS reçu par le client.
    allow_duplicatebooleanOptionneltrue pour confirmer un doublon détecté (409 DUPLICATE_SUSPECTED).
    webhookstringOptionnelURL https, 500 caractères au plus, qui recevra l'issue du décaissement (voir plus bas).
    bash
    curl -X POST https://api.elyonpay.org/api/wallet/payouts \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "reference": "PAY-2026-11-000123",
        "msisdn": "+237670000101",
        "account_ref": "CLT-1001",
        "amount": 25000,
        "description": "Retrait du 02/11",
        "webhook": "https://yoursite.com/elyonpay/payouts"
      }'

    Réponse 201 quand le décaissement est créé, 200 quand la même demande est rejouée : après un timeout, rejouez sans crainte. Une référence déjà prise par une demande différente est refusée (409 REFERENCE_REUSED).

    json
    {
      "id": "8a6eae66-4c7d-4c96-8683-b56e895f4e28",
      "reference": "PAY-2026-11-000123",
      "batch_ref": null,
      "beneficiary_type": "CUSTOMER",
      "account_ref": "CLT-1001",
      "beneficiary_name": "Jean Mballa",
      "msisdn": "237670000101",
      "payment_method": "MTN_MONEY",
      "amount": 25000,
      "currency": "XAF",
      "description": "Retrait du 02/11",
      "status": "QUEUED",
      "attempt": 1,
      "failure_reason": null,
      "operator_reference": null,
      "created_at": "2026-11-02T20:29:10+00:00",
      "updated_at": "2026-11-02T20:29:10+00:00",
      "completed_at": null
    }
    ChampDescription
    idIdentifiant ElyonPay du décaissement.
    msisdn, payment_methodLe numéro payé, chiffres seuls avec l'indicatif, et son opérateur (ORANGE_MONEY ou MTN_MONEY), repris de son dépôt.
    account_refVotre étiquette client, si vous l'avez donnée.
    beneficiary_nameLe nom de la demande, sinon celui déclaré au dépôt (customer.name).
    statusVoir Cycle de vie ci-dessous.
    attemptNuméro de la tentative : 1, puis +1 à chaque relance.
    failure_reasonPourquoi un décaissement a échoué ou est en revue.
    operator_referenceRéférence du virement chez l'opérateur, une fois envoyé.
    completed_atDate de l'issue finale (SUCCEEDED ou FAILED).

    Envoyer un lot

    POST/api/wallet/payouts/batch

    Pour les paiements de fin de période. Chaque élément de items a les mêmes champs qu'un décaissement seul. batch_ref (64 caractères au plus) regroupe les lignes dans le journal ; le webhook du lot vaut pour chaque ligne, celui d'une ligne l'emporte.

    json
    {
      "batch_ref": "OCT-2026",
      "webhook": "https://yoursite.com/elyonpay/payouts",
      "items": [
        { "reference": "OCT-2026-0001", "msisdn": "+237670000101", "account_ref": "CLT-1001", "amount": 12000 },
        { "reference": "OCT-2026-0002", "msisdn": "+237690000102", "account_ref": "CLT-1002", "amount": 40000 },
        { "reference": "OCT-2026-MARGE", "beneficiary_type": "MERCHANT", "amount": 300000 }
      ]
    }

    Chaque ligne est contrôlée et réservée seule, avec son propre résultat : CREATED, EXISTING (déjà créée, lot rejoué) ou REFUSED avec son erreur. Deux refus portent sur le lot entier et ne créent rien : trop de lignes (BATCH_TOO_LARGE), ou total des nouvelles lignes au-dessus du disponible (BATCH_EXCEEDS_BALANCE). Un lot rejoué après une coupure ne recrée rien.

    json
    {
      "batch_ref": "OCT-2026",
      "results": [
        { "index": 0, "reference": "OCT-2026-0001", "result": "CREATED", "payout": { "id": "3f0c...", "status": "QUEUED" } },
        { "index": 1, "reference": "OCT-2026-0002", "result": "REFUSED", "error": { "error_code": "MSISDN_NOT_ELIGIBLE", "message": "..." } },
        { "index": 2, "reference": "OCT-2026-MARGE", "result": "CREATED", "payout": { "id": "9b27...", "status": "QUEUED" } }
      ],
      "summary": { "total": 3, "created": 2, "existing": 0, "refused": 1 }
    }

    La réponse est 200 même quand des lignes sont refusées : lisez le résultat de chacune.

    Suivre vos décaissements

    GET/api/wallet/payouts
    ParamètreTypeRequisDescription
    statusstringOptionnelQUEUED, PROCESSING, SUCCEEDED, FAILED ou ON_HOLD.
    account_refstringOptionnelLes décaissements portant cette étiquette client.
    batch_refstringOptionnelLes lignes d'un lot.
    from, toISO 8601OptionnelPériode de création ; to est exclu.
    limit, offsetintegerOptionnelPagination : limit de 1 à 200 (50 par défaut).
    bash
    curl "https://api.elyonpay.org/api/wallet/payouts?status=FAILED&from=2026-10-01&to=2026-11-01&limit=50&offset=0" \
      -H "Authorization: Bearer pk_live_..."
    
    { "items": [ { ... } ], "limit": 50, "offset": 0 }

    Le plus récent d'abord. Un décaissement se lit aussi seul, par son id ou par votre reference : GET /api/wallet/payouts/PAY-2026-11-000123. C'est la source de vérité : en cas de doute (webhook manqué, timeout), relisez-le.

    Relancer un décaissement

    POST/api/wallet/payouts/{id|reference}/retry

    Seul un décaissement FAILED se relance (sinon 409 NOT_RETRYABLE). Il garde votre référence, repart en QUEUED avec une nouvelle tentative, et le montant est de nouveau réservé sur votre solde : solde et plafonds sont recontrôlés. Il part vers le numéro de la demande. Réponse 202 avec le décaissement.

    Cycle de vie

    StatutSignificationSolde
    QUEUEDAccepté, en attente d'envoi à l'opérateur.Réservé
    PROCESSINGEnvoyé à l'opérateur, en attente de sa réponse.Réservé
    SUCCEEDEDPayé. Statut final.Sorti
    FAILEDRefusé par l'opérateur. Statut final, sauf relance.Rendu
    ON_HOLDEn revue chez ElyonPay : l'opérateur n'a pas donné de réponse certaine, ou un contrôle a bloqué l'envoi. Nous vérifions auprès de l'opérateur et tranchons : payé, rendu ou renvoyé.Réservé
    Pourquoi l'argent reste réservé sans réponse : une panne ou un timeout ne vaut jamais refus. Le montant ne revient sur votre solde que sur un refus certain de l'opérateur ; sinon il reste réservé jusqu'à une réponse. C'est ce qui empêche de payer deux fois la même somme.

    Webhooks de décaissement

    Avec un webhook dans la demande, ElyonPay envoie un POST JSON à chaque issue. Rien n'est envoyé pour QUEUED ni PROCESSING.

    ÉvénementQuandSolde
    payout.succeededL'opérateur a payé, ou notre revue l'a confirmé.L'argent est sorti
    payout.failedL'opérateur a refusé, ou notre revue a établi que rien n'est parti.Montant rendu, relance possible
    payout.on_holdLe décaissement passe en revue.Montant toujours réservé

    Un décaissement en revue reçoit ensuite une seconde notification, payout.succeeded ou payout.failed. data est l'objet décaissement complet, plus merchant_id (votre code partenaire).

    json
    {
      "event": "payout.succeeded",
      "created_at": "2026-11-02T20:36:14+00:00",
      "data": {
        "id": "8a6eae66-4c7d-4c96-8683-b56e895f4e28",
        "reference": "PAY-2026-11-000123",
        "account_ref": "CLT-1001",
        "amount": 25000,
        "currency": "XAF",
        "status": "SUCCEEDED",
        "operator_reference": "5b1f0c2e-8d3a-4c47-9e21-3f6a7d2b9c10",
        "completed_at": "2026-11-02T20:36:14+00:00",
        "merchant_id": "PART-EGT-00042"
      }
    }
    En-têteDescription
    X-Mip-EventL'événement.
    X-Mip-DeliveryIdentifiant de la notification, le même d'une tentative à l'autre : dédupliquez sur lui.
    X-Mip-AttemptNuméro de la tentative.

    Vérifier auprès d'ElyonPay

    Le webhook vous prévient, il ne fait pas foi : il n'est pas signé. Avant d'agir, relisez le décaissement par son data.id avec votre clé d'API, et décidez sur le status que renvoie l'API. Une notification qui ne viendrait pas de nous ne provoque ainsi qu'une relecture.

    javascript
    app.post('/elyonpay/payouts', express.json(), async (req, res) => {
      res.sendStatus(200); // répondez vite, traitez ensuite
    
      const { data } = req.body;
      const answer = await fetch(
        'https://api.elyonpay.org/api/wallet/payouts/' + encodeURIComponent(data.id),
        { headers: { Authorization: 'Bearer ' + process.env.ELYONPAY_API_KEY } }
      );
      const payout = await answer.json();
    
      // Seul le statut relu chez ElyonPay compte.
      if (payout.status === 'SUCCEEDED') await markPayoutPaid(payout.reference);
      if (payout.status === 'FAILED') await markPayoutFailed(payout.reference);
    });

    Répondez par un code 2xx. Sinon, nous réessayons quatre fois, après 3 s, 30 s, 60 s et 90 s. Une notification manquée ne change rien au décaissement : relisez-le par l'API.

    Contrôles et plafonds

    Chaque demande est contrôlée avant de réserver quoi que ce soit, puis recontrôlée au moment de l'envoi (compte en revue) :

    ContrôleRefus
    Montant au plus égal au plafond par décaissementAMOUNT_ABOVE_LIMIT
    Numéro fourni, qui vous a payé, chez Orange Money ou MTN MoMoMSISDN_REQUIRED, MSISDN_NOT_ELIGIBLE, RAIL_NOT_SUPPORTED
    Montant au plus égal au disponibleINSUFFICIENT_FUNDS
    Cumul du jour au plus égal au plafond journalier du walletDAILY_LIMIT_EXCEEDED
    Cumul du jour vers ce numéro au plus égal au plafond journalier par numéroDESTINATION_DAILY_LIMIT_EXCEEDED
    Pas le même montant vers le même numéro dans la fenêtre de doublonDUPLICATE_SUSPECTED

    Vos plafonds (par décaissement, par jour, par numéro et par jour, fenêtre de doublon, lignes par lot) sont fixés dans votre contrat et affichés dans votre tableau de bord. Le jour est le jour civil à Douala. Un décaissement FAILED ne compte plus dans les plafonds ; une relance compte le jour où elle est faite.

    Erreurs

    Les refus de l'API wallet ont leur propre format : un error_code stable, un message lisible, et les détails utiles au même niveau.

    json
    {
      "error_code": "INSUFFICIENT_FUNDS",
      "message": "The available wallet balance does not cover this payout.",
      "available": 950000,
      "pending_release": 300000
    }
    CodeHTTPDescription
    API_KEY_REQUIRED403Créer, envoyer un lot ou relancer sans la clé d'API du marchand (session du tableau de bord, JWT).
    OWNER_ONLY403Lecture des décaissements par un autre utilisateur que le titulaire du compte (un caissier, par exemple).
    MERCHANT_BLOCKED403Votre compte est en revue : les décaissements sont suspendus. Contactez-nous.
    NOT_A_WALLET404Le compte n'est pas en mode wallet.
    NOT_FOUND404Aucun décaissement sous cet id ou cette référence.
    INVALID_JSON400Le corps n'est pas un objet JSON (ou, pour un lot, n'a pas de liste items).
    STATUS_INVALID, FROM_INVALID, TO_INVALID400Filtre du journal illisible.
    REFERENCE_REQUIRED, REFERENCE_INVALID422reference absente, vide ou de plus de 64 caractères.
    AMOUNT_INVALID422amount n'est pas un entier strictement positif.
    AMOUNT_ABOVE_LIMIT422Montant au-dessus du plafond par décaissement (détail : max_amount).
    BENEFICIARY_TYPE_INVALID422beneficiary_type autre que CUSTOMER ou MERCHANT.
    MSISDN_REQUIRED422Pas de msisdn pour un décaissement à un client.
    ACCOUNT_REF_INVALID, BENEFICIARY_NAME_INVALID422account_ref ou beneficiary_name trop long, ou avec un caractère de contrôle.
    DESCRIPTION_INVALID, BATCH_REF_INVALID, WEBHOOK_INVALID422Champ trop long, caractère de contrôle, ou webhook qui n'est pas une URL https.
    MSISDN_NOT_ELIGIBLE422Ce numéro ne vous a jamais payé : aucun dépôt Mobile Money confirmé depuis lui (détail : msisdn).
    RAIL_NOT_SUPPORTED422Le compte à payer n'est ni Orange Money ni MTN MoMo.
    MERCHANT_ACCOUNT_MISSING422Décaissement de marge sans compte de versement enregistré.
    INSUFFICIENT_FUNDS422Le disponible ne couvre pas le montant (détails : available, pending_release).
    DAILY_LIMIT_EXCEEDED422Plafond journalier du wallet atteint (détails : daily_limit, used_today).
    DESTINATION_DAILY_LIMIT_EXCEEDED422Plafond journalier de ce numéro atteint (détails : destination_daily_limit, used_today, msisdn).
    DUPLICATE_SUSPECTED409Même montant vers le même numéro dans la fenêtre de doublon (détails : duplicate_of, duplicate_created_at). Renvoyez avec allow_duplicate: true s'il est voulu.
    REFERENCE_REUSED409Cette référence porte déjà un décaissement différent (détail : payout).
    REFERENCE_DUPLICATED_IN_BATCH409La même référence apparaît deux fois dans le lot.
    NOT_RETRYABLE409Seul un décaissement FAILED se relance (détail : status).
    BATCH_EMPTY, INVALID_ITEM422Lot sans ligne, ou ligne qui n'est pas un objet.
    BATCH_TOO_LARGE422Trop de lignes dans le lot (détail : max_items). Rien n'est créé.
    BATCH_EXCEEDS_BALANCE422Le total des nouvelles lignes dépasse le disponible (détails : batch_total, available). Rien n'est créé.

    Dans votre tableau de bord

    La rubrique Wallet montre votre solde, vos mouvements et vos décaissements, filtrables par statut, par référence client et par période, avec vos plafonds en vigueur. Le bouton Exporter CSV sort toutes les lignes du filtre (séparateur point-virgule, UTF-8, heures en UTC). Aucun décaissement ne se crée ni ne se relance depuis le tableau de bord : seulement par l'API, avec votre clé.

    Tester en sandbox

    Même API sur https://api.elyonpay.net/api, avec la clé de votre compte sandbox et sans argent réel. Les dépôts y sont décaissables immédiatement (release_delay_hours vaut 0) : vous pouvez déposer, décaisser, recevoir les webhooks et essayer les refus de l'API (solde, plafonds, doublons) dans la même séance.

    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
    PLAYER_REF_REMOVED422player_ref n'est plus accepté : envoyez customer.account_ref
    PLAYER_NAME_REMOVED422player_name n'est plus accepté : envoyez customer.name
    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