L’API de FedaPay permet d’intégrer facilement des solutions de paiement sécurisées dans votre site web ou application. Ce guide vous expliquera en détail comment configurer et gérer la collecte de paiements à l’aide de l’API, de la création initiale à la finalisation du processus, en passant par les fonctionnalités avancées comme les paiements sans redirection. Que vous soyez développeur ou responsable de produits, vous trouverez ici tout le nécessaire pour utiliser FedaPay de manière optimale.

​
Étapes pour Créer et Gérer une Collecte de Paiement

Les étapes de configuration d’une collecte se divisent en plusieurs processus essentiels.
1

Initialisation de la Collecte : Création d'une Requête

La première étape consiste à envoyer une requête de création de collecte via l’API. Cette requête nécessite certains paramètres obligatoires :
  • description : une brève description de l’objet de la collecte
  • amount : le montant, toujours en nombre entier
  • currency : la devise, indiquée par son numéro ou code ISO (référez-vous au Tableau des Devises FedaPay pour les détails)
  • callback_url : un lien de retour facultatif pour rediriger le client après le paiement
  • customer : le client concerné par la collecte
Si le client n’est pas encore enregistré dans votre système, vous pouvez créer simultanément son profil en ajoutant des informations comme le nom, prénom, email, et numéro de téléphone.

​
Exemple de requête pour créer une collecte

  curl -X POST \
  https://sandbox-api.fedapay.com/v1/transactions \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "description" : "Transaction for john.doe@example.com",
        "amount" : 2000,
        "currency" : {"iso" : "XOF"},
        "callback_url" : "https://maplateforme.com/callback",
        "customer" : {
            "firstname" : "John",
            "lastname" : "Doe",
            "email" : "john.doe@example.com",
            "phone_number" : {
                "number" : "+22997808080",
                "country" : "bj"
            }
          }
      }'
Retrouvez plus d’informations dans notre Reference APIRemplacez YOUR_SECRETE_API_KEY par votre clé API et utilisez l’URL du serveur approprié (sandbox ou live).Si le client est déjà enregistré, utilisez simplement son ID ou email pour l’associer à la collecte.
Attention :Le paramètre customer n’est pas obligatoire. Cependant, lorsque vous créer une transaction avec un customer, assurez-vous que l’adresse email est unique. En effet, FedaPay considère qu’il s’agit du meme customer si les emails sont identique. Si vous envoyer la meme adresse email et que vous renseignez des nom, prénom et numéros de téléphone différents, FedaPay mettra simplement à jour le customer avec les nouvelles informations.
2

Génération du Token et du Lien de Paiement

Une fois la requête envoyée, l’API renvoie un identifiant unique pour la collecte. Utilisez cet identifiant pour demander un lien et un token de paiement pour rediriger le client vers la page de paiement sécurisée.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions/ID/token \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json'
Le lien ainsi généré peut être utilisé pour rediriger les utilisateurs vers la page de paiement de FedaPay.
3

Redirection vers la Page de Paiement

Ce lien redirige votre client vers une page de paiement sécurisée, où il pourra finaliser la collecte. Si vous avez spécifié un callback_url, votre client sera redirigé automatiquement à l’issue du paiement.
4

Utilisation du Lien de Retour (Callback URL)

Le callback_url permet de rediriger le client vers une page spécifique à la fin du paiement, avec le statut et l’ID de la collecte en paramètres. Par exemple :
  • Paiement approuvé : https://www.monsite.com/?id=258&status=approved
  • Paiement annulé : https://www.monsite.com/?id=259&status=canceled
Attention : Pour des raisons de sécurité, ne vous fiez pas au statut renvoyé par l’URL. Effectuez toujours une vérification directe auprès de l’API pour obtenir le statut réel.
5

Récupération des Détails d’une Collecte

Pour récupérer les informations complètes d’une collecte, effectuez une requête avec l’ID de cette collecte.

​
Exemple de requête pour récupérer les détails d’une collecte

/*Remplacez YOUR_SECRETE_API_KEY par la clé API secrète de votre compte sandbox ou live. Si vous utilisez votre compte live, vous devez remplacer le lien par https://api.fedapay.com/v1/transactions/ID */

curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/ID \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json'
Retrouvez plus d’informations dans notre Reference API

​
Paiements sans Redirection

Pour offrir une expérience fluide sans redirection, vous pouvez intégrer directement le formulaire de paiement dans votre application pour certaines méthodes spécifiques (MTN Bénin, Moov Bénin, Moov Togo, et MTN Côte d’Ivoire). Ce mode de paiement est particulièrement utile pour les sites e-commerce qui souhaitent garder l’utilisateur sur leur plateforme tout au long du processus, sans redirection vers une autre page. Envoi d’un Paiement Mobile Sans Redirection Le processus de paiement mobile sans redirection se divise en deux étapes principales dans l’environnement Live ou Sandbox :
1

Créer une collecte de paiement

La première étape consiste à créer une collecte via l’API de FedaPay. Cela génère un token qui est nécessaire pour effectuer la transaction.
2

Déclencher le paiement

Une fois que vous avez le token de paiement, vous devez envoyer une requête à l’API FedaPay pour traiter le paiement. La requête se fait en utilisant une des méthodes de paiement spécifiquesVoici un exemple de code pour envoyer un paiement mobile sans redirection
curl -X POST \
https://sandbox-api.fedapay.com/v1/METHODE_PAIEMENT \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json'
-d '{
  "token" : "TOKEN_DE_PAIEMENT",
  "phone_number": {
    "number": "64000001",
    "country":"bj"
  }
}'
Attention :Remplacez METHODE_PAIEMENT par la méthode de paiement choisie (par exemple mtn_benin, moov_benin, etc.).VOTRE_CLE_API_SECRETE doit être remplacée par votre clé API secrète (en mode sandbox pour les tests ou en mode live pour les transactions en production).Lorsque vous êtes prêt à passer en production, remplacez l’URL de sandbox par l’URL en mode Live :
  • Sandbox : https://sandbox-api.fedapay.com
  • Live : https://api.fedapay.com/v1/transactions/ID
Important : Veillez à tester minutieusement vos intégrations dans l’environnement sandbox avant de les déployer en production
Attention :Le paramètre phone_number n’est pas obligatoire pour la requête d’envoie de notification de paiement. Cependant, s’il n’est pas mentionné, FedaPay essaiera d’envoyer la notification au numéro lié au client associé à la transaction lors de sa création.
Remarque : Le paiement sans redirection ne prend pas en charge tous les opérateurs. Consulter la section Méthodes de Paiement pour en savoir un peu plus.

​
Récupération Automatique du Statut d’une Collecte

Pour vérifier le statut final d’une collecte, surtout lors d’un paiement sans redirection :

​
Cycle de Vie d’une Collecte : Les Statuts

Chaque collecte passe par différents statuts :
  • pending : En attente (statut par défaut à la création)
  • approved : Approuvée (paiement réussi)
  • declined : Déclinée (interruption volontaire ou accidentelle par le client)
  • canceled : Annulée (solde insuffisant ou autre problème de paiement)
  • refunded : Remboursée (somme reversée au client)
  • transferred : Transférée (montant transféré sur le compte marchand)
  • expired : la collecte n’a pas été finalisée dans le délai imparti
Pour consulter le statut en temps réel, rendez-vous dans le tableau de bord FedaPay sous la section Collectes ou utilisez l’API pour vérifier avec l’ID de la collecte.

​
Ajouter des données personnalisées à vos transactions : merchant_reference et custom_metadata

Lorsque vous créez une transaction via l’API de FedaPay, il est souvent nécessaire d’y associer des informations propres à votre application. Cela vous permet de mieux suivre, analyser ou relier une transaction à un utilisateur ou une commande spécifique sur votre plateforme. FedaPay vous offre deux champs très utiles pour cela : merchant_reference et custom_metadata. merchant_reference : Votre identifiant unique pour chaque transaction Le champ merchant_reference vous permet d’attribuer à chaque transaction un identifiant unique défini par vous-même (par exemple : un ID de commande, un numéro de facture ou le code d’une session d’achat). Cet identifiant est stocké par FedaPay et peut ensuite être utilisé pour retrouver facilement la transaction via une API dédiée. Pourquoi l’utiliser ?
  • Vous avez une plateforme e-commerce ou une application mobile et souhaitez lier une transaction FedaPay à un paiement interne.
  • Vous souhaitez retrouver rapidement une transaction en utilisant vos propres références, sans avoir à stocker l’ID généré par FedaPay.
  • Vous voulez tracer plus facilement les paiements effectués par vos clients.
Exemple : Créer une transaction avec merchant_reference
Curl
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{
      "description" : "Transaction for john.doe@example.com",
      "amount" : 2000,
      "currency" : {"iso" : "XOF"},
      "callback_url" : "https://maplateforme.com/callback",
      "customer" : {
        "email" : "john.doe@example.com",
      },
      "merchant_reference": "CMD-20250701-001" 
    }'
Dans cet exemple, CMD-20250701-001 est la référence propre au marchand pour cette commande.
Récupérer une transaction avec la référence marchand
Curl
curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/merchant/{reference}
 \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'
custom_metadata : Ajouter des données personnalisées à vos transactions Avec le champ custom_metadata, vous pouvez enregistrer des informations supplémentaires directement dans la transaction. Il peut s’agir, par exemple :
  • Le numéro de la commande
  • Du type de service acheté
  • De l’identifiant de l’agent vendeur
  • Ou toute autre donnée utile pour vous.
Ces données sont stockées sous forme de paires clé-valeur et restent attachées à la transaction, sans affecter son traitement. Pourquoi l’utiliser ?
  • Pour enrichir vos rapports internes ou automatiser certains traitements en récupérant vos propres données.
  • Pour éviter de stocker des informations sensibles côté client.
  • Pour gagner du temps lors du rapprochement comptable ou des vérifications manuelles.
Exemple : Créer une transaction avec custom_metadata
Curl
curl -X POST https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "description": "Abonnement premium",
  "amount": 10000,
  "currency": {"iso": "XOF"},
  "callback_url": "https://votreapp.com/callback",
  "customer": {
    "email": "utilisateur@votreapp.com"
  },
  "custom_metadata": {
    "client_id": "USER-14567",
    "forfait": "premium",
    "langue": "fr"
  }
}'
Bonnes pratiques :
  • Assurez-vous que la valeur de merchant_reference est unique pour chaque transaction. Si la valeur de l’identifiant existe déjà, la création de la transaction échouera.
  • Utilisez custom_metadata uniquement pour des données non sensibles (évitez les mots de passe, données de carte, etc.).
  • Ces champs sont facultatifs, mais très utiles pour automatiser vos flux métier et faciliter l’intégration avec vos outils internes.