> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fedapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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.
* **description (optionnel)** :Champ libre permettant de décrire l’objet ou l’usage du dépôt.Ce champ peut notamment servir à :
* préciser la nature de la transaction (ex. : aide familiale, paiement de service, achat de biens, etc.) ;
* répondre aux exigences réglementaires, notamment celles de la BCEAO relatives à la justification de l’usage des fonds ;
* faciliter le suivi, l’identification et l’analyse des transactions dans le dashboard et via l’API.
Le champ description est facultatif côté API, afin de garantir la compatibilité avec les intégrations existantes. Toutefois, il peut être requis dans certaines interfaces du dashboard pour améliorer la traçabilité des opérations.
#### Exemple de requête pour la création d’un dépôt
```java Curl theme={null}
curl -X POST \
https://sandbox-api.fedapay.com/v1/payouts \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"amount" : 2000,
"currency" : {"iso" : "XOF"},
"mode": "mtn_open" ,
"description" : "paiement de service", // Non obligatoire
"customer" : { // obligatoire.
"firstname" : "John",
"lastname" : "Doe",
"email" : "john.doe@example.com",
"phone_number" : {
"number" : "+22997808080",
"country" : "bj"
}
}
}'
```
```javascript NodeJs theme={null}
const { FedaPay, Payout } = require('fedapay');
FedaPay.setApiKey('YOUR_API_KEY');
FedaPay.setEnvironment('sandbox');
const payout = await Payout.create(
{
amount: 2000,
currency: { iso: "XOF" },
mode: "mtn_open", // Non obligatoire. FedaPay détectera l'operateur sinon.
description : "paiement de service", // Non obligatoire
customer: { // obligatoire.
firstname: "John",
lastname: "Doe",
email: "john.doe@example.com",
phone_number: {
number: "+22997808080",
country: "bj",
},
},
});
```
```php PHP theme={null}
\FedaPay\Fedapay::setApiKey(MY_API_KEY);
\FedaPay\Payout::create([
"amount" => 2000,
"currency" => ["iso" => "XOF"],
"mode" => "mtn_open", // Non obligatoire. FedaPay détectera l'operateur sinon.
"description" => "paiement de service", // Non obligatoire
"customer" => [ // Non obligatoire.
"firstname" => "John",
"lastname" => "Doe",
"email" => "john.doe@example.com",
"phone_number" => [
"number" => "+22997808080",
"country" => "bj",
],
],
]);
```
```Ruby Ruby theme={null}
require 'fedapay';
FedaPay.api_key = '';
FedaPay.environment = 'sandbox';
currency = { iso: 'XOF' };
payout = FedaPay::Payout.create({
amount: 1000,
currency: currency,
mode: "mtn_open", // Non obligatoire.
description: "paiement de service", // Non obligatoire
customer: { // Non obligatoire.
firstname: "John",
lastname: "Doe",
email: "john.doe@example.com",
phone_number: {
number: "+22997808080",
country: "bj",
},
},
});
```
[Retrouvez plus d’informations dans notre Reference API](/api-reference/payouts/create)
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.
**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.
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
```java Curl theme={null}
curl -X PUT \
https://sandbox-api.fedapay.com/v1/payouts/start \
-H 'Authorization: Bearer TOKEN' \
-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
]
}'
```
```javascript NodeJs theme={null}
const payout = await Payout.create({...});
// Envoi du dépôt maintenant
await payout.sendNow();
// Envoi d'un dépôt sur numéro de téléphone autre que celui du customer
await payout.sendNow({
phone_number: {
number: "64000001",
country: "BJ"
}
});
// Envoi du dépôt plus tard
await payout.schedule("2024-11-18 18:8:43");
// Programmer un dépôt pour plus tard mais sur un autre numéro autre
// que celui du customer
await payout.schedule("2024-11-18 18:8:43", {
phone_number: {
number: "64000001",
country: "BJ"
}
});
// Programmer plusieurs envois
await Payout.scheduleAll([
{
id: 23, // Envoie le dépôt instantanément
scheduled_at: "2024-11-18 18:8:43" // Envoie le dépôt plus tard
},
{
id: 24, // Envoie le dépôt instantanément
scheduled_at: "2024-11-18 18:8:43" // Envoie le dépôt plus tard
},
{
id: 25,
scheduled_at: "2024-11-18 18:8:43",
phone_number: {
number: "64000001",
country: "BJ"
}
}
]);
// Envoyer tous les dépôts instantanément
await Payout.sendAllNow([
{ id: 23 },
{ id: 24 },
{
id: 24,
phone_number: {
number: "64000001",
country: "BJ"
}
}
]);
```
```php PHP theme={null}
$payout = \FedaPay\Payout::create(array(...));
// Envoi du dépôt maintenant
$payout->sendNow();
// Envoi d'un dépôt sur numéro de téléphone autre que celui du customer
$payout->sendNow([
"phone_number" => [
"number" => "64000001",
"country" => "BJ"
]
]);
// Programmer un dépôt pour plus tard
$payout->schedule("2024-11-18 18:8:43");
// Programmer un dépôt pour plus tard mais sur un autre numéro autre
// que celui du customer
$payout->schedule("2024-11-18 18:8:43", [
"phone_number" => [
"number" => "64000001",
"country" => "BJ"
]
]);
// Programmer plusieurs envoies
Payout::scheduleAll([
[
"id" => 23 // Envoie le dépôt instantanément
],
[
"id" => 24,
"scheduled_at" => "2024-11-18 18:8:43" // Envoie le dépôt plus tard
],
[
"id" => 25,
"scheduled_at" => "2024-11-18 18:8:43",
"phone_number" => [
"number" => "64000001",
"country" => "BJ"
]
]
]);
// Envoyer tous les paiements instantanément
Payout::sendAllNow([
[ "id" => 23 ],
[ "id" => 24 ],
[
"id" => 24,
"phone_number" => [
"number" => "64000001",
"country" => "BJ"
]
]
]);
```
```ruby Ruby theme={null}
payout = FedaPay::Payout.create({...});
# Envoi du dépôt maintenant
payout.sendNow();
# Envoi d'un dépôt sur numéro de téléphone autre que celui du customer
payout.sendNow({
phone_number: {
number: "64000001",
country: "BJ"
}
});
# Envoi du dépôt plus tard
payout.schedule("2024-11-18 18:8:43");
# Programmer un dépôt pour plus tard mais sur un autre numéro autre
# que celui du customer
payout.schedule("2024-11-18 18:8:43", {
phone_number: {
number: "64000001",
country: "BJ"
}
});
# Programmer plusieurs envois
FedaPay::Payout.scheduleAll([
{
id: 23, # Envoie le dépôt instantanément
scheduled_at: "2024-11-18 18:8:43" # Envoie le dépôt plus tard
},
{
id: 24, # Envoie le dépôt instantanément
scheduled_at: "2024-11-18 18:8:43" # Envoie le dépôt plus tard
},
{
id: 25,
scheduled_at: "2024-11-18 18:8:43",
phone_number: {
number: "64000001",
country: "BJ"
}
}
]);
# Envoyer tous les dépôts instantanément
FedaPay::Payout.sendAllNow([
{ id: 23 },
{ id: 24 },
{
id: 24,
phone_number: {
number: "64000001",
country: "BJ"
}
}
]);
```
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
```java Curl theme={null}
/*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 TOKEN' \
-H 'Content-Type: application/json'
```
```javascript NodeJs theme={null}
const { FedaPay, Payout } = require('fedapay');
/* Remplacez YOUR_SECRETE_API_KEY par votre véritable clé API */
FedaPay.setApiKey("YOUR_SECRETE_API_KEY");
/* Indiquez si vous souhaitez exécuter votre requête en mode test ou en direct */
FedaPay.setEnvironment('sandbox'); //or setEnvironment('live');
/* Afficher un depot */
const payout = await Payout.retrieve(params = {}, headers = {});
```
```php PHP theme={null}
\FedaPay\Fedapay::setApiKey(MY_API_KEY);
$customer = \FedaPay\Payout::retrieve(ID, params = {}, header = {});
```
```Ruby Ruby theme={null}
require 'fedapay';
# configurer la bibliothèque FedaPay
FedaPay.api_key = '' # Votre clé API secrète
FedaPay.environment = '' # sandbox or live
payouts = FedaPay::Payout.retrieve(ID);
```
[Retrouvez plus d’informations dans notre Reference API](/api-reference/payouts/get-by-id)
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](/payment-methods/fr/payment-methods-fr) 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é :
```java Curl theme={null}
curl -X POST \
-H 'Authorization: Bearer TOKEN' \
-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"
}
}'
```
```javascript NodeJs theme={null}
const { FedaPay, Payout } = require('fedapay');
/* Replace YOUR_SECRET_API_KEY with your real API key */
FedaPay.setApiKey("YOUR_SECRET_API_KEY");
/* Specify whether you want to run your query in test or live mode */
FedaPay.setEnvironment('sandbox'); // or 'live'
/* Create a payout with custom metadata */
const payout = await Payout.create({
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"
}
});
console.log("Payout created:", payout.id);
```
```php PHP theme={null}
// Configurer la clé API et l'environnement
\FedaPay\FedaPay::setApiKey('YOUR_SECRET_API_KEY');
\FedaPay\FedaPay::setEnvironment('sandbox'); // ou 'live'
// Créer un dépôt avec des métadonnées personnalisées
$payout = \FedaPay\Payout::create([
"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"
]
]);
echo "Payout created: " . $payout->id;
```
```Ruby Ruby theme={null}
require 'fedapay'
FedaPay.api_key = 'YOUR_SECRET_API_KEY'
FedaPay.environment = 'sandbox' # or 'live'
payout = FedaPay::Payout.create(
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'
}
)
puts "Payout created: #{payout.id}"
```
**À 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).
### Merchant\_reference : votre identifiant unique pour chaque payout
Le champ merchant\_reference vous permet d’attribuer à chaque opération de payout (transfert d’argent du compte marchand FedaPay vers un numéro Mobile Money) un identifiant unique défini par vous-même.
Cet identifiant est enregistré par FedaPay et peut ensuite être utilisé pour retrouver ou tracer facilement un payout via une API dédiée.
**Pourquoi l’utiliser ?**
* **Suivi précis des transferts sortants** : Idéal si vous gérez de nombreux paiements vers des fournisseurs, partenaires, livreurs ou utilisateurs.
* **Traçabilité interne** : Permet de lier un payout FedaPay à un paiement interne (par exemple un remboursement, une commission ou un versement).
* **Recherche simplifiée** : Vous pouvez retrouver un payout à tout moment via son merchant\_reference, sans avoir à stocker l’ID généré par FedaPay.
* **Audit & reporting** : Très utile pour générer des rapports ou assurer la conformité comptable et financière de vos flux sortants.
**Exemple : Créer un payout avec merchant\_reference**
```java Curl theme={null}
curl -X POST https://sandbox-api.fedapay.com/v1/payouts \
-H 'Authorization: Bearer YOUR_SECRET_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"amount": 5000,
"currency": {"iso": "XOF"},
"description": "Paiement fournisseur Mars 2025",
"recipient": {
"name": "Kossi Agbo",
"phone_number": {
"number": "97000001",
"country": "bj"
}
},
"merchant_reference": "PAY-20250315-002"
}'
```
```javascript NodeJs theme={null}
const { FedaPay, Payout } = require('fedapay');
/* Replace YOUR_SECRET_API_KEY with your real API key */
FedaPay.setApiKey("YOUR_SECRET_API_KEY");
/* Set environment */
FedaPay.setEnvironment('sandbox'); // or 'live'
/* Create a payout with merchant_reference */
const payout = await Payout.create({
amount: 5000,
currency: { iso: 'XOF' },
description: 'Paiement fournisseur Mars 2025',
recipient: {
name: 'Kossi Agbo',
phone_number: { number: '97000001', country: 'bj' }
},
merchant_reference: 'PAY-20250315-002'
});
console.log("Payout created:", payout.id);
```
```php PHP theme={null}
\FedaPay\FedaPay::setApiKey('YOUR_SECRET_API_KEY');
\FedaPay\FedaPay::setEnvironment('sandbox'); // ou 'live'
$payout = \FedaPay\Payout::create([
"amount" => 5000,
"currency" => ["iso" => "XOF"],
"description" => "Paiement fournisseur Mars 2025",
"recipient" => [
"name" => "Kossi Agbo",
"phone_number" => [
"number" => "97000001",
"country" => "bj"
]
],
"merchant_reference" => "PAY-20250315-002"
]);
echo "Payout created: " . $payout->id;
```
```Ruby Ruby theme={null}
require 'fedapay'
FedaPay.api_key = 'YOUR_SECRET_API_KEY'
FedaPay.environment = 'sandbox' # or 'live'
payout = FedaPay::Payout.create(
amount: 5000,
currency: { iso: 'XOF' },
description: 'Paiement fournisseur Mars 2025',
recipient: {
name: 'Kossi Agbo',
phone_number: { number: '97000001', country: 'bj' }
},
merchant_reference: 'PAY-20250315-002'
)
puts "Payout created: #{payout.id}"
```
**Récupérer un payout avec la référence marchand**
```java Curl theme={null}
curl -X GET \
https://sandbox-api.fedapay.com/v1/payouts/merchant/PAY-20250315-002 \
-H 'Authorization: Bearer YOUR_SECRET_API_KEY' \
-H 'Content-Type: application/json'
```
```javascript NodeJs theme={null}
const { FedaPay, Payout } = require('fedapay');
FedaPay.setApiKey("YOUR_SECRET_API_KEY");
FedaPay.setEnvironment('sandbox');
const reference = 'PAY-20250315-002';
const payout = await Payout.retrieveByMerchantReference(reference);
console.log("Payout found:", payout.id);
```
```php PHP theme={null}
$merchant_reference = 'PAY-20250315-002';
$payout = \FedaPay\Payout::retrieveByMerchantReference($merchant_reference);
echo "Payout found: " . $payout->id;
```
```Ruby Ruby theme={null}
require 'fedapay'
FedaPay.api_key = 'YOUR_SECRET_API_KEY'
FedaPay.environment = 'sandbox' # or 'live'
reference = 'PAY-20250315-002'
payout = FedaPay::Payout.retrieve_by_merchant_reference(reference)
puts "Payout found: #{payout.id}"
```
**Bonnes pratiques :**
* Utilisez un format structuré pour vos références, ex. PAY-YYYYMMDD-XXX.
* Ne réutilisez jamais une même merchant\_reference pour plusieurs payouts.
* Vous pouvez également combiner merchant\_reference et custom\_metadata pour ajouter des détails (ID employé, campagne, projet...).
### 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`](mailto:support@fedapay.com)