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.
1

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.

​
Exemple de requête pour la création d’un dépôt

  curl -X POST \
  https://sandbox-api.fedapay.com/v1/payouts \
  -H 'Authorization: Bearer VOTRE_CLE_API_PRIVEE' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount" : 2000,
        "currency" : {"iso" : "XOF"},
        "mode": "mtn_open" 
        "customer" : {
            "firstname" : "John",
            "lastname" : "Doe",
            "email" : "john.doe@example.com",
            "phone_number" : {
                "number" : "+22997808080",
                "country" : "bj"
            }
        }
      }'
Retrouvez plus d’informations dans notre Reference APIUn 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.
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

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 
    curl -X PUT \
https://sandbox-api.fedapay.com/v1/payouts/start \
-H 'Authorization: Bearer VOTRE_CLE_API_PRIVEE' \
-H 'Content-Type: application/json'
-d '{
    "payouts" : [
      { "id": 23 }, // Envoie le dépôt instantanément
      { "id": 23, "phone_number": { "number": "66000001", "country": "BJ" } }, // Envoie le dépôt instantanément avec numéro de téléphone
      { "id": 24 , "scheduled_at": "2024-11-18 18:8:43"} // Envoie le dépôt plus tard
    ]
  }'
3

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.

​
Exemple de requête pour récupérer les détails d’un dépôt


/*Remplacez VOTRE_CLE_API_PRIVEE par la clé privée de votre compte sandbox ou live. Si vous utilisez votre compte live, vous devez remplacer le lien par https://api.fedapay.com/v1/payouts/ID  */

  curl -X GET \
  https://sandbox-api.fedapay.com/v1/payouts/ID \
  -H 'Authorization: Bearer VOTRE_CLE_API_PRIVEE' \
  -H 'Content-Type: application/json'
Retrouvez plus d’informations dans notre Reference APIRé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.

​
Ajouter des données personnalisées (custom_metadata) à vos dépôts

Lorsque vous effectuez un dépôt à partir de votre solde FedaPay vers un compte Mobile Money (MTN Bénin, MTN Cote d’ivoire, Moov Bénin, Moov Togo et Togocel), vous pouvez y joindre des informations personnalisées grâce au champ custom_metadata. Cela vous permet d’associer à chaque opération des éléments utiles pour votre activité, comme un identifiant utilisateur, le motif du transfert, une référence de service. À quoi sert custom_metadata dans un dépôt ? Que vous soyez une plateforme de services, un opérateur de cashback, une marketplace ou une solution de paiement pour marchands, le champ custom_metadata vous permet de :
  • Garder une trace précise de l’opération du côté de votre système.
  • Automatiser vos processus internes, en rattachant un dépôt à un utilisateur, un événement ou une commande.
  • Faciliter les audits et les rapprochements comptables grâce à des données personnalisées stockées au bon endroit.
  • Gagner du temps : plus besoin de croiser manuellement les ID FedaPay avec ceux de votre système.
Exemple : effectuer un dépôt avec des métadonnées personnalisées Voici une requête de dépôt (payout) avec un champ custom_metadata renseigné :
Curl
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 3000,
  "currency": {"iso": "XOF"},
  "description": "Paiement de la commission d’un agent terrain",
  "receiver": {
    "name": "Koffi Kodjo",
    "phone_number": "+22961234567",
    "provider": "mtn"
  },
  "custom_metadata": {
    "agent_id": "AGT-0032",
    "mois": "Juillet",
    "type": "commission"
  }
}'
À savoir
  • Le champ custom_metadata accepte une structure JSON (paires clé-valeur).
  • Utilisez des clés simples et explicites (ex. : type, mois, client_id).
  • Il est totalement facultatif, mais fortement recommandé pour une gestion structurée.
  • Évitez d’y mettre des informations sensibles ou confidentielles (comme des mots de passe ou des numéros de carte).

​
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