Introduction à notre API

L’API de GoCardless vous permet de gérer les paiements par prélèvement automatique via votre site ou votre logiciel. Avec l’API, lorsqu’un client souscrit à vos services, il peut vous donner une autorisation de prélèvement automatique en ligne. À partir de là, votre intégration peut ensuite automatiquement créer et gérer vos paiements et abonnements. Vous n’avez pas besoin d’ajouter un nouveau client manuellement à GoCardless. Avec notre API, vous bénéficiez d’une flexibilité totale en matière de création de paiement (et ça, c’est gratuit pour nos clients).

Cet article vous guidera tout au long des différentes étapes nécessaires pour utiliser notre API, de la création d’un client à l’encaissement de votre premier paiement.

Jetons un œil au fonctionnement des paiements par prélèvement automatique et à l’organisation de l’API de GoCardless. Pour commencer, afin d’imputer un paiement sur le compte d’un client, vous avez besoin de leur autorisation d’encaisser des paiements via prélèvement automatique. Vous pouvez soit obtenir cette autorisation par le biais de nos pages de paiement, soit contrôler totalement le processus de paiement en hébergeant les pages de paiement sur votre site Internet à l’aide de GoCardless Pro.

GoCardless Standard et Plus

Suivez les étapes ci-dessous pour créer un nouveau client dans GoCardless Standard et GoCardless Plus :

1. Premièrement, vous orientez vos clients vers la page de paiement de GoCardless. Là, ils peuvent compléter l’autorisation d’encaisser des paiements sur leur compte.
2. Une fois la page complétée, nous les redirigeons vers votre site. Nous appelons cette action « le flux de redirection » (ou « Redirect Flow »). Au moment où le client est redirigé vers votre site, le flux de redirection a déjà créé un compte client sur le système GoCardless. À ce compte client sera associé un compte bancaire client, qui sera, à son tour, associé à un mandat de prélèvement.
3. Et voilà ! Vous pouvez désormais créer des paiements et des abonnements sur ce mandat.

GoCardless Pro

Si vous hébergez vos propres pages de paiement, vos clients n’auront jamais besoin de quitter votre site pour vous donner une autorisation de prélèvement automatique.

1. Créez un compte client, suivi d’un compte bancaire client directement relié au client via notre API.
2. Puis, créez un mandat avec les informations du compte bancaire du client.
3. C’est fini ! Vous pouvez désormais créer des paiements et des abonnements sur ce mandat.

Exemples de requêtes

Maintenant que nous avons couvert les bases, penchons-nous sur les requêtes que vous allez appeler dans l’API. Pour les étapes suivantes, vous aurez besoin des éléments ci-dessous :

• Un compte sandbox GoCardless, créez-en un ici.
• Un access token pour utiliser l’API, créez-en un ici.

Afin d’envoyer une requête HTTP à notre API, vous devez tout d’abord décider de l’URL sur laquelle vous souhaitez envoyer la requête. Les URLs de base de l’API de GoCardless sont les suivantes :

• https://api.gocardless.com/ pour l’environnement live
• https://api-sandbox.gocardless.com/ pour l’environnement sandbox

Puisque nous utilisons l’environnement sandbox (test), nous utiliserons l’adresse https://api-sandbox.gocardless.com/ suivie de l’endpoint sur lequel vous souhaitez envoyer une requête. Vous devrez aussi préciser si vous souhaitez envoyer une requête POST (envoi de données) ou GET (requête de données) puis les en-têtes (headers). Notre API requiert la mise en place de plusieurs en-têtes dont :

• « Authorization », utilise l’access token que vous avez créé dans les paramètres développeur, précédé du mot « Bearer ».
• « Accept », dit à l’API que vous souhaitez envoyer les données au format JSON. Le type sera application/json.

Si vous nous envoyez des données, pour créer un nouveau paiement par exemple, vous aurez aussi besoin de préciser le type de contenu :

• « Content-Type », précise le format du contenu envoyé à l’API (si nécessaire). Le type sera application/json.

Voici à quoi ressemblerait une requête des endpoints de nos clients pour obtenir une liste de tous les clients sur le compte avec cURL :

curl https://api-sandbox.gocardless.com/customers \
-H "Authorization: Bearer ZQfaZRchaiCIjRhSuoFr6hGrcrAEsNPWI7pa4AaO" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "GoCardless-Version: 2015-07-06"

Création d’un client à l’aide du flux de redirection

Pour envoyer un client vers les pages de paiement de GoCardless, vous devez créer un flux de redirection. Pour cela, vous devez envoyer une requête POST. L’endpoint du flux de redirection requiert au moins deux paramètres :

• session_token, utilisé comme un identifiant vous permettant de relier le flux de redirection au client dans votre intégration. Cet identifiant peut être l’adresse e-mail du client ou un identifiant aléatoire. C’est grâce à cet identifiant que vous reconnaîtrez ce client lorsqu’il revient sur votre site une fois les paiements autorisés.
• success_redirect_url, l’URL vers laquelle nous redirigeons le client lorsqu’il remplit les pages de paiement.
• description (facultatif), présenté au client lorsqu’il se trouve sur notre page de paiement.

Ces paramètres doivent être envoyés avec la requête dans un Blob JSON, dans une enveloppe redirect_flows comme suit :

curl https://api-sandbox.gocardless.com/redirect_flows \
-H "Authorization: Bearer ZQfaZRchaiCIjRhSuoFr6hGrcrAEsNPWI7pa4AaO" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "GoCardless-Version: 2015-07-06" \
-d '{
  "redirect_flows": {
    "description": "Magazine subscription",
    "session_token": "session_ca853718-99ea-4cfd-86fd-c533ef1d5a3b",
    "success_redirect_url": "http://localhost/success"
  }
}'

La réponse de l’API:

{
   "redirect_flows": {
      "id": "RE00005H8602K9J5C9V77KQAMHGH8FDB",
      "description": "Magazine subscription",
      "session_token": "session_ca853718-99ea-4cfd-86fd-c533ef1d5a3b",
      "scheme": null,
      "success_redirect_url": "http://localhost/success",
      "created_at": "2016-06-29T13:28:10.282Z",
      "links": {
         "creditor": "CR000035V20049"
      },
      "redirect_url": "https://pay-sandbox.gocardless.com/flow/RE00005H8602K9J5C9V77KQAMHGH8FDB"
   }
}

La réponse montre le redirect_url pour le flux de redirection qui vient d’être créé. Vous pouvez utiliser une redirection HTTP 303 (ou une autre méthode de redirection) pour rediriger votre client vers nos pages de paiement. Nous vous conseillons de le faire rapidement, le lien de redirection arrivant à expiration au bout de 30 minutes. Le client arrivera ensuite sur la page de paiement de GoCardless et pourra entrer ses coordonnées afin d’autoriser le paramétrage du prélèvement automatique.

Une fois le formulaire complété, nous redirigerons le client sur le redirect_url que vous avez précisé au début de la requête et ajouterons le paramètre redirect_flow_id comme suit : http://localhost/success?redirect_flow_id=RE00005H8602K9J5C9V77KQAMHGH8FDB.

Afin que l’API sache que le client est de retour dans intégration, vous devez compléter le flux de redirection en envoyant la requête suivante à l’API. Ceci est une étape obligatoire et le client ne pourra pas être créé si elle n’est pas complète.

curl https://api-sandbox.gocardless.com/redirect_flows/RE00005QAMHGH8FDB/actions/complete \
-H "Authorization: Bearer ZQfaZRchaiCIjRhSuoFr6hGrcrAEsNPWI7pa4AaO" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "GoCardless-Version: 2015-07-06" \
-d '{
  "data": {
    "session_token": "session_ca853718-99ea-4cfd-86fd-c533ef1d5a3b"
  }
}'

Vous remarquerez que l’identifiant du flux de redirection et l’action requise ont été ajoutés à l’URL et que le session_token (tel que paramétré lors de la création du flux de redirection) a été envoyé dans le corps de la requête.

La réponse de l’API :

{
   "redirect_flows": {
      "id": "RE00005H8602K9J5C9V77KQAMHGH8FDB",
      "description": "Magazine subscription",
      "session_token": "session_ca853718-99ea-4cfd-86fd-c533ef1d5a3b",
      "scheme": null,
      "success_redirect_url": "http://localhost/success",
      "created_at": "2016-06-29T13:49:00.077Z",
      "links": {
         "creditor": "CR000035V20049",
         "mandate": "MD0000TWJWRFHG",
         "customer": "CU0000X30K4B9N",
         "customer_bank_account": "BA0000TCWMHXH3"
      }
   }
}

Ça y est, les coordonnées du client sont enregistrées. GoCardless va se charger de paramétrer l’autorisation pour encaisser des paiements depuis leur compte bancaire. Utilisez l’identifiant du mandat (fourni dans les liens) pour créer des paiements et des abonnements. Conservez cet identifiant ainsi que les autres références des ressources de votre client dans votre base de données.

La création d’un paiement créera un nouvel appel sur l’API, grâce à paymentsendpoint. Un coup d’œil rapide à notre documentation développeur vous montrera les trois paramètres requis ci-dessous :

• amount, montant du paiement, donné en centimes. Pour encaisser 10,00 €, la valeur sera donc 1000.
• currency, devise dans laquelle vous encaissez le paiement.
• links[mandate], mandat qui doit être imputé.

charge_date est un autre paramètre utile qui précise à quelle date le paiement doit quitter le compte bancaire du client. Si aucune charge_date n’est fournie, le paiement sera imputé le plus rapidement possible.

curl https://api-sandbox.gocardless.com/payments \
-H "Authorization: Bearer ZQfaZRchaiCIjRhSuoFr6hGrcrAEsNPWI7pa4AaO" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "GoCardless-Version: 2015-07-06" \
-d '{
  "payments": {
    "amount": 1000,
    "currency": "GBP",
    "links": {
      "mandate": "MD0000TWJWRFHG"
    }
  }
}
'

La réponse de l’API :

{
   "payments": {
      "id": "PM0001G6V7BSN4",
      "created_at": "2016-07-01T09:27:52.352Z",
      "charge_date": "2016-07-06",
      "amount": 1000,
      "description": null,
      "currency": "GBP",
      "status": "pending_submission",
      "amount_refunded": 0,
      "reference": null,
      "metadata":{},
      "links": {
         "mandate": "MD0000TWJWRFHG",
         "creditor": "CR000035V20049"
      }
   }
}

Ça y est ! Vous venez de paramétrer un client et avez encaissé votre premier paiement à l’aide de l’API de GoCardless !

L’API propose beaucoup d’autres options et vous permet d’intégrer la fonctionnalité de prélèvement automatique dans votre site Internet ou logiciel existant.

Si vous utilisez les langages PHP, Java, Ruby ou Python, vous pouvez aussi utiliser nos librairies client. Pour commencer, lisez notre guide « Commencez maintenant » contenant des exemples de code que vous pouvez copier-coller.

Pour toute question ou commentaire sur l’API, envoyez un e-mail à api@gocardless.com.