Une intégration API Mangopay provoque rarement une douleur parce qu'un pay-in carte répond mal en sandbox. La souffrance arrive quand un vendeur OWNER n'est pas KYC, quand un wallet contient des fonds qui ne doivent pas partir, quand un transfer n'est pas rapproché, ou quand un payout sort vers un compte bancaire non maîtrisé.
Le vrai sujet est de respecter la logique marketplace de Mangopay: users, wallets, pay-ins, transfers, payouts, refunds, KYC, hooks et events racontent tous une partie différente de l'argent. Les traiter comme un simple PSP de checkout crée une dette de cantonnement.
Vous allez comprendre comment décider qui peut payer, qui peut recevoir, quand un wallet devient exploitable, comment traiter `KYC_SUCCEEDED`, `PAYIN_NORMAL_SUCCEEDED`, `TRANSFER_NORMAL_SUCCEEDED` et `PAYOUT_NORMAL_SUCCEEDED`, et quoi bloquer quand la preuve financière manque.
Pour poser ce cadre sans bricolage, notre accompagnement en intégration API peut relier Mangopay à votre marketplace, votre ERP, votre OMS, votre comptabilité et vos outils support. Le sujet se rattache aussi à l'offre API paiement et à la page intégrateur Mangopay quand le besoin porte spécifiquement sur ce connecteur.
Pour qui Mangopay devient un sujet de run
Mangopay devient critique pour les marketplaces, plateformes de services, modèles de commission, cagnottes, réservations, fintechs et produits qui doivent séparer l'argent du client, l'argent du vendeur et les frais plateforme.
Le signal faible se voit quand une équipe parle d'un paiement réussi sans savoir si les fonds sont dans le bon wallet, si le seller peut recevoir un payout, ou si le KYC bloque encore le reversement.
Contrairement à ce que l'on croit souvent, le plus difficile n'est pas de collecter une carte. En réalité, la valeur du connecteur se joue dans le passage pay-in, wallet, transfer, payout, refund et preuve comptable.
1. Créer users et KYC sans bloquer les vendeurs
Distinguer PAYER et OWNER dès le modèle interne
Mangopay distingue les users `PAYER`, qui peuvent faire des pay-ins vers leurs wallets et des transfers, et les users `OWNER`, qui peuvent aussi recevoir des transfers sur leurs wallets. Cette différence doit exister dans le domaine métier.
Un acheteur simple, un vendeur, un fournisseur, un prestataire ou une plateforme n'ont pas le même profil réglementaire. Mélanger ces rôles crée des erreurs tardives, au moment où l'argent doit être transféré ou payé.
Le connecteur doit donc relier user Mangopay, compte interne, rôle marketplace, statut vendeur, capacité de payout, KYCLevel, TermsAndConditionsAccepted et owner métier. Sans cette table, chaque blocage compliance devient une chasse aux indices.
Traiter KYCLevel REGULAR comme une condition de payout
La documentation indique qu'un OWNER peut demander une vérification KYC, et qu'une vérification réussie lui donne `KYCLevel` `REGULAR` avec capacité à demander des payouts. Cette règle doit gouverner l'activation vendeur.
Les documents KYC peuvent avoir des statuts `CREATED`, `VALIDATION_ASKED`, `VALIDATED`, `REFUSED` ou `OUT_OF_DATE`. Un document refusé ou obsolète doit être recréé avant nouvelle soumission, ce qui change le support vendeur.
Si 12 vendeurs ont des fonds disponibles mais un KYC non validé depuis 5 jours, alors la priorité est de bloquer les promesses de reversement. Le seuil touche directement la trésorerie perçue et la relation seller.
Gérer SCA et PendingUserAction sans perdre le vendeur
Les objets users SCA introduisent notamment `UserStatus` `PENDING_USER_ACTION` et `PendingUserAction.RedirectUrl`. Ce lien sert à rediriger l'utilisateur vers une session SCA, avec un `ReturnUrl` encodé à ajouter.
Mangopay précise que la session SCA expire 10 minutes après génération. Le SI doit donc gérer expiration, relance, nouvelle session, message vendeur et état interne, au lieu de stocker un lien comme preuve durable.
Le bon runbook distingue vendeur à compléter, vendeur vérifié, vendeur refusé, vendeur obsolète et vendeur inactif. Chaque état doit avoir un message, une action support et une règle de blocage payout.
2. Modéliser wallets, pay-ins et fonds cantonnés
Considérer le wallet comme l'unité de cantonnement
Le Wallet object est un e-wallet dans l'environnement Mangopay. La documentation indique qu'il peut recevoir des fonds via pay-in, déplacer des fonds par transfer, convertir entre devises, ou retirer des fonds vers un compte bancaire via payout.
Un wallet possède un owner unique, une devise, un solde et un `FundsType` comme `DEFAULT`, `FEES` ou `CREDIT`. La plateforme doit savoir si le solde appartient à un utilisateur, aux frais plateforme ou à une gestion de repudiation.
Le mapping utile relie wallet ID, user ID, owner interne, devise, solde attendu, type de fonds, commande, seller, litige et dernière transaction. Sans cela, un solde positif n'est pas une preuve exploitable.
Créer les pay-ins avec la bonne destination financière
Un pay-in alimente un wallet. Selon le moyen de paiement, Mangopay expose des familles comme card pay-ins, banking pay-ins, APM pay-ins, pay by bank, direct debits ou virtual IBAN, avec des statuts de transaction.
Le SI doit décider si le pay-in crédite un wallet acheteur, un wallet seller, un wallet technique ou un wallet de transit. Cette décision détermine ensuite qui peut transférer, rembourser ou demander un payout.
La bonne règle consiste à refuser tout pay-in dont la destination financière ne peut pas être expliquée. La conversion checkout vers wallet doit être prouvée avant de déclencher livraison, commission ou libération vendeur.
Écrire les montants en plus petite subdivision de devise
Mangopay représente les amounts dans la plus petite subdivision de la devise, par exemple 12,60 EUR sous la forme `1260`. Cette convention doit être appliquée partout, y compris frais, refunds, transfers et payouts.
Un arrondi mal placé crée une dette silencieuse. La boutique parle en euros, le wallet parle en centimes, la commission peut être calculée ligne par ligne, et la comptabilité exige une ventilation exacte.
Le connecteur doit journaliser montant brut, frais plateforme, montant crédité, devise, taux éventuel et source de calcul. Cette preuve évite de traiter un écart de centime comme un incident Mangopay.
3. Transférer et payer sans perdre la preuve
Séparer transfer interne et payout externe
Un transfer déplace des fonds d'un wallet vers un autre wallet. Un payout retire des fonds d'un wallet vers un compte bancaire externe ou un Recipient. Ces deux actions n'ont pas la même preuve ni le même risque.
Le transfer peut représenter une commission vendeur, une libération après livraison ou une compensation interne. Le payout représente une sortie bancaire, avec éligibilité, recipient, mode demandé et suivi financier.
Le back-office doit afficher source wallet, destination wallet, payout, statut, fees, devise, user, commande et justificatif. Une action financière sans ces liens devient difficile à défendre en cas de litige.
Créer le Recipient avant de promettre le virement
Mangopay s'appuie sur le Recipient pour les payouts, et les anciens Bank Account objects actifs ont été migrés vers Recipients. Le payout doit donc être relié à un moyen de destination bancaire compatible.
Les modes de payout incluent notamment `STANDARD`, `INSTANT_PAYMENT`, `INSTANT_PAYMENT_ONLY` et `RTGS_PAYMENT` selon devise, destination et activation. Le connecteur ne doit pas promettre l'instantané si le contrat ne le permet pas.
Si 7 vendeurs demandent un payout instantané mais que leur Recipient ne supporte pas le mode demandé, alors la priorité est d'afficher l'éligibilité avant demande. Le seuil signale déjà une dette de promesse seller.
Surveiller Verification of Payee quand elle s'applique
Mangopay signale que Verification of Payee peut impacter les payouts pour certaines plateformes offrant des User-Owned Accounts comme Virtual Account ou Banking Alias. Cette contrainte ne doit pas rester dans un commentaire technique.
Le SI doit isoler les cas concernés, afficher la cause, retenir le payout si besoin et donner une consigne support lisible. Un vendeur ne doit pas découvrir une vérification bancaire au moment où il attend son argent.
Cette prudence protège aussi la conformité. Un payout bancaire est une sortie de fonds, et le connecteur doit savoir expliquer pourquoi il part, pourquoi il attend, ou pourquoi il est refusé.
4. Rembourser pay-ins et transfers sans écart
Choisir le bon niveau de refund
Mangopay permet des refunds sur pay-ins et transfers, et documente aussi des cas de payout refund initiés par Mangopay. Le choix dépend du chemin exact de l'argent dans les wallets.
Si le pay-in a crédité un wallet puis qu'un transfer a déjà envoyé les fonds au seller, le remboursement ne se résume pas à renvoyer l'argent au buyer. Il faut aussi compenser le wallet seller et la commission éventuelle.
Le modèle interne doit donc connaître pay-in initial, transfer associé, wallet débité, wallet crédité, fees, commande, retour produit et statut client. Sans cela, le refund peut résoudre le client et casser la finance.
Mettre les refunds partiels en quarantaine utile
Un refund partiel doit montrer montant, devise, ligne de commande, seller, frais, transfer, wallet et effet sur solde. Un simple statut `SUCCEEDED` ne suffit pas si l'avoir interne raconte un autre montant.
La file de quarantaine doit retenir les refunds qui ne peuvent pas prouver leur chemin financier. Elle doit afficher l'écart, l'owner, la prochaine action et la date limite de résolution.
Cas concret: si 6 refunds partiels dépassent 3 jours sans rapprochement avec les transfers, alors le bon arbitrage est de bloquer les refunds automatiques suivants. Le seuil indique une dette de clôture déjà mesurable.
Conserver les causes de refus et d'échec
Les transactions Mangopay portent un statut comme `CREATED`, `SUCCEEDED` ou `FAILED`, avec des résultats et messages selon les objets. Le support doit recevoir une traduction métier, pas seulement un code.
Une erreur de wallet, de solde, de KYC, de recipient, de moyen de paiement ou de devise ne produit pas la même reprise. Chaque famille doit avoir un owner, une alerte et une consigne client différente.
Le runbook doit aussi distinguer refund demandé, refund réussi, refund refusé, transfer compensé et payout bloqué. Cette précision évite de promettre un remboursement alors que l'argent a déjà changé de wallet.
5. Lire webhooks et events comme filet de reprise
Traiter le Hook comme une notification à relire
Les webhooks Mangopay reposent sur le Hook object et envoient une requête GET avec `EventType`, `RessourceId` et `Date`. La faute d'orthographe `RessourceId` est documentée et doit être traitée telle quelle.
Le webhook ne transporte pas tout le dossier. Il signale qu'un événement est arrivé sur une ressource, par exemple `PAYIN_NORMAL_SUCCEEDED` avec l'ID du pay-in concerné. Le SI doit relire la ressource avant d'appliquer l'effet métier.
Cette méthode évite de transformer une notification courte en source unique. Le connecteur garde l'event, vérifie l'objet, compare le montant, puis applique la décision de livraison, transfer, payout ou support.
Répondre 200 vite pour ne pas casser les retries
Mangopay demande que l'URL de webhook réponde avec un statut HTTP 200 en moins de 2 secondes pour que la notification soit considérée valide. Le endpoint doit aussi être accessible en TLS 1.2+ avec certificat valide.
Si la notification échoue, Mangopay retente toutes les 10 minutes pendant la première heure, puis toutes les 8 heures pendant 3 jours. Après 100 échecs consécutifs, le Hook devient `INVALID` et les notifications s'arrêtent.
Le handler doit donc répondre vite, journaliser, mettre en file, puis traiter. Si 25 échecs consécutifs apparaissent sur un EventType, la priorité est de réparer le hook avant que la plateforme perde sa vue temps réel.
Utiliser la liste des events pour récupérer les manqués
Mangopay fournit un endpoint pour lister les events déclenchés par la plateforme, même si aucun Hook n'a été souscrit pour l'EventType concerné. La documentation indique une récupération jusqu'à 45 jours en arrière.
Cette capacité doit être intégrée au runbook. Si un hook devient `INVALID`, si un firewall bloque les notifications, ou si un traitement a planté, l'équipe doit pouvoir reconstruire la période manquante.
La reprise utile relie EventType, RessourceId, Date, objet relu, effet déjà appliqué, effet manquant et owner. Sans cette table, la récupération d'events peut créer des doublons au lieu de réparer.
6. Sécuriser idempotence, SCA et accès API
Utiliser Idempotency-Key sur les POST sensibles
Mangopay supporte l'idempotence pour tous les appels POST avec le header `Idempotency-Key`. La clé évite de répéter un effet lors d'un retry réseau et permet de retrouver une réponse manquée via l'API response endpoint.
La clé doit contenir entre 16 et 36 caractères alphanumériques ou tirets, et Mangopay recommande un UUID. Une même clé utilisée dans les 24 heures bloque les requêtes suivantes avec un HTTP 409.
Le piège consiste à réutiliser une clé après un appel failed. Mangopay indique que les demandes idempotentes sont bloquées quel que soit le code HTTP du premier appel, donc le SI doit journaliser intention, clé et résultat.
Séparer API key, droits et environnements
Le connecteur doit isoler ClientId, API key, environnement sandbox, production, permissions, scopes, webhook URL, hooks, email d'alerte et secrets applicatifs. Un mauvais couple environnement clé peut déplacer un flux réel dans une zone de test.
Les scopes Mangopay permettent de limiter les droits par action, par exemple autour de refunds, KYC, payouts ou bank accounts. Le principe de moindre privilège doit être appliqué aux workers, outils support et tâches finance.
La supervision sécurité doit montrer quel service appelle quel endpoint, avec quelle clé, quelle intention et quel résultat. Cette trace raccourcit les enquêtes en cas de 401, 403, quota ou erreur de permission.
Contrôler l'accès wallet quand SCA s'applique
Mangopay documente des exigences SCA sur certains accès wallet considérés comme consultation de solde. Les endpoints de wallet concernés doivent être traités comme sensibles, surtout dans des interfaces vendeur.
L'interface ne doit pas appeler ces endpoints sans prévoir redirection, expiration, reprise et message utilisateur. Un solde visible mais non actualisable peut créer une incompréhension seller.
Le bon arbitrage consiste à séparer lecture technique, affichage vendeur et preuve comptable. Le solde affiché doit dire s'il est actualisé, approximatif, bloqué par SCA ou en attente de rellecture.
7. Rapprocher transactions, wallets et comptabilité
Utiliser la Transaction comme vocabulaire commun
Mangopay indique qu'une Transaction représente tout mouvement d'argent depuis ou vers un wallet, notamment pay-ins, payouts et transfers. Les statuts de transaction incluent `CREATED`, `SUCCEEDED` et `FAILED`.
Le rapprochement utile commence par cette table commune. Il relie AuthorId, CreditedUserId, DebitedFunds, CreditedFunds, Fees, wallet, devise, commande, seller, facture, écriture interne et période de clôture.
Une transaction `SUCCEEDED` ne dit pas seule quelle promesse métier appliquer. Il faut connaître son type, son origine, sa destination et l'objet métier qui l'a déclenchée.
Tenir compte des périodes de disponibilité des données
La documentation Mangopay signale que certaines données de transaction sont retenues 13 mois depuis `CreationDate`. Une plateforme doit donc organiser ses exports, journaux et archives internes avant cette limite.
Le SI ne peut pas dépendre uniquement de rellectures API tardives pour une clôture annuelle, un litige vendeur ou une preuve fiscale. Il doit exporter les informations financières utiles selon une cadence définie.
La routine mensuelle doit conserver transactions, events, wallets, refunds, transfers, payouts, KYC status et écritures ERP. Cette archive devient la preuve métier quand les données API ne suffisent plus.
Classer les écarts par cause opérationnelle
Les écarts Mangopay peuvent venir d'un KYC refusé, d'un wallet mal propriétaire, d'un refund partiel, d'un transfer absent, d'un payout bloqué, d'un hook invalid ou d'un event non rejoué.
Le SI doit classer l'écart avec cause, montant, ancienneté, wallet, user, transaction, commande, owner et prochaine action. Sans cette taxonomie, la finance demande au support de résoudre un problème technique.
La routine quotidienne compare events, wallets, transactions, commandes, factures, commissions et payouts. Chaque divergence doit sortir avec un statut de résolution, pas seulement un commentaire dans un tableur.
8. Erreurs fréquentes sur Mangopay
Collecter avant de savoir qui possède les fonds
La première erreur consiste à créer un pay-in sans modéliser clairement le wallet destinataire et le propriétaire économique. Le paiement réussit, mais personne ne sait ensuite si l'argent doit rester, bouger, être remboursé ou sortir.
Le symptôme apparaît quand la marketplace doit ventiler une commande multi-seller après coup. Le wallet technique devient une zone grise, la commission n'est pas prouvée, et le seller ne comprend pas son solde.
La correction est nette: définir avant checkout le wallet de destination, les fees, le futur transfer, les conditions de payout et le cas de refund. Une collecte sans destination financière explicite doit être refusée.
Le signal faible se voit quand le même paiement apparaît dans trois vues différentes avec trois propriétaires possibles. Avant que le volume augmente, il faut trancher wallet, owner, fees, règle de libération et responsable de contrôle avant toute promesse seller ou export finance.
Activer un seller avant KYC et SCA exploitables
La deuxième erreur consiste à promettre le reversement à un seller dont le KYC est `VALIDATION_ASKED`, `REFUSED`, `OUT_OF_DATE` ou dont la session SCA est encore `PENDING_USER_ACTION`.
Le signal faible se voit quand le support répond aux vendeurs avec des captures d'écran au lieu de lire le statut Mangopay. Cette situation transforme la conformité en conversation commerciale frustrante.
La réponse opérationnelle est de séparer publication d'offre, réception de transfer, demande de payout et payout exécuté. Chaque étape doit indiquer ce que le seller peut faire et ce qu'il doit compléter.
Traiter les hooks comme des callbacks complets
La troisième erreur consiste à appliquer un effet métier directement depuis `EventType` et `RessourceId`, sans relire la ressource. Le hook est un signal, pas un dossier complet.
Le risque augmente quand un hook échoue, quand Mangopay retente, ou quand la plateforme rejoue des events des 45 derniers jours. Sans idempotence, une reprise peut doubler un transfer, un mail ou une écriture.
La méthode fiable consiste à journaliser le hook, répondre 200 rapidement, relire l'objet, comparer l'état attendu, puis appliquer l'effet une seule fois. Le owner de reprise doit être visible.
Rapprocher les payouts trop tard
La quatrième erreur se voit en clôture. Les sellers ont reçu leurs fonds, les wallets ont changé, mais l'ERP n'a pas relié payout, transfer, fees, refund et facture.
Par exemple, si 8 payouts restent non rapprochés pendant 5 jours ouvrés, alors la priorité est de bloquer les exports automatiques. Le seuil indique une dette de clôture plus risquée qu'un retard de reporting.
La réponse consiste à reconstruire chaque payout depuis wallet, transfer, fees, seller, transaction et écriture. La sortie bancaire doit devenir explicable sans tableur improvisé.
9. Plan d'action pour livrer le connecteur
Commencer par la carte des flux d'argent
Le plan d'action commence par les flux d'argent, pas par les endpoints. Il faut savoir qui paie, quel wallet reçoit, quel wallet transfère, qui peut demander payout et quelle écriture confirme la sortie.
La chronologie de base relie user, KYC, wallet, pay-in, transfer, refund, payout, hook, event et transaction. Chaque étape doit avoir une preuve, un statut interne et un propriétaire.
Cette feuille de route oblige marketplace, finance, support, produit et technique à parler le même langage. Si un wallet positif déclenche la même action qu'un payout validé, le modèle est encore dangereux.
- D'abord, figer les sources de vérité pour buyer, seller, user Mangopay, wallet, KYC, pay-in, transfer, refund, payout et facture.
- Ensuite, développer users, wallets, pay-ins, transfers, payouts, refunds, hooks, events, idempotence et reconciliation financière contrôlée.
- Puis, écrire les blocages sur KYC refusé, SCA expirée, wallet incohérent, refund partiel, hook invalid et payout non rapproché.
- À valider avant volume, prouver KYC failed, pay-in succeeded, transfer succeeded, refund partiel, hook retry et payout reconstitué.
- À refuser, toute automatisation qui ne peut pas montrer user, wallet, transaction, montant, owner, idempotence et décision finale.
Dessiner le modèle de données de reprise
La table de reprise doit porter user ID, wallet ID, pay-in ID, transfer ID, payout ID, refund ID, hook ID, EventType, RessourceId, statut, montant, devise, seller et action suivante.
Elle doit aussi conserver les liens vers logs de worker, ticket support, écriture ERP, commission, facture, avoir et relance vendeur. Cette granularité évite de traiter un incident financier comme un simple problème de webhook.
Si 16 dossiers nécessitent une intervention après la recette, la priorité est de réduire les causes racines: KYC mal routé, wallet incomplet, transfer tardif, refund non rapproché ou hook non rejoué.
Le contrat de traitement doit aussi décrire entrées, sorties, dépendances, owner, monitoring, rollback, journalisation, seuils, file de reprise et responsabilités support. Cette précision évite de découvrir le vrai modèle d'exploitation pendant un incident vendeur.
- À afficher dans chaque dossier: user, wallet, KYC, transaction, EventType, montant, seller, owner et prochaine action.
- À bloquer automatiquement: seller non REGULAR, wallet sans owner, hook INVALID, refund sans avoir et payout non rapproché.
- À revoir chaque semaine: délais KYC, taux de refused, hooks en échec, soldes bloqués et montants en quarantaine.
Mettre la supervision dans les routines marketplace
La supervision minimale affiche users PAYER, users OWNER, KYC pending, KYC refused, wallets avec solde, pay-ins succeeded, transfers succeeded, refunds retenus, hooks invalid et payouts non rapprochés.
Une fiche de mise en oeuvre doit détailler entrées, sorties, responsabilités, owner, instrumentation, monitoring, runbook, file de reprise, seuils et contrat d'alerte. Cette fiche rend l'exploitation indépendante de l'équipe qui a développé.
Le tableau utile distingue argent acheteur, argent seller, frais plateforme, charge support, risque conformité et dette technique. Une croissance GMV peut cacher une dette si les wallets et payouts ne sont pas rapprochés.
10. Tester KYC, payout et webhook
Rejouer le flux nominal sans raccourci
Le test nominal doit créer un user, obtenir le bon rôle, créer un wallet, alimenter le wallet par pay-in, transférer vers le wallet seller, puis demander un payout éligible et rapprocher la transaction.
Il faut prouver plus qu'un paiement carte réussi. La recette doit montrer user, wallet, KYCLevel, amount en plus petite subdivision, pay-in, transfer, fees, payout, hook et écriture comptable.
Le bon résultat est une chronologie lisible dans le back-office. Le support doit comprendre pourquoi le seller peut vendre, recevoir, attendre, compléter son KYC ou être bloqué.
Simuler KYC refused, OUT_OF_DATE et hook invalid
Le test doit couvrir `KYC_FAILED`, `KYC_OUTDATED`, `USER_KYC_REGULAR`, hook en échec, hook devenu `INVALID`, event récupéré après coup et resoumission impossible d'un document refusé par conformité.
Chaque cas doit produire une décision visible: bloquer payout, demander nouveau document, relancer seller, empêcher transfer, reconstruire events ou escalader compliance. Une erreur KYC sans message seller devient un coût support.
La recette est réussie quand une personne hors projet peut expliquer pourquoi un seller n'est pas payable, quel document manque, quel event fait foi et quelle action déclenche la reprise.
Tester refund, transfer et payout comme une clôture réelle
Le refund partiel doit être testé avec pay-in initial, transfer déjà effectué, frais plateforme et avoir interne. Le test doit vérifier que la compensation ne laisse pas le wallet seller incohérent.
Le payout doit ensuite être rapproché avec la transaction, le wallet, le seller, la facture et l'écriture comptable. La preuve n'est pas complète tant que la finance ne peut pas expliquer le montant.
La mini-clôture de test doit contenir 3 pay-ins, 2 transfers, 1 refund partiel, 1 payout et 1 hook rejoué. Si chaque mouvement est expliqué, le connecteur commence à être exploitable.
11. Fixer les seuils de go-live Mangopay
Choisir des critères qui protègent seller et finance
Le go-live doit être conditionné par des preuves de cycle complet, pas par la réussite d'un pay-in isolé. Il faut valider user, KYC, wallet, pay-in, transfer, refund, payout, hook, event et idempotence.
Les critères utiles portent sur taux de KYC validés, délai moyen de validation, solde wallet bloqué, transfers non rapprochés, refunds retenus, hooks en échec, payouts non rapprochés et tickets seller.
La décision peut rester progressive. Un lancement sur une verticale, un pays, une devise ou une catégorie seller vaut mieux qu'une ouverture globale qui mélange KYC, payouts et retours produits dès la première semaine.
Bloquer les anomalies avant d'élargir les volumes
Si un hook ne répond pas 200 sous 2 secondes pendant la recette, il faut attendre avant go-live. Mangopay retente, puis peut invalider le Hook après trop d'échecs, ce qui coupe la visibilité.
Si les payouts ne se rapprochent pas automatiquement, il faut attendre aussi. Le problème peut sembler comptable, mais il touchera sellers, commissions, cash, litiges et confiance dans la marketplace.
Le même principe vaut pour les KYC refusés sans message ou les refunds partiels sans compensation. Tant que la réponse métier n'est pas écrite, le lancement repose sur improvisation.
Organiser une mise en production observable dès le premier seller
Le premier seller doit être suivi comme une opération, avec marketplace, support, finance et technique. Le contrôle vise à sécuriser les décisions qui changent solde, offre publiée, payout et remboursement.
Les métriques doivent être lues à chaque étape: user créé, KYC soumis, KYC validé, wallet actif, pay-in succeeded, transfer succeeded, refund, hook reçu et payout attendu. Une dérive légère peut éviter une crise seller.
La revue de fin de cycle doit produire une liste courte: incidents clos, dossiers retenus, causes racines, seuils à ajuster et décision d'élargissement. Sans cette revue, l'intégration ne progresse pas.
12. Organiser support et amélioration continue
Donner au support une fiche orientée seller et wallet
Le support doit disposer d'une fiche qui part du seller, puis montre user, UserCategory, KYCLevel, UserStatus, wallet, balance, pay-ins, transfers, refunds, payouts, hooks et action autorisée.
Cette fiche doit traduire les états. `VALIDATION_ASKED`, `VALIDATED`, `REFUSED`, `OUT_OF_DATE`, `PENDING_USER_ACTION`, `SUCCEEDED` ou `FAILED` ne doivent jamais devenir des libellés interchangeables pour vendeurs actifs.
Une bonne fiche évite trois erreurs: promettre un payout à un seller non REGULAR, rembourser un pay-in sans compenser un transfer, ou croire qu'un hook suffit sans relire la ressource.
Suivre les trente premiers jours avec peu de métriques mais les bonnes
Les trente premiers jours doivent mesurer la qualité de décision: KYC en attente, KYC refused, wallets créditeurs, refunds retenus, hooks invalid, events rejoués, payouts réussis et écarts de transaction.
Il faut segmenter par rôle user, pays, devise, catégorie seller, canal de paiement, moyen de payout, ancienneté vendeur et montant moyen. Cette segmentation évite de corriger toute l'intégration pour un problème local.
Une revue courte chaque semaine suffit si elle produit des décisions concrètes. Corriger un mapping, clarifier une fiche support, ajuster un seuil ou changer une relance vaut mieux qu'un dashboard exhaustif sans arbitrage.
Améliorer Mangopay depuis les preuves de production
Les améliorations doivent partir des symptômes réels. Si les KYC refused montent, il faut relire les causes. Si les hooks deviennent invalid, il faut revoir endpoint, firewall, temps de réponse et file de traitement.
Si les payouts tardent à être rapprochés, il faut revoir transactions, exports, wallet, écriture ERP et ownership finance. Si les refunds produisent des écarts, il faut renforcer la compensation transfer.
La feuille de route doit rester courte: une règle de statut, une preuve support, une alerte finance ou une reprise automatisée. Tout ce qui ne réduit ni risque seller, ni délai support, ni écart comptable peut attendre.
Questions fréquentes sur l'API Mangopay
Quel est le flux Mangopay minimal? Le flux minimal crée user, wallet, pay-in, transfer ou payout selon le modèle, puis rapproche transactions, webhooks, events, refunds et écritures internes.
Pourquoi distinguer PAYER et OWNER? `PAYER` peut faire des pay-ins et transfers, tandis que `OWNER` peut recevoir des transfers et demander des payouts avec le niveau KYC attendu. Cette différence gouverne l'activation seller.
Comment gérer un hook manqué? Il faut journaliser le hook, relire la ressource, puis utiliser la liste des events pour récupérer jusqu'à 45 jours de signaux si une notification a été perdue ou invalidée.
Dawap peut-il accompagner cette intégration API? Oui. Dawap peut cadrer users, wallets, KYC, pay-ins, transfers, payouts, refunds, hooks, events, idempotence, monitoring, reprise et synchronisation ERP ou marketplace.
Guides complémentaires après Mangopay
Approfondir les architectures de paiement API avant arbitrage
La ressource paiement API aide à replacer Mangopay dans une architecture PSP plus large. Elle clarifie les responsabilités entre checkout, wallet, transfer, payout, refund et support.
Elle devient utile quand Mangopay cohabite avec carte bancaire, Stripe, PayPal, Adyen, Oney ou GoCardless. Le marchand peut comparer paiement instantané, cantonnement marketplace, reversement seller et preuves de règlement.
Cette comparaison aide aussi à choisir les abstractions mutualisables. Journaux d'audit, files de reprise, nomenclature d'erreurs et tableaux financiers peuvent être communs, tandis que les règles Mangopay restent isolées.
Sécuriser les doublons de pay-ins et transfers
La ressource idempotence API complète directement ce sujet. Elle aide à éviter doubles pay-ins, doubles transfers, doubles refunds et doubles écritures quand une tentative est rejouée.
Elle est particulièrement pertinente pour Mangopay, parce que les POST supportent `Idempotency-Key`, avec blocage dans les 24 heures et possibilité de retrouver une réponse manquée dans cette fenêtre.
Elle donne enfin un vocabulaire utile pour la reprise: effet irréversible, clé naturelle, journal d'exécution, concurrence, rejet contrôlé et compensation. Ces notions évitent de transformer un timeout en dette financière.
Piloter hooks, KYC et incident Mangopay
La ressource webhook ou polling API aide à décider quand traiter un hook Mangopay, quand relire user, wallet, pay-in, transfer ou payout, et quand garder un statut d'attente pour éviter une décision trop rapide sur un flux cantonné.
Si un KYC, un wallet, un transfer, un refund ou un payout bloque une marketplace, le runbook d'incident API donne le cadre pour borner le seller, le wallet ou le lot concerné, puis reprendre uniquement les mouvements à risque.
Rapprocher Mangopay avec ERP et comptabilité
La ressource réconciliation API devient utile dès que wallets Mangopay, transactions, ERP et comptabilité racontent des états différents. Elle donne un cadre pour identifier la source qui doit trancher.
Elle complète la partie marketplace en donnant une méthode pour classer les écarts: KYC bloqué, wallet mal owner, transfer absent, refund partiel, payout non rapproché ou hook non rejoué.
Elle permet surtout de sortir du rapprochement artisanal. Les écarts sont qualifiés par période, montant, statut, wallet, seller et système propriétaire, ce qui rend la correction défendable auprès de la finance.
Préparer les écritures financières aval
La ressource facturation électronique API prolonge le sujet quand un pay-in ou un payout Mangopay déclenche facture, avoir ou écriture comptable. Elle aide à cadrer les dépendances entre paiement, commission et document financier.
Elle devient utile quand une transaction marketplace ouvre une chaîne plus large: facture buyer, facture seller, commission, remboursement, contrôle TVA, reporting et synchronisation ERP. Le pay-in ne doit pas déclencher une écriture définitive trop tôt.
Pour passer du cadrage à l'exécution, la landing API paiement donne le cadre général, tandis que la page intégrateur Mangopay précise l'accompagnement possible sur ce connecteur.
Conclusion: brancher Mangopay sans dette de cantonnement
Une intégration API Mangopay fiable commence par une chronologie respectée: user, KYC, wallet, pay-in, transfer, refund, payout, hook, event et transaction. Chaque étape porte une preuve différente.
Les détails qui font la différence ne sont pas décoratifs: `UserCategory`, `KYCLevel`, `PendingUserAction.RedirectUrl`, `Idempotency-Key`, `EventType`, `RessourceId`, wallet ID, pay-in ID, transfer ID, payout ID et refund ID.
Le vrai coût d'un mauvais connecteur Mangopay apparaît rarement pendant le premier test. Il apparaît quand un seller non REGULAR attend un payout, quand un hook devient INVALID, ou quand un wallet positif ne rejoint pas la comptabilité.
Si vous devez intégrer Mangopay dans une marketplace robuste, notre accompagnement Integration API peut cadrer le flux, développer le connecteur, sécuriser les webhooks et donner au support les preuves nécessaires pour exploiter les wallets sans dette cachée.
