react-sdk-feexpay v2 — Documentation officielle

SDK React pour l'intégration des paiements FeexPay dans vos applications web.

Table des matières

1. Introduction
2. Prérequis
3. Installation
4. Démarrage rapide
5. Référence API
   • Composant <FeexPay />
   • Props détaillées
   • Objet de retour du callback
   • Types exportés
6. Méthodes de paiement
7. Pays et opérateurs supportés
8. Exemples d'utilisation
9. Gestion des erreurs
10. Personnalisation du bouton
11. Changelog

1. Introduction

react-sdk-feexpay est une bibliothèque React qui permet d'intégrer la passerelle de paiement FeexPay en quelques lignes de code. Elle expose un composant clé-en-main qui affiche un bouton « Payer » et gère l'intégralité du tunnel de paiement : ouverture d'une modale, saisie des informations du payeur, sélection de l'opérateur, initiation de la transaction et retour de statut.

Cas d'usage typiques :

• Boutiques e-commerce sur les marchés d'Afrique de l'Ouest
• Collecte de paiements Mobile Money (MTN, Moov, Orange, Wave, etc.)
• Paiements par portefeuille numérique (Coris Money, Wave CI)
• Applications SaaS ou plateformes de services avec abonnements

Ce que le SDK gère pour vous :

• Sélection du pays et de l'opérateur
• Formatage automatique du numéro de téléphone
• Calcul des frais de transaction
• Polling du statut de paiement (toutes les 10 s, jusqu'à 2 min)
• Redirection après paiement (URL ou callback JavaScript)
• Gestion OTP (Orange Sénégal, Coris Money Bénin)
• Affichage iframe pour les opérateurs avec redirect (Wave, Orange CI/BF…)

2. Prérequis

| Dépendance | Version minimale | |---|---| | React | 19.0.0 | | react-dom | 19.0.0 | | Node.js | 18+ recommandé |

Le SDK inclut ses propres dépendances (axios, styled-components) ; vous n'avez pas à les installer séparément.

3. Installation

npm install react-sdk-feexpay

yarn add react-sdk-feexpay

pnpm add react-sdk-feexpay

Note : react et react-dom sont des peerDependencies. Ils doivent déjà être présents dans votre projet.

4. Démarrage rapide

import FeexPay from 'react-sdk-feexpay';

export default function CheckoutPage() {
  return (
    <FeexPay
      amount={5000}
      token="votre_token_api"
      id="identifiant_boutique"
      description="Commande #1234"
      callback={(result) => {
        if (result.status === 'SUCCESSFUL') {
          console.log('Paiement réussi !', result.reference);
        }
      }}
    />
  );
}

Ce snippet suffit pour afficher un bouton opérationnel. En cliquant dessus, la modale de paiement s'ouvre et guide l'utilisateur jusqu'à la confirmation.

5. Référence API

Composant <FeexPay />

C'est le composant principal (export par défaut). Il combine un bouton et la logique de paiement complète.

import FeexPay from 'react-sdk-feexpay';
// ou via l'alias nommé :
import { FeexPayButton } from 'react-sdk-feexpay';

FeexPayButton est un alias de FeexPay fourni pour la rétrocompatibilité avec la v1.

Props détaillées

Props obligatoires

| Prop | Type | Description | |---|---|---| | amount | number | Montant à encaisser, en unité entière (ex. 5000 pour 5 000 XOF). | | token | string | Token d'authentification API de votre boutique FeexPay. | | id | string | Identifiant unique de votre boutique FeexPay. |

Props optionnelles — Comportement

| Prop | Type | Défaut | Description | |---|---|---|---| | description | string | '' | Description de la transaction, visible dans le tableau de bord FeexPay. | | mode | 'LIVE' \| 'SANDBOX' | 'LIVE' | Mode de fonctionnement. Utilisez 'SANDBOX' pour les tests. | | currency | 'XOF' \| 'USD' \| 'CAD' \| 'XAF' | 'XOF' | Devise de la transaction. | | case | 'MOBILE' \| 'CARD' \| 'WALLET' | — | Force l'affichage d'une méthode de paiement unique, sans onglets. |

Props optionnelles — Callbacks et redirections

| Prop | Type | Description | |---|---|---| | callback | (response: CallbackResponse) => void | Fonction appelée côté client à la fin de la transaction (succès ou échec). Voir Objet de retour du callback. | | callback_url | string | URL de redirection après un paiement réussi. La référence est passée en query param : ?ref=<reference>. | | error_callback_url | string | URL de redirection après un paiement échoué. La référence est passée en query param : ?ref=<reference>. | | callback_info | Record<string, unknown> | Données métier arbitraires renvoyées intactes dans la réponse du callback (ex. { orderId: '42', userId: 'abc' }). |

Props optionnelles — Référence et personnalisation

| Prop | Type | Alias v1 | Description | |---|---|---|---| | reference | string | customId | Référence personnalisée de la transaction dans vos systèmes (idempotence). | | fieldsToHide | string[] | fields_to_hide | Liste de champs à masquer dans la modale. Valeurs possibles : 'name', 'email'. | | defaultValueField | Record<string, any> | — | Pré-remplit des champs de la modale. Clés supportées : country_iban ('BJ', 'CI', 'SN', 'TG', 'BF'), name, email. | | first_name | string | — | Pré-remplit le champ "Nom et Prénoms" de la modale. | | email | string | — | Pré-remplit le champ "Email" de la modale. |

Props optionnelles — Style du bouton

| Prop | Type | Description | |---|---|---| | buttonText | string | Texte personnalisé du bouton (défaut : "Payer X XOF"). | | buttonClass | string | Classes CSS Tailwind ou personnalisées appliquées au bouton. | | buttonStyles | React.CSSProperties | Styles inline appliqués au bouton. |

Objet de retour du callback

Lorsque la transaction se termine, la prop callback reçoit un objet avec les champs suivants :

{
  reference: string;        // Référence unique FeexPay de la transaction
  status: PaymentStatus;    // Statut final (voir ci-dessous)
  phoneNumber: string;      // Numéro de téléphone formaté du payeur
  reseau: string;           // Opérateur utilisé (ex. 'MTN', 'WAVE SN')
  callback_info: Record<string, unknown>; // Données métier passées via callback_info
  description: string;      // Description de la transaction
  transaction_id: string;   // Identifiant de transaction (= reference)
  message: string;          // Message de statut lisible
  amount: number;           // Montant de base (sans frais)
  currency: string;         // Devise (ex. 'XOF')
  first_name: string;       // Nom du payeur
  email: string;            // Email du payeur
}

Valeurs possibles de status :

| Valeur | Signification | |---|---| | 'SUCCESSFUL' / 'SUCCESS' | Paiement accepté et confirmé | | 'FAILED' | Paiement refusé ou annulé | | 'PENDING' | En attente de confirmation opérateur | | 'TIMEOUT' | Expiration de la vérification (120 s sans réponse) | | 'INSUFFICIENT_FUNDS' | Solde insuffisant chez le payeur |

Types exportés

Tous les types TypeScript du SDK sont disponibles à l'import :

import type {
  FeexPayProps,
  PaymentConfig,
  PaymentStatus,
  PaymentMethod,
  Network,
  Country,
  Currency,
  Transaction,
} from 'react-sdk-feexpay';

Network

type Network = 'MTN' | 'MOOV' | 'CELTIIS' | 'CORIS' | 'ORANGE' | 'WAVE' | 'FREE' | 'TOGOCOM';

Country

type Country = 'BENIN' | 'COTE_D_IVOIRE' | 'BURKINA_FASO' | 'CONGO_BRAZZAVILLE' | 'SENEGAL' | 'TOGO';

Currency

type Currency = 'XOF' | 'USD' | 'CAD' | 'XAF';

PaymentMethod

type PaymentMethod = 'MOBILE' | 'CARD' | 'WALLET';

6. Méthodes de paiement

| Méthode | Valeur case | Description | |---|---|---| | Mobile Money | 'MOBILE' | Paiement via l'opérateur mobile du payeur. Un message push ou USSD est envoyé sur son téléphone pour confirmation. | | Wallet | 'WALLET' | Paiement via portefeuille numérique. Coris Money (Bénin) ou Wave (Côte d'Ivoire). Nécessite un code OTP pour Coris. | | Carte bancaire | 'CARD' | Visa / Mastercard. Momentanément indisponible. |

Lorsque case n'est pas fourni, les trois onglets apparaissent dans la modale et le payeur choisit sa méthode.

7. Pays et opérateurs supportés

Mobile Money

| Pays | Opérateurs disponibles | Code pays | |---|---|---| | Bénin | MTN, Moov, Celtiis | BENIN | | Côte d'Ivoire | MTN CI, Orange CI | COTE_D_IVOIRE | | Burkina Faso | Moov BF, Orange BF | BURKINA_FASO | | Congo-Brazzaville | MTN CG | CONGO_BRAZZAVILLE | | Sénégal | Orange SN, Free SN, Wave SN | SENEGAL | | Togo | Togocom TG, Moov TG | TOGO |

Wallet

| Pays | Réseau Wallet | |---|---| | Bénin | Coris Money (CORIS) | | Côte d'Ivoire | Wave (WAVE) |

Note : Pour Orange Sénégal, le payeur doit obtenir un code OTP en composant *144*391# depuis son téléphone avant de valider le paiement.

8. Exemples d'utilisation

Exemple minimal

import FeexPay from 'react-sdk-feexpay';

function App() {
  return (
    <FeexPay
      amount={2500}
      token="tok_live_xxxxxxxxxxxxxx"
      id="shop_xxxxxxxx"
    />
  );
}

Avec callback JavaScript

import FeexPay from 'react-sdk-feexpay';

function CheckoutPage() {
  const handlePaymentResult = (result) => {
    switch (result.status) {
      case 'SUCCESSFUL':
        // Confirmer la commande côté serveur
        fetch('/api/orders/confirm', {
          method: 'POST',
          body: JSON.stringify({
            reference: result.reference,
            orderId: result.callback_info.orderId,
          }),
        });
        break;
      case 'FAILED':
      case 'INSUFFICIENT_FUNDS':
        alert('Le paiement a échoué : ' + result.message);
        break;
      case 'TIMEOUT':
        alert('La confirmation a expiré. Vérifiez votre compte opérateur.');
        break;
    }
  };

  return (
    <FeexPay
      amount={15000}
      token="tok_live_xxxxxxxxxxxxxx"
      id="shop_xxxxxxxx"
      description="Abonnement mensuel"
      callback={handlePaymentResult}
      callback_info={{ orderId: '1042', userId: 'usr_abc' }}
    />
  );
}

Avec redirection URL

<FeexPay
  amount={8000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  description="Commande #567"
  callback_url="https://monsite.com/paiement/succes"
  error_callback_url="https://monsite.com/paiement/echec"
  reference="CMD-2026-567"
/>

Après le paiement, l'utilisateur est redirigé vers :

• https://monsite.com/paiement/succes?ref=<reference> en cas de succès
• https://monsite.com/paiement/echec?ref=<reference> en cas d'échec

Forcer une méthode de paiement

{/* Mobile Money uniquement */}
<FeexPay
  amount={5000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  case="MOBILE"
/>

{/* Wallet uniquement */}
<FeexPay
  amount={5000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  case="WALLET"
/>

Pré-remplir les informations du payeur

<FeexPay
  amount={3000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  first_name="Jean Dupont"
  email="[email protected]"
  defaultValueField={{ country_iban: 'CI' }}
/>

Cela pré-remplit le nom, l'email et sélectionne automatiquement la Côte d'Ivoire dans le sélecteur de pays.

Masquer des champs

{/* Masquer l'email et le nom (utile si déjà authentifié) */}
<FeexPay
  amount={10000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  first_name="Marie Koné"
  email="[email protected]"
  fieldsToHide={['name', 'email']}
/>

Mode sandbox (tests)

<FeexPay
  amount={100}
  token="tok_sandbox_xxxxxxxxxxxxxx"
  id="shop_test_xxxxxxxx"
  mode="SANDBOX"
  description="Test de paiement"
  callback={(r) => console.log('Sandbox result:', r)}
/>

Bouton personnalisé déclenché par événement DOM

Le SDK écoute l'événement personnalisé feexpay:trigger sur son élément racine. Cela permet d'utiliser n'importe quel élément comme déclencheur :

import { useRef } from 'react';
import FeexPay from 'react-sdk-feexpay';

function CustomTrigger() {
  const containerRef = useRef(null);

  const openPayment = () => {
    containerRef.current
      ?.querySelector('[data-feexpay]')
      ?.dispatchEvent(new CustomEvent('feexpay:trigger', { bubbles: true }));
  };

  return (
    <>
      {/* Le composant est invisible (custom_button interne) */}
      <div ref={containerRef}>
        <FeexPay
          amount={5000}
          token="tok_live_xxxxxxxxxxxxxx"
          id="shop_xxxxxxxx"
        />
      </div>

      {/* Votre propre bouton */}
      <button onClick={openPayment} className="mon-bouton-custom">
        Finaliser l'achat
      </button>
    </>
  );
}

Utilisation du contexte FeexPayProvider

Le composant <FeexPay /> inclut son propre FeexPayProvider. Si vous souhaitez gérer plusieurs instances ou partager le contexte dans une arborescence React, vous pouvez wrapper votre application manuellement :

import { FeexPayProvider } from 'react-sdk-feexpay';

function App() {
  return (
    <FeexPayProvider>
      {/* Votre application */}
    </FeexPayProvider>
  );
}

9. Gestion des erreurs

Erreurs de configuration

Si les identifiants id ou token sont invalides, le SDK affiche un message d'erreur à la place du bouton :

Veuillez vérifier vos identifiants de boutique (ID et token).

Aucune modale ne s'ouvre dans ce cas.

Erreurs de validation du formulaire

La modale valide les champs avant d'initier le paiement. Les messages d'erreur s'affichent dans une modale de statut :

| Champ manquant / invalide | Message affiché | |---|---| | Nom complet vide | Veuillez entrer votre nom complet | | Email absent ou invalide | Veuillez entrer une adresse email valide | | Numéro de téléphone trop court | Veuillez entrer un numéro de téléphone valide | | Wallet sur un pays non supporté | Seuls le Bénin (Coris) et la Côte d'Ivoire (Wave) sont supportés |

Codes de statut API

| Code | Signification | Comportement | |---|---|---| | 10 | Fonds insuffisants | Statut INSUFFICIENT_FUNDS, redirection error_callback_url si définie | | 92 | Transaction annulée | Statut FAILED, redirection error_callback_url si définie | | 201 (Coris) | OTP requis | Ouverture de la modale OTP |

Gestion du timeout

Le SDK effectue une vérification de statut toutes les 10 secondes, pendant 2 minutes maximum (12 tentatives). Si aucune confirmation n'arrive dans ce délai :

• Le statut TIMEOUT est retourné dans le callback
• La redirection error_callback_url est déclenchée si définie
• Message : "La vérification du paiement a expiré. Veuillez vérifier votre compte."

Conseil : Configurez un webhook côté serveur sur le tableau de bord FeexPay pour recevoir les confirmations de paiement indépendamment du timeout côté client.

Erreurs réseau

En cas d'exception lors de l'appel API (réseau coupé, serveur indisponible), le SDK affiche :

Une erreur est survenue lors du traitement du paiement. Veuillez réessayer.

Le callback est appelé avec status: 'FAILED'.

Opérateurs avec redirect iframe

Pour certains opérateurs (Wave CI, Orange CI, Moov BF, Orange BF, Wave SN), le paiement passe par une page externe affichée dans une iframe intégrée. L'utilisateur finalise le paiement dans cette iframe, puis le SDK vérifie le statut en arrière-plan. Un bouton de fermeture permet de revenir au formulaire.

10. Personnalisation du bouton

Via buttonText et buttonClass

<FeexPay
  amount={5000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  buttonText="Acheter maintenant"
  buttonClass="bg-green-600 hover:bg-green-700 text-white font-semibold py-3 px-6 rounded-full"
/>

Via buttonStyles (styles inline)

<FeexPay
  amount={5000}
  token="tok_live_xxxxxxxxxxxxxx"
  id="shop_xxxxxxxx"
  buttonStyles={{
    backgroundColor: '#1a56db',
    color: '#ffffff',
    padding: '12px 24px',
    borderRadius: '8px',
    fontWeight: 'bold',
    border: 'none',
    cursor: 'pointer',
  }}
/>

Le texte par défaut du bouton est "Payer X {currency}" où X est le montant formaté en locale française.

11. Changelog

1.0.0 — Publication initiale

• Renommage du paquet en react-sdk-feexpay
• Migration vers React 19 et styled-components v6
• Composant principal FeexPay avec alias rétrocompatible FeexPayButton
• Support Mobile Money : Bénin, Côte d'Ivoire, Burkina Faso, Congo-Brazzaville, Sénégal, Togo
• Support Wallet : Coris Money (Bénin), Wave (Côte d'Ivoire)
• Gestion OTP pour Orange Sénégal et Coris Money
• Affichage iframe pour les opérateurs avec redirect
• Polling de statut automatique (10 s × 12 = 2 min)
• Pré-remplissage des champs (first_name, email, defaultValueField)
• Masquage de champs (fieldsToHide)
• Event DOM feexpay:trigger pour déclencheurs personnalisés
• Exports TypeScript complets (PaymentConfig, Transaction, Network, Country, etc.)

Ressources

• Site officiel FeexPay : feexpay.me
• Conditions d'utilisation : feexpay.me/fr/terms-and-conditions
• Tableau de bord marchands : Disponible sur votre espace FeexPay
• Support : Contactez l'équipe FeexPay depuis votre tableau de bord

Documentation générée pour react-sdk-feexpay v2