Cet article suppose que vous avez actuellement une intégration avec notre ancienne API.
Si vous ne disposez pas d'une intégration existante ou si vous utilisez notre API actuelle, cet article ne vous concerne pas. Vous pouvez consulter la documentation relative à notre API actuelle ici.
Il pourrait vous être utile de lire la brève présentation des changements avant de consulter ce guide.
Si vous disposez d'une intégration partenaire ou si vous souhaitez en créer une, ce guide vous intéressera. Vous devriez aussi prendre contact avec nous avant de vous lancer.
Par où commencer ?
Si vous ne l'avez pas encore fait, vous devez créer un compte sandbox ici. Les comptes sandbox ne sont plus rattachés à votre compte actif. Vous devrez donc créer un compte sandbox distinct pour créer une intégration avec la nouvelle API.
Ensuite, créez un jeton d'accès. Vous devrez donner un nom à votre jeton d'accès et vous assurer de lui attribuer un accès en mode lecture-écriture. Cliquez sur « Créer un jeton d'accès » et copiez le jeton dans le presse-papiers. Sauvegardez-le à un emplacement sécurisé, en gardant en tête que vous ne pourrez plus y accéder à nouveau. Au besoin, vous pouvez désactiver votre jeton d'accès et en créer un nouveau.
Lisez en détail notre Guide de démarrage et la documentation complète à l'attention des développeurs pour vous lancer dans la création de votre nouvelle intégration. Le guide et la documentation fournissent des exemples de codes pour toutes les bibliothèques clientes actuelles (ou de requêtes HTTP si nous n'avons pas de bibliothèque qui correspond à votre pile), et vous pouvez voir la source de chaque bibliothèque via les liens fournis dans notre documentation.
Envoyer des requêtes à la nouvelle API
Si vous utilisez une de nos bibliothèque clientes, vous n'aurez pas à vous soucier de cette section. Les bibliothèques s'occupent de créer des requêtes pour vous dans le bon format.
Les URL de base pour l'API sont :
| Compte actif | https://api.gocardless.com/ |
| Compte sandbox | https://api-sandbox.gocardless.com/ |
Vous devrez utiliser le jeton d'accès que vous avez créé plus tôt, puis le fournir dans l'en-tête d'une requête d'autorisation lorsque vous envoyez des requêtes à l'API :
Authorization: Bearer ACCESS_TOKEN_HERE
Vous devrez aussi spécifier l'en-tête GoCardless-Version. La version disponible actuellement au moment de la rédaction est celle du 6 juillet 2015 :
GoCardless-Version: 2015-07-06
Toutes les requêtes et réponses sont au format JSON et encodées en UTF-8. En considérant que l'en-tête Accept est facultatif mais recommandé. L'en-tête Content-Type doit être fourni lors de l'envoi des données à l'API (à l'aide des points de terminaison POST et PUT). Vous pouvez opter pour le type MIME JSON standard (application/json), ou la variante JSON-API (application/vnd.api+json).
Webhooks
Les webhooks contiennent désormais bien plus d'informations, et peuvent être envoyés à plusieurs points de terminaison. Lorsqu'une ressource change de statut, nous enregistrons un événement, et les événements sont compilés dans des tableaux puis publiés en tant que webhooks.
Si vous souhaitez utilisez les webhooks, vous devrez ajouter un point de terminaison de webhook ici. Dans un environnement sandbox, vous pouvez utiliser une URL HTTP pour vos webhooks, mais pour une mise en service, le point de terminaison doit être sécurisé avec le protocole HTTPS. Vous en apprendrez davantage sur les webhooks ici.
Comment continuer à facturer mes clients ?
Pour créer des paiements pour vos clients, vous devrez utiliser leur identifiant de mandat. Quel que soit le type d'autorisation que vous utilisiez dans l'ancienne API, vous aurez maintenant besoin de l'identifiant du mandat pour créer des paiements.
Les identifiants de ressource que vous avez utilisés jusqu'à présent peuvent être utilisés dans l'API actuelle, mais ils seront associés à des ressources légèrement différentes. Par exemple, un identifiant de pré-autorisation dans l'ancienne API correspond à l'identifiant d'un mandat dans l'API actuelle. Les mappages sont répertoriés ci-dessous :
| Ancien identifiant | Nouvel identifiant |
| Identifiant de pré-autorisation | Identifiant du mandat |
| Identifiant de l'autorisation d'abonnement | Identifiant de l'abonnement |
| Identifiant de l'autorisation ponctuelle | Identifiant du paiement |
| Identifiant de la facture | Identifiant du paiement |
Restrictions des mandats
L'ancienne API comportait des factures uniques et des abonnements non modifiables. Les clients qui configuraient ce type de mandat de prélèvement devaient donc approuver tous les nouveaux paiements ou abonnements que vous créiez dans le cadre de leurs mandats. Nous les qualifions de « mandats restreints ».
Vous ne pouvez pas créer de mandats restreints avec l'API actuelle, mais ils existent pour offrir un moyen simple de facturer des clients dans le cadre de ces anciens types d'autorisation sans qu'ils n'aient à saisir à nouveau leurs coordonnées bancaires.
| Ancien type d'autorisation | Type de mandat |
| Pré-autorisation | Mandat non restreint |
| Autorisation ponctuelle | Mandat restreint |
| Abonnement | Mandat restreint |
Avec un mandat non restreint, vous pouvez créer des paiements et des abonnements pour le client sans autre autorisation. Dans un souci de nous conformer aux règles du programme de prélèvement, nous lui enverrons cependant un e-mail pour l'avertir que vous avez créé un mandat ou un abonnement.
Avec un mandat restreint, nous demanderons l'autorisation du client par e-mail avant que tout paiement ne soit prélevé de son compte. Le client devra simplement cliquer sur un lien dans l'e-mail pour l'autoriser ; il n'aura pas besoin de remplir les pages de paiements ou de fournir à nouveau ses coordonnées.
Les mandats de pré-autorisation ne sont pas restreints, mais ils seront toujours soumis avec le montant et l'intervalle maximaux que vous avez spécifiés initialement.
Comment configurer des paiements ponctuels/des abonnements/des pré-autorisations dans la nouvelle API ?
Au lieu d'avoir à créer des liens différents pour chaque type d'autorisation, vous aurez juste à mettre en œuvre le concept de flux de redirection.
D'abord, vous devrez créer un flux de redirection pour votre client et le redirigerer vers l'URL fournie, par exemple https://pay.gocardless.com/flux/RE123.
Le client remplira les nouvelles pages de paiements GoCardless améliorées, en renseignant son nom, son adresse e-mail, et ses coordonnées bancaires.
Après avoir soumis le formulaire, nous stockerons de façon sécurisée ses informations et redirigerons le client vers votre URL de redirection, que vous aurez spécifié lors de la création du flux de redirection.
Vous devrez ensuite « terminer » l'exécution du flux de redirection en envoyant une seule requête à l'API, laquelle génèrera la création du client, de son compte bancaire et du mandat. Cette procédure est similaire à l'étape « confirmer la ressource » dans l'ancienne API.
Le nouveau mandat généré vous permet de créer des paiements et des abonnements pour le client. Vous devriez stocker l'identifiant du mandat grâce auquel vous pourrez créer des paiements futurs et identifier les webhooks entrants liés au statut du mandat.
Comment puis-je effectuer la transition vers la nouvelle API ?
Une fois que vous êtes satisfait de votre intégration sandbox avec la nouvelle API, nous pouvons vous aider à effectuer la transition en quelques étapes :
- Nous transférons votre compte dans notre nouveau tableau de bord. Vous perdrez l'accès à votre ancien tableau de bord de développement, mais votre ancienne intégration continuera de fonctionner. Toutes les données existantes seront disponibles dans le nouveau tableau de bord.
- Maintenant que votre compte se trouve sur le nouveau tableau de bord, vous serez en mesure de créer un jeton d'accès et de spécifier un point de terminaison de webhook pour votre compte actif.
- De votre côté, vous pouvez progressivement cesser d'utiliser l'ancienne API et commencer à utiliser la nouvelle interface quand bon vous semble.
- Une fois que vous satisfait et que tout fonctionne correctement, nous pouvons désactiver vos anciens jeton d'accès et point de terminaison de webhook.
Points à considérer :
- Tout l'historique de votre compte sera toujours disponible et vos clients n'auront pas besoin de fournir de nouvelles autorisations.
- L'ancienne intégration ne pourra pas accéder aux ressources que vous créez via le nouveau tableau de bord ou l'API, mais toutes les ressources créées dans votre ancienne intégration seront accessibles par la nouvelle API.
- Vous devrez nous contacter pour que nous puissions mettre à niveau votre compte et désactiver votre ancienne intégration (ou si vous avez des questions).
- Si vous disposez d'une ancienne intégration de partenaires, vous devez nous contacter pour vous assurer que le processus de transition est approprié pour votre intégration.