Piloter le prélèvement SEPA GoCardless depuis votre logiciel métier

Quels objets l'API GoCardless met-elle à disposition ?

L'API GoCardless couvre tout le cycle du prélèvement : l'autorisation donnée par le client (le mandat), les sommes à prélever, puis l'argent reversé sur votre compte. La référence de l'API range ses ressources par familles ; voici celles qu'un logiciel métier utilise au quotidien.

Votre logiciel crée les mandats et les paiements ; GoCardless lui renvoie les changements d'état. Un échéancier se crée sur un mandat déjà actif, soit en fournissant chaque date, soit en donnant une date de début, un intervalle et les montants, GoCardless calculant alors le calendrier.

Le calendrier SEPA que votre logiciel doit respecter

Un prélèvement SEPA n'est pas instantané : un logiciel qui marque une facture « payée » le jour de la demande se trompe. Le guide SEPA publié par GoCardless donne ces délais :

Conséquence pratique : le logiciel distingue au moins trois états, « demandé », « encaissé » et « reversé », et garde la possibilité d'un retour en arrière pendant plusieurs semaines. Pour une entreprise qui vit d'abonnements, une contestation reçue sept semaines après l'encaissement doit rouvrir la créance et la relance, pas seulement colorer une ligne en rouge.

Accès, environnement de test et limites de l'API GoCardless

• Authentification : chaque requête porte un jeton d'accès dans l'en-tête Authorization (schéma Bearer) et l'en-tête GoCardless-Version, dont la valeur courante est 2015-07-06. Le jeton se crée dans l'onglet Développeurs du tableau de bord et ne s'affiche qu'une fois.
• Bac à sable : un compte sandbox distinct, servi par api-sandbox.gocardless.com, permet de construire l'intégration sans mouvement d'argent. Des simulateurs de scénarios provoquent les cas difficiles : paiement réussi, paiement échoué faute de provision, paiement encaissé puis contesté, mandat refusé pour coordonnées erronées, mandat expiré.
• Débit : 1 600 requêtes par minute, réponse 429 au-delà ; une requête est interrompue après 29 secondes.
• Idempotence : en-tête Idempotency-Key de 128 caractères au plus, honoré au moins 30 jours ; une clé déjà utilisée renvoie une erreur 409 qui désigne l'objet existant.
• Webhooks : chaque envoi regroupe un ou plusieurs événements (250 au plus), signés en HMAC SHA256 dans l'en-tête Webhook-Signature avec le secret propre au point de réception. GoCardless attend la réponse 10 secondes au plus et tente la livraison 9 fois en tout.
• Bibliothèques officielles : Python, Java, Go, Ruby, Node.js, PHP et .NET, plus des SDK iOS et Android.

Un éditeur qui veut proposer GoCardless à ses propres clients passe par l'OAuth 2 de GoCardless : il déclare une application, obtient un identifiant et un secret, puis chaque client autorise l'accès à son compte en lecture seule ou en lecture et écriture, sans communiquer ses identifiants.

Les circuits de prélèvement les plus fréquents en PME

1. L'adhésion du client. À la signature d'un contrat de location, le logiciel crée une demande d'autorisation (Billing Request) et envoie le lien au client, qui autorise le prélèvement. L'activation du mandat arrive par webhook, la fiche client affiche « prélèvement en place » et le commercial n'a plus à appeler la comptabilité. Le métier est détaillé sur notre page logiciel de location de matériel.
2. La cotisation ou le loyer mensuel. Une fédération crée un abonnement GoCardless par adhérent ; chaque prélèvement remonte avec sa date prévue, et l'adhésion reste active tant que les paiements suivent.
3. La facture étalée. Une formation payable en trois fois devient un échéancier sur le mandat existant ; le logiciel affiche le reste dû après chaque échéance.
4. Le rejet et sa suite. Un prélèvement échoue faute de provision : l'événement arrive avec sa cause, le logiciel rouvre la facture et prévient le chargé de clientèle. Les offres Advanced et Pro de GoCardless incluent Success+, qui, selon GoCardless, représente automatiquement un paiement échoué au moment où le payeur a le plus de chances d'avoir les fonds ; le logiciel attend alors l'issue de la nouvelle tentative avant de relancer le client.
5. Le rapprochement bancaire. Chaque virement GoCardless et son détail permettent d'associer le montant reçu en banque aux factures soldées, sans pointage ligne à ligne. C'est la suite logique d'un travail pour éliminer les doubles saisies.

Doublons, lots, contestations : les pièges d'une intégration GoCardless

• Le double prélèvement : la documentation GoCardless recommande fortement une clé d'idempotence pour créer paiements et mandats, car une requête rejouée sans clé peut débiter deux fois. La clé doit rester la même d'un essai à l'autre pour une même facture.
• Le traitement par lots : un webhook pouvant contenir jusqu'à 250 événements, GoCardless conseille de les traiter de façon asynchrone et de garder la trace de ceux déjà traités.
• L'état réel : à réception d'un webhook, GoCardless conseille de relire l'état courant de la ressource par l'API plutôt que de se fier au seul message.
• Les contestations tardives : le logiciel doit savoir rouvrir une facture des semaines après son encaissement.
• Les coordonnées bancaires : l'IBAN d'un particulier est une donnée personnelle. Si GoCardless le conserve, le logiciel n'a pas besoin de le stocker en clair, et le traitement figure dans votre registre RGPD.
• Le coût : en France, l'offre Standard de GoCardless affiche 1 % + 0,20 € par transaction nationale, plafonné à 2 €, sans frais de mise en place, et 0,30 € par remboursement (tarif public hors TVA relevé en octobre 2026).

Intégration existante de votre logiciel ou connexion développée ?

Vérifiez d'abord si votre logiciel de facturation ou de gestion des adhérents propose déjà GoCardless. GoCardless documente un parcours dédié aux éditeurs, avec connexion OAuth des comptes marchands : si votre éditeur l'a mis en œuvre, l'activation se fait dans ses paramètres et aucun développement n'est utile. Si les volumes sont faibles, le tableau de bord GoCardless et un export mensuel peuvent aussi suffire.

Un développement se justifie quand le prélèvement conditionne une règle métier (suspendre un accès, bloquer une livraison, recalculer un échéancier), quand le logiciel est spécifique, ou quand plusieurs outils doivent connaître l'état du paiement. Pour les paiements par carte à la commande, le besoin est différent : voir l'intégration Stripe.

Ce que YMHB Web met en place pour un prélèvement GoCardless

YMHB Web traite une intégration GoCardless comme un flux financier : chaque prélèvement doit pouvoir être retrouvé, expliqué et rejoué. Le cadrage fixe qui déclenche le prélèvement, quels statuts voit le métier et ce qui se passe en cas de rejet ; le chiffrage suit. Le développement se fait dans le bac à sable avec les simulateurs, puis la mise en service suit la liste de contrôle de GoCardless : jeton de production, adresse de production, point de réception des webhooks déclaré sur le compte réel, premier appel de vérification.

• Le compte GoCardless, les jetons et les secrets de webhooks sont à votre nom.
• Le code est déposé chez vous, documenté, avec un journal de chaque événement reçu.
• Un écran des anomalies liste les prélèvements rejetés ou contestés qui attendent une décision.
• Les évolutions de l'API sont suivies dans le cadre de la maintenance, comme pour toute intégration par API.