Intégration API GoCardless
Nous développons votre connecteur GoCardless
Nous développons le connecteur GoCardless pour signer des mandats SEPA, prélever à l'échéance réelle et suivre rejets et reversements.
- Équipe produit senior
- intégrations de paiement en production
- du cadrage au monitoring
À quoi sert l'API GoCardless et pourquoi encaisser par prélèvement bancaire ?
GoCardless est un opérateur de prélèvement SEPA et ACH utilisé pour les paiements récurrents : abonnements, factures mensuelles, règlements d'échéanciers. L'API permet à votre application de créer un mandat de prélèvement en ligne, de programmer des échéances et d'être notifié de chaque règlement ou échec. On l'intègre quand la carte bancaire n'est pas le bon moyen de paiement : montants élevés, clientèle B2B, abonnements longue durée, et qu'on veut encaisser sans que le client renouvelle sa carte ou saisisse ses coordonnées à chaque fois.
Ce que nos clients construisent sur l'API GoCardless
Abonnement B2B en prélèvement SEPA
Mandat signé en parcours hébergé, échéancier calé sur 1 jour ouvré interbancaire avant l'échéance, plus de carte à relancer.
Paiement en plusieurs fois
Formation, travaux, matériel : chaque échéance est un paiement suivi, avec relance branchée sur details.cause, pas sur un code banque.
Cotisations et adhésions
Appel annuel, notification préalable automatique, gestion des mandats révoqués. Le PDF signé et le tableur d'IBAN disparaissent.
Reversement d'apporteurs
Paiements sortants créés puis approuvés à deux niveaux dans le back-office. Une référence métier empêche le double virement.
Ce que ça change dans votre recouvrement
La technique au service d'un résultat mesurable : moins d'impayés carte, un mandat vivant, une trésorerie lisible.
Plus de carte qui expire
Le prélèvement SEPA tient tant que le mandat tient. Le taux d'échec devient un problème de solde, pas de cycle de vie de carte.
Un échéancier que la banque peut honorer
Soumission 1 jour ouvré interbancaire avant l'échéance, notification 2 jours ouvrés avant. Vous arrêtez de promettre un débit immédiat.
Le rejet a une cause lisible
details.cause est normalisé, contrairement au code banque. La relance dit la vraie raison, pas un libellé technique.
La trésorerie, pas les factures émises
confirmed, paid_out, failed, charged_back : le tableau de bord montre ce qui est encaissé, pas ce qui a été facturé.
Comment nous livrons votre connecteur GoCardless
Cadrage
Billing Requests ou pages approuvées, schéma SEPA, calendrier interbancaire, paiements sortants. On tranche la contrainte de production d'abord.
Développement
Connecteur typé, GoCardless-Version sur chaque appel, Idempotency-Key métier, webhook HMAC avec réponse 498.
Recette
Mandat, rejet, 409 traité comme un succès, événement received out of order, IBAN invalide bloqué avant création.
Monitoring
Alertes sur événement non traité, journal des mandats, tableau de bord de santé. Vous savez qu'un flux est cassé avant vos clients.
Ce que permet l'API GoCardless
- Billing Requests et parcours hébergé
- Cycle pending, ready_to_fulfil, fulfilled, cancelled. GoCardless recommande les Billing Request Flows pour la conversion et la conformité.
- Prélèvements et abonnements SEPA
- Paiements, abonnements adossés à un mandat. Les subscription_request des Billing Requests ne couvrent pas SEPA (ACH et PAD seulement).
- Contrôle d'IBAN
- bank_details_lookups vérifie clé et atteignabilité avant de créer un mandat. Un IBAN faux coûte un cycle bancaire entier.
- Paiements sortants
- Création puis approbation. Les POST sortants partagent 300 requêtes par minute, soit environ 150 paiements (créer puis approuver).
Le vocabulaire de l'API GoCardless
- GoCardless-Version
- En-tête obligatoire, une seule version publiée : 2015-07-06. Sans lui, missing_version_header. Les ajouts arrivent sans changer la date.
- Idempotency-Key
- Jusqu'à 128 caractères, honorée au moins 30 jours. Un conflit renvoie 409 idempotent_creation_conflict avec links.conflicting_resource_id : c'est un succès.
- details.cause
- Clé normalisée, indépendante du schéma bancaire. details.reason_code change d'une banque à l'autre : une machine à états branchée dessus se brise en changeant de pays.
- meta.webhook_id
- Identifie la tentative de livraison, pas l'événement. La déduplication se fait sur event.id. Dédupliquer ici ne se voit qu'en incident.
- 498 Token Invalid
- Réponse attendue si la signature est invalide : GoCardless journalise et ne retente pas. Un 200 ferait croire que la livraison a réussi.
- Billing Request
- Objet moderne (pending, ready_to_fulfil, fulfilled, cancelled). En production sans pages approuvées, c'est le seul chemin légal pour créer un mandat.
Les contraintes réelles de l'API GoCardless
Livraison hors ordre, au moins une fois
payment.confirmed peut arriver avant payment.created. GoCardless ne garantit pas exactly-once. On relit la ressource via l'API à chaque webhook, on ne déduit rien de la séquence.
La prod n'est pas le bac à sable
Sans approbation de vos pages par la banque de parrainage, création de client, de compte bancaire et de mandat sont interdites hors Billing Requests. Un prototype bac à sable peut être illégal tel quel.
Trois plafonds de débit, pas un
1 000 requêtes par minute en standard, 60 sur GET /balances, 300 POST partagés sur les paiements sortants (environ 150 paiements). Le 429 arrive trop tard : on lit ratelimit-*.
Le 409 est une bonne nouvelle
idempotent_creation_conflict pointe vers la ressource déjà créée. Le traiter comme une erreur relance un second prélèvement ou bloque la file. Les SDK qui génèrent la clé tout seuls sont un piège.
Billing Requests ou endpoints directs ?
Deux façons de créer un mandat. En production, le choix n'est souvent pas un choix.
| Critère | Billing RequestsParcours hébergé | Endpoints directsClient, compte, mandat |
|---|---|---|
| Production sans pages approuvées | Autorisé | Interdit |
| Bank Authorisations | Uniquement via les interfaces hébergées | Non créables hors parcours GoCardless |
| Conversion et conformité | Parcours optimisé par GoCardless | À faire valider par la banque de parrainage |
| Abonnement SEPA | Objet Subscription classique ensuite | Idem, une fois le mandat créé |
| Bac à sable | Accessible | Accessible, trompeur pour la prod |
| Flux JavaScript | Hors de ce chemin | Restreint en production |
| Le bon cas | Presque tous les projets français | Pages déjà approuvées, partenaire whitelabel |
Nous posons cette restriction au premier rendez-vous. Un prototype construit sur les endpoints directs est souvent à jeter avant la mise en production.
Ce que nous mesurons sur une intégration GoCardless
Les autres API de paiement
Si le prélèvement SEPA n'est pas le bon choix, ces options se discutent au cadrage.
GoCardlessNous développons votre connecteur GoCardlessCette page
StripeCarte et Billing, quand l'acheteur n'a pas d'IBAN ou que le cycle de vie carte vous convient.
PayPalUn compte que l'acheteur possède déjà, plutôt qu'un mandat de prélèvement.
SumUpL'encaissement en présence, quand la vente se conclut sur un terminal.
MollieNous développons votre connecteur MollieOn combine GoCardless avec
La stack qui entoure GoCardless sur nos projets.
Intégration GoCardless : vos questions
Trois étapes. D'abord un jeton Bearer et l'en-tête GoCardless-Version : 2015-07-06 sur chaque requête. Ensuite Billing Request plus parcours hébergé pour le mandat, puis paiements ou abonnements, avec une Idempotency-Key dérivée de la facture, pas celle générée par le SDK. Enfin les webhooks : HMAC-SHA256 sur le corps brut, 498 si la signature est invalide, 204 sur un type inconnu, déduplication sur event.id, relecture de la ressource parce que les événements n'arrivent ni une seule fois ni dans l'ordre. La partie sensible n'est pas l'appel, c'est la contrainte de production et le calendrier SEPA.
Cela dépend du parcours mandat et du recouvrement. Un abonnement B2B avec parcours hébergé et échéancier SEPA est plus court qu'un outil avec paiements sortants, relances par cause et tableau de trésorerie. Un premier flux utile se livre en deux à trois semaines. Une chaîne complète demande plutôt six à huit semaines. La restriction de production (Billing Requests sans pages approuvées) se tranche au cadrage, pas en recette. Nous donnons une estimation ferme avant de commencer.
Billing Requests plus Billing Request Flows sont le parcours hébergé, obligatoire en production tant que vos pages de paiement n'ont pas été approuvées par la banque de parrainage. Les endpoints de création de client, de compte bancaire et de mandat, et tout le flux JavaScript, sont alors interdits. Le bac à sable les expose tous, ce qui trompe. Les Bank Authorisations ne se créent que depuis les interfaces hébergées. Pour un projet français standard, on part des Billing Requests. Les endpoints directs se discutent seulement si vos pages sont déjà conformes.
Vérifier Webhook-Signature en HMAC-SHA256 hexadécimal sur le corps brut, répondre 2xx après persistance, 498 sur signature invalide. Dédupliquer sur event.id, jamais sur meta.webhook_id (c'est la tentative). Relire le paiement via l'API, parce qu'un confirmed peut précéder le created. L'Idempotency-Key métier (prelevement:{facture}:{echeance}) plus le traitement du 409 comme un succès évitent le second prélèvement après un timeout. Le handler reste sous 10 secondes : vérifier, enfiler, répondre. Le métier se fait en tâche de fond.
Oui. Nous poussons chaque paiement confirmed ou paid_out avec la référence de facture vers Pennylane ou votre outil, et les rejets (failed, charged_back) alimentent la relance. Un contrôle de cohérence périodique signale l'écart entre prélèvements et écritures, sans correction silencieuse. Le calendrier SEPA (soumission 1 jour ouvré interbancaire avant, notification 2 jours ouvrés avant) se reflète dans l'échéancier affiché : on ne promet pas un débit le jour même que la banque ne peut pas honorer.
Un projet d'intégration GoCardless ?
Parlons-en. 30 minutes pour cadrer mandats et prélèvements, vérifier ce que l'API permet vraiment et vous dire franchement ce qui est faisable.
Parler de mon projet GoCardless