Gestion des Collectes
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.
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
Retrouvez plus d’informations dans notre Reference API
Remplacez 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.
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.
Le lien ainsi généré peut être utilisé pour rediriger les utilisateurs vers la page de paiement de FedaPay.
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.
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.
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
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 :
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.
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écifiques
Voici un exemple de code pour envoyer un paiement mobile sans redirection
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 :
-
Envoyez une requête pour obtenir les détails de la collecte.
-
Implémentez un webhook pour recevoir des notifications automatiques. Consultez la section Webhooks pour plus de détails.
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 (solde insuffisant ou autre problème de paiement)
-
canceled : Annulée (interruption volontaire ou accidentelle par le client)
-
refunded : Remboursée (somme reversée au client)
-
transferred : Transférée (montant transféré sur le compte marchand)