Relier Mollie à votre logiciel de gestion : ce que permet l'API

Quelles ressources l'API Mollie ouvre-t-elle à votre logiciel ?

L'API Mollie est une API REST : chaque ressource se crée, se lit ou se modifie par une requête HTTPS vers https://api.mollie.com/v2, et un paiement se crée par un POST sur /v2/payments. Ses familles de ressources, d'après la documentation consultée en octobre 2026 :

Trois paramètres d'un paiement Mollie comptent pour un logiciel de gestion. Le champ metadata accepte environ 1 Ko de données libres, de quoi y ranger le numéro de facture ou de dossier. La description est limitée à 255 caractères, et Mollie la tronque au lieu de la refuser. Après la création, le client est redirigé vers l'adresse renvoyée dans _links.checkout, la page de paiement hébergée par Mollie.

Clé Test, clé Live, jeton d'organisation : qui s'authentifie comment ?

Chez Mollie, le mode d'authentification dépend de qui appelle l'API.

• Les clés API donnent accès à un profil de paiement. Elles vont par paires : une clé Test pour développer, une clé Live pour encaisser réellement. C'est la voie habituelle quand votre propre logiciel encaisse pour votre propre entreprise.
• Les jetons d'accès avancés (advanced access tokens) agissent au niveau de l'organisation et peuvent être restreints à un mode ou à un profil ; seuls les utilisateurs au rôle Admin peuvent aujourd'hui en créer.
• Les jetons d'application OAuth servent à appeler l'API au nom de clients connectés, avec leur consentement, dans le cadre de Mollie Connect. Mollie demande d'utiliser OAuth, et non des clés API, pour toute intégration tierce.

Le secret d'une clé n'est visible qu'à sa création, précise Mollie : il part directement dans le coffre de secrets du serveur, jamais dans le code source ni dans une application mobile. Pour la renouveler sans coupure, la documentation Mollie conseille de créer une seconde clé, de basculer le logiciel dessus, puis seulement de supprimer l'ancienne.

Le mode test de Mollie suffit-il pour recetter l'intégration ?

Le mode test de Mollie suffit pour les paiements, pas pour la partie comptable. En test, les paiements et les autres ressources sont isolés des données réelles, et un écran de paiement de test permet de choisir le statut final sans dépenser d'argent. Pour simuler un refus de carte, Mollie publie des montants dits magiques : un paiement de 1 001,00 euros forcé en échec produit par exemple le motif invalid_card_number.

Trois limites sont à connaître avant la recette :

• seul l'euro est accepté en mode test ;
• les endpoints des opérations comptables, dont les versements (settlements) et les soldes (balances), ne fonctionnent pas en mode test : le rapprochement se vérifie donc sur les premières opérations réelles ;
• les webhooks sont appelés en test comme en production, à une adresse joignable depuis internet : localhost ne reçoit rien.

Comment traiter un webhook Mollie sans se tromper de statut ?

Le webhook Mollie est volontairement minimal. Mollie envoie un POST au format application/x-www-form-urlencoded qui contient un seul paramètre, id, sans le nouveau statut. Le logiciel relit la ressource par l'API et n'agit que si le statut a changé, ce qui neutralise un appel falsifié : un faux message ne peut pas faire passer pour payée une commande qui ne l'est pas.

Le webhook part sur les statuts paid, authorized, expired, failed et canceled, sur les remboursements et sur les contestations. Il n'est pas appelé quand un moyen de paiement a été imposé à la création et que le client annule sur la page de paiement : seule une annulation sur l'écran de choix du moyen de paiement, où il est alors renvoyé, passe le paiement en canceled. Le logiciel relit donc lui-même les paiements restés ouverts.

Cinq circuits Mollie pour une PME

1. La facture payable en ligne. À l'émission d'une facture, le logiciel crée un lien par la Payment Links API et l'insère dans le courriel ou le PDF. Mollie destine ces liens aux clients qui paient à leur rythme, les paiements créés par la Payments API ayant une durée de vie courte. Le webhook du paiement associé solde la facture ; la relance des retards est traitée sur notre page pour automatiser les relances d'impayés.
2. Le contrat de maintenance. Le logiciel crée le client (POST /v2/customers), puis un premier paiement avec sequenceType à first : réglé par carte, il crée un mandat de type creditcard. Un abonnement Mollie prend le relais à l'intervalle choisi, et chaque paiement généré déclenche un webhook ; relu par l'API, il porte son subscriptionId.
3. La location ou la précommande. Avec captureMode à manual, le paiement est seulement autorisé à la commande et capturé plus tard, quand le matériel part. En capture automatique, le paramètre captureDelay diffère la capture de 7 jours au plus.
4. Le rapprochement du mois. Un versement Mollie (settlement) est le virement du solde vers le compte bancaire ; l'API liste les paiements, remboursements, captures et contestations qu'il regroupe. Pour une comptabilité plus précise, Mollie indique que la Balances API peut être mieux adaptée.
5. La place de marché. Une plateforme qui encaisse pour plusieurs vendeurs passe par Mollie Connect et OAuth : chaque vendeur autorise la plateforme, qui crée les paiements en son nom.

Limites d'appels, doublons et reprise : les règles de Mollie

Mollie ne publie pas de plafond unique. Les limites sont calculées pour chaque marchand, en requêtes par seconde, différentes selon les endpoints, avec des compteurs séparés pour la lecture et l'écriture. Un dépassement renvoie une erreur HTTP 429 avec un en-tête Retry-After, et les en-têtes RateLimit et RateLimit-Policy indiquent le quota restant à chaque réponse. Une hausse se demande depuis le tableau de bord Mollie.

Contre les doublons, tous les POST acceptent un en-tête Idempotency-Key, idéalement un UUID. Pendant une heure, une requête rejouée avec la même clé renvoie la réponse initiale ; la même clé avec d'autres paramètres provoque une erreur 400, et une requête concurrente une erreur 409. Ces clés sont liées à l'identifiant d'API utilisé : après une rotation, elles ne sont plus reconnues.

Pour les données personnelles, le logiciel n'envoie à Mollie que ce que le paiement exige et ne place dans metadata qu'une référence interne, jamais une donnée sensible. Notre guide RGPD et logiciel métier détaille ces obligations.

Extension Mollie ou développement sur mesure ?

Mollie liste des intégrations prêtes à l'emploi pour les plateformes e-commerce (WooCommerce, Shopify, PrestaShop, Magento, Shopware, Wix et d'autres), pour Salesforce et pour Odoo, ainsi qu'une liaison sans code avec Pennylane. Pour une boutique standard, l'extension officielle suffit.

Le sur-mesure se justifie quand le paiement naît dans un logiciel qu'aucune extension ne connaît : devis signé dans un CRM, dossier de location, inscription à une formation, intervention terminée. Il se justifie aussi quand les versements doivent descendre en comptabilité selon vos propres règles ; dans ce cas, voyez aussi notre page sur l'intégration Pennylane.

Ce que YMHB Web livre pour une intégration Mollie

YMHB Web commence par le cadrage : quand le logiciel crée un paiement, quel statut métier dépend de quel statut Mollie, que deviennent les paiements abandonnés. Le chiffrage vient après. Le développement et la recette se font avec la clé Test de votre compte, et la clé Live n'est posée qu'à la mise en service.

• un point de réception des webhooks qui répond 200 sans attendre et relit chaque ressource par l'API avant d'agir ;
• des clés d'idempotence sur toutes les créations, et une relecture planifiée des paiements restés ouverts ;
• un journal des appels et un écran des paiements en anomalie ;
• le code, déposé chez vous et documenté, et des clés qui restent dans votre compte Mollie.

La logique d'ensemble de ces connexions est décrite sur notre page connecter ses logiciels par API, et la réalisation technique sur notre page API et intégrations.