Dans beaucoup d’entreprises africaines, la fin du mois ne se joue pas sur un virement groupé à la banque, mais sur des dizaines ou des centaines de transferts mobile money : agents terrain, livreurs, vendeurs à la commission, prestataires, partenaires. Faits à la main depuis un téléphone, ces paiements prennent des heures, et une seule erreur de saisie suffit à envoyer de l’argent au mauvais numéro.

Ce guide décrit une méthode fiable pour verser salaires, primes et commissions en mobile money ou par virement, à grande échelle, sans double paiement ni oubli.

Pourquoi le mobile money pour payer vos équipes

Pour une part importante des travailleurs, le portefeuille mobile money est le compte du quotidien : c’est là qu’ils reçoivent, épargnent et dépensent. Les payer directement sur ce portefeuille présente plusieurs avantages :

• L’argent arrive vite, en général dans l’instant, y compris le soir ou le week-end.
• Le bénéficiaire reçoit le montant complet : chez Monerails, les frais sont débités de votre côté, en plus du montant.
• Chaque versement laisse une trace, avec une référence, un statut et une preuve de paiement.
• Il fonctionne au-delà des frontières : la même méthode paie un livreur à Douala, une vendeuse à Abidjan et un agent à Nairobi, chacun dans sa monnaie.

Préparer des données propres

La plupart des incidents de paiement viennent des données, pas de la technique. Avant le premier versement, constituez un fichier de bénéficiaires fiable :

Faites confirmer numéro et opérateur par chaque bénéficiaire à l’embauche, puis à chaque changement. Pour les bénéficiaires payés sur compte bancaire, Monerails permet le virement local dans douze pays, dont le Cameroun, la Côte d’Ivoire, le Sénégal, le Nigeria et le Kenya.

Payer en masse par API

Avec l’API Monerails, un paiement de masse est une boucle : un appel par bénéficiaire, chacun avec sa propre clé d’idempotence. L’exemple ci-dessous en Node.js parcourt une liste et envoie chaque versement.

for (const p of beneficiaires) {
  await fetch('https://api.monerails.com/v1/payouts', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `paie-2026-11-${p.matricule}`,
    },
    body: JSON.stringify({
      amount: p.montant,          // 85000 = 85 000 FCFA
      currency: p.devise,         // 'XAF', 'XOF', 'KES'…
      country: p.pays,            // 'CI' pour la Côte d'Ivoire
      recipient: { type: 'mobile_money', name: p.nom,
                   phone: p.telephone, operator: p.operateur },
      client_reference: `paie-2026-11-${p.matricule}`,
    }),
  });
}

Trois points font la différence entre un script qui marche et un script fiable :

1. Une clé d’idempotence stable par versement. Construite à partir de la période et de l’identifiant du bénéficiaire, elle permet de relancer tout le script après une coupure sans jamais payer deux fois la même personne.
2. Le respect des limites de débit. Sur une réponse 429, attendez le délai indiqué par l’en-tête Retry-After avant de reprendre.
3. Aucune nouvelle création après un 202. Cette réponse signifie que le paiement est en route : attendez le webhook.

Ce qui se passe côté solde

À la création de chaque paiement, Monerails réserve le montant et les frais sur votre solde dans la devise concernée. Si le solde ne couvre pas les deux, la requête est refusée (402 balance_insufficient) et rien n’est envoyé. Vérifiez donc votre solde avant de lancer un lot, en tenant compte des frais publiés sur la page Tarifs.

Si un paiement échoue, par exemple sur un numéro inexistant, le montant et les frais reviennent automatiquement sur votre solde, avec le motif de l’échec. Vous corrigez la ligne et vous renvoyez ce seul paiement, avec une nouvelle clé.

Suivre chaque versement

Un paiement passe par les statuts pending et processing, puis devient succeeded ou failed. Abonnez-vous aux webhooks payout.succeeded et payout.failed pour mettre à jour votre logiciel de paie au fil de l’eau, sans interroger l’API en boucle.

Grâce au champ client_reference, chaque événement porte votre propre référence : le rapprochement avec votre fichier de paie se fait ligne à ligne. En fin de traitement, comparez trois totaux : le nombre de versements prévus, le nombre de succeeded et le nombre de failed. Tant qu’ils ne concordent pas, le lot n’est pas clos.

Exemple : les commissions d’un réseau de vendeurs

Prenons une entreprise de distribution qui rémunère 180 vendeurs à la commission, au Cameroun et en Côte d’Ivoire. Chaque fin de mois, son outil de gestion calcule la commission de chacun à partir des ventes enregistrées.

1. L’outil exporte la liste : identifiant du vendeur, nom, numéro, opérateur, pays, montant.
2. La finance vérifie les deux soldes, XAF et XOF, frais compris, et valide le total.
3. Le script de paiement parcourt la liste, avec une clé commission-2026-11-<identifiant> par vendeur.
4. Les webhooks mettent à jour chaque ligne : payée, ou en échec avec son motif.
5. Les quelques échecs, souvent un numéro changé, sont corrigés avec le vendeur et renvoyés le jour même.

Le lendemain, chaque vendeur a reçu sa commission sur son portefeuille, et l’entreprise dispose d’un état complet : qui a été payé, quand, avec quelle référence. En cas de contestation, la preuve de paiement est disponible pour chaque versement.

Contrôle interne et sécurité

Les paiements sortants sont l’opération la plus sensible d’un compte. Organisez-les en conséquence :

• Séparez les rôles. Chez Monerails, les rôles Propriétaire, Finance, Approbateur et Développeur déterminent qui peut payer, reverser ou émettre des cartes. Les clés d’API capables de payer doivent être créées par un membre Propriétaire, Finance ou Approbateur.
• Gardez la clé de production hors du code, dans un gestionnaire de secrets, avec le seul rôle nécessaire.
• Testez d’abord. Rejouez votre lot complet en mode test : les paiements suivent tout le parcours sans déplacer d’argent réel.
• Commencez petit. Pour un nouveau bénéficiaire, un premier versement modeste confirme le numéro avant les montants importants.

Chaque paiement est par ailleurs contrôlé au regard des listes de sanctions avant son départ.

Et sans développeur ?

Depuis le tableau de bord, vous pouvez déjà envoyer des paiements un par un, vers un portefeuille ou un compte bancaire, en voyant les frais avant de valider. L’import d’un fichier CSV, vérifié ligne par ligne et soumis à validation avant envoi, arrive bientôt : il permettra de lancer un lot entier depuis un tableur, avec un rapport et un webhook pour chaque paiement.

Quelle que soit la voie choisie, les principes restent les mêmes : des données propres, une référence unique par versement, un solde qui couvre montants et frais, et un rapprochement à la fin. Le tableau de bord et l’API partagent les mêmes soldes : les paiements envoyés par l’un ou l’autre apparaissent côte à côte dans vos transactions.

La liste de contrôle du jour de paie

1. Fichier de bénéficiaires à jour : nom, numéro, opérateur, pays.
2. Solde suffisant dans chaque devise, frais compris.
3. Une référence et une clé d’idempotence uniques par versement.
4. Webhooks payout.succeeded et payout.failed actifs.
5. Rapprochement final : prévus = réussis + échoués, échecs corrigés et renvoyés.

Pour aller plus loin, le guide de l’API mobile money détaille webhooks et idempotence, et notre article sur le mobile money au Cameroun, en Côte d’Ivoire et au Sénégal rappelle les formats de numéro de chaque pays. Le détail technique est dans le guide des paiements sortants, et l’offre sur la page Paiements.