Gestion des Collectes et Dépôts
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
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.
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.
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
Remarque : Le paiement sans redirection ne prend pas en charge tous les opérateurs. Consulter la section Méthodes de Paiement(Redirection vers 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)
Gestion des dépôts
Un dépôt est une opération qui permet de transférer de l’argent directement à partir de votre balance vers le compte d’un client. Cette fonctionnalité est conçue pour les entreprises qui ont besoin de gérer des paiements vers des clients spécifiques.
Étapes pour la Création d’un Dépôt
La création d’un dépôt via l’API se déroule en plusieurs étapes. Chaque dépôt passe par différents processus qui doivent être respectés pour garantir le bon déroulement du transfert.
Requête de Création d'un Dépôt
Pour commencer, vous devez envoyer une requête de création de dépôt via notre API. Les informations essentielles à fournir lors de cette requête incluent :
-
amount : Le montant du dépôt, toujours indiqué en nombre entier.
-
currency : La devise à utiliser pour le dépôt. Vous pouvez indiquer le code ISO de la devise choisie (par exemple, XOF pour le franc CFA).
-
customer : Le client concerné par le dépôt. Si le client n’existe pas encore dans votre base de données, vous pouvez le créer en même temps que le dépôt en fournissant les informations suivantes : nom, prénom, adresse e-mail, et numéro de téléphone.
Code API pour la création d’un dépôt
Un exemple de code est disponible pour simplifier la création d’un dépôt via l’API. Assurez-vous de remplacer YOUR_SECRETE_API_KEY par votre clé privée sandbox ou live.
Envoi du Dépôt
Après avoir créé un dépôt, il sera marqué comme “en attente”. Vous devez ensuite procéder à son envoi. Deux options s’offrent à vous :
-
Envoyer le dépôt immédiatement
-
Planifier l’envoi pour plus tard
Code API pour l’envoi du dépôt
Utilisez le code PHP, Node.js ou Ruby pour envoyer le dépôt en remplaçant YOUR_SECRETE_API_KEY par votre clé privée.
Récupération des Détails d'un Dépôt
Une fois le dépôt créé et/ou envoyé, vous pouvez consulter ses détails pour obtenir des informations spécifiques, telles que le statut ou l’historique du dépôt.
Code API pour récupérer les détails d’un dépôt
Récupérez les informations d’un dépôt spécifique en utilisant son identifiant unique (ID). Remplacez ID dans l’URL par l’identifiant du dépôt que vous souhaitez consulter.
Cycle de Vie des Dépôts
Lorsqu’un dépôt est créé, il passe par plusieurs statuts :
-
pending (En attente) : Statut initial après la création du dépôt.
-
started (Démarré) : Le dépôt a été validé et l’envoi est en cours de démarrage.
-
processing (En cours d’envoi) : Le dépôt est en cours de traitement et d’envoi vers le destinataire.
-
sent (Envoyé) : Le dépôt a été envoyé avec succès au destinataire.
-
failed (Échoué) : L’envoi du dépôt a échoué, pour des raisons qui peuvent varier (erreur technique, problème avec la méthode de versement, etc.).
Vous pouvez suivre l’évolution du statut de vos dépôts à partir du tableau de bord FedaPay dans le menu Dépots.
Méthodes de Versement Disponibles
Actuellement, les méthodes de versement prises en charge pour les dépôts sont disponibles dans plusieurs pays de la sous-région
Ces méthodes permettent d’envoyer facilement des fonds vers différents pays d’Afrique de l’Ouest.
Support
Si vous avez des questions ou rencontrez des difficultés avec les dépôts, n’hésitez pas à contacter notre support technique à l’adresse : support@fedapay.com