Mangopay est souvent choisi pour des modèles marketplace ou plateformes multi-vendeurs. Le sujet n’est pas seulement d’encaisser : il faut identifier les parties, gérer les wallets, contrôler le KYC et expliquer les reversements.
Les docs Mangopay structurent users, wallets, pay-ins, transfers, payouts, refunds, hooks et vérifications. Une intégration solide doit relier ces objets à la commande et au vendeur.
Une intégration Mangopay API doit donc démarrer par le modèle financier, pas par le premier endpoint disponible.
Le cadrage doit rester prudent : les obligations, les pays, les statuts de vérification et les limites de paiement doivent être vérifiés dans les sources officielles et les conseils compétents. L’article aide à organiser l’intégration, pas à promettre une conformité automatique.
La question à poser tôt
Qui possède le wallet, qui peut recevoir un payout, qui est bloqué par le KYC et qui explique le solde au support ?
Traiter Mangopay comme un SI finance
Un wallet mal modélisé crée des écarts plus coûteux qu’un bug de checkout. Il faut penser finance, support et conformité dès la conception.
Le flux doit dire où sont les fonds et pourquoi ils y sont. Cette lecture doit rester disponible même quand un vendeur est bloqué, qu’un payout échoue ou qu’un refund arrive après la clôture.
Modéliser payeurs et vendeurs
Les rôles doivent être explicites : acheteur, vendeur, plateforme, bénéficiaire, administrateur. Chaque rôle change les droits et les preuves attendues.
Cette modélisation évite les wallets partagés et les responsabilités floues.
Anticiper les seuils KYC
Le KYC ne doit pas être découvert le jour du premier payout vendeur. Le back-office doit suivre statut, documents, blocage et action attendue.
Les seuils doivent être vérifiés dans la documentation et avec les conseils compétents.
Gouverner les wallets
Un wallet est un objet métier. Il doit être rattaché au bon propriétaire métier, au bon vendeur et au bon contexte de vente.
La plateforme doit empêcher les mouvements impossibles à expliquer. Elle doit aussi exposer un historique lisible : entrée, sortie, commission, réserve, remboursement et correction.
Relier pay-ins et commandes
Le pay-in doit pointer vers la commande, le client, le panier et les lignes concernées. Cette clé facilite refunds, support et reporting.
Sans référence commune, le cash devient un puzzle.
Tracer transfers et commissions
Les transfers doivent distinguer montant vendeur, commission plateforme, frais éventuels et réserve. Ce détail rend le reporting marketplace exploitable.
Un transfer sans justification métier devient une dette comptable. La référence de commande, le vendeur, la règle de commission et le motif de réserve doivent rester liés.
Sécuriser payouts vendeurs
Le payout ne doit partir que si vendeur, wallet, KYC, solde et règles internes sont cohérents. Le support doit comprendre pourquoi un payout est bloqué.
Les règles de réserve et de délai doivent être visibles.
Un payout bloqué doit devenir une action back-office, pas une enquête dans les exports.
Cette visibilité est aussi commerciale : un vendeur accepte mieux un délai s’il voit le motif, la pièce attendue, le montant concerné et la date estimée de déblocage.
Fiabiliser hooks et reprise
Les hooks doivent être idempotents, vérifiés et rejouables. Un événement perdu sur KYC, pay-in ou payout peut bloquer la chaîne financière.
Les logs doivent séparer incident technique et blocage métier.
Surveiller les blocages cash
Le run suit wallets sans responsable clair, KYC bloqué, pay-ins sans commande, transfers incohérents et payouts en erreur.
La surveillance doit distinguer incident technique, blocage documentaire, règle métier et risque finance. Chaque catégorie appelle une action différente.
- Cartographier les rôles.
- Tracer wallets et soldes.
- Surveiller KYC et payouts.
- Rapprocher commissions.
- Documenter les reprises.
Auditer wallets, réserves et corrections
Un projet Mangopay devient robuste quand chaque wallet peut être audité sans ouvrir une enquête technique. Il faut retrouver pourquoi l’argent est entré, pourquoi il n’est pas sorti, quelle commission a été prise et quelle correction a été appliquée.
Le coût caché se loge dans les corrections manuelles de solde. Une correction qui semble régler un vendeur peut casser la lecture finance si elle ne conserve pas le motif, la commande, la règle de commission, la pièce KYC ou l’événement qui a déclenché le blocage.
La contre-intuition consiste à accepter un peu plus de friction back-office pour éviter des mouvements cash impossibles à expliquer. Un payout retardé mais documenté coûte moins cher qu’un payout rapide qui déclenche ensuite litige, correction et suspicion vendeur.
- Créer une piste d’audit par wallet : entrée, transfer, commission, réserve, payout, refund et correction.
- Bloquer les corrections sans motif métier et propriétaire identifié.
- Distinguer blocage KYC, risque vendeur, erreur technique et règle de réserve.
- Rapprocher les soldes avant chaque campagne de reversement importante.
Cette discipline transforme Mangopay en socle finance exploitable. La plateforme peut alors scaler les vendeurs sans perdre la confiance sur le sujet le plus sensible : où se trouve l’argent et pourquoi.
Conclusion : le wallet doit rester auditable
Mangopay API est puissante pour les modèles multi-vendeurs si chaque wallet, transfert et payout reste auditable. C’est la condition pour scaler sans perdre la finance.
Pour la comparaison PSP, voyez API paiement : choisir selon le modèle.
