An introduction to our API

Written by

Last editedApr 2023

The GoCardless API allows you to manage Direct Debit payments via your own website or software. When a customer signs up for your services they can give you a Direct Debit authorisation online. Your integration can then create and manage payments and subscriptions automatically - there’s no need to manually add a new customer to GoCardless. Our API provides you with full flexibility when it comes to payment creation, and we offer it to all of our merchants at no extra cost.

In this blog post we’ll guide you through the steps needed to use our API, from customer creation to taking your first payment.

Let’s look at how Direct Debit payments work and how the GoCardless API is organised. In order to charge a customer’s bank account, you will first need their authorisation to collect payments via Direct Debit. This can be via our secure online payment pages or, if you’re using GoCardless Pro, you can take complete control of the payment process by hosting the payment pages on your own website.

GoCardless

Using GoCardless the process of creating a new customer is as follows:

You direct your customers to the GoCardless payment page, allowing them to complete the authorisation to take payments from their account.
Once complete, we redirect your customers back to your website. We’ve called this the redirect flow. When the customer is returned to your website, the redirect flow will already have created a customer record on the GoCardless system. Associated with the customer record will be a customer bank account, which itself will be associated with a mandate.
You can now create payments and subscriptions against this mandate.

GoCardless Pro

If you host your own payment pages your clients will never have to leave your website to give you a Direct Debit authorisation.

You use our API to create a customer record, followed by a customer bank account which is linked to the customer.
Next you create a mandate by referencing the customer bank account.
You can now create payments and subscriptions against this mandate.

Example requests

Now that we’ve covered the basics let’s look at the actual requests to the API. In order for you to follow these steps you will need the following:

A GoCardless sandbox account, get one here
An access token to use the API, create one here

In order to send a HTTP request to our API you will first need to set the URL where you want the request sent to. The base URLs for the GoCardless API are

https://api.gocardless.com/ for live
https://api-sandbox.gocardless.com/ for sandbox

As we’re using the sandbox we’ll use https://api-sandbox.gocardless.com/ which is then followed by the endpoint you want to send a request to. You will also need to specify if you want to send a POST (sending information) or a GET (requesting information) request and you will need to set the headers. Our API requires several headers to be set:

Authorization uses the access token you’ve created in the developer settings, preceded by the word Bearer
Accept tells the API that you’re expecting data to be sent in the JSON format. This needs to be application/json.

If you’re sending data to us, for example to create a new payment, you’ll also need to specify the content type:

Content-Type specifies the format of the content sent to the API (if any). This needs to be application/json.

An example request to our customers endpoint to list all customers on an account using curl would look like this:

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"

Creating a customer using the redirect flow

To send your customer to the GoCardless payment pages you will need to create a redirect flow. This will be a POST request, and the redirect flow endpoint requires at least two parameters:

session_token This is used as an identifier allowing you to link the redirect flow to the respective customer in your integration. You could use the customer's email address or generate a random ID for this - it’s how you will identify this customer when they’re returned to your site after authorising payments
success_redirect_url This is the URL we redirect the customer to when they complete the payment pages.
description (optional) This will be shown to the customer when they’re on our payment page.

These parameters will need to be send with the request in a JSON blob, wrapped in a redirect_flows envelope:

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"
  }
}'

The response from the 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"
   }
}

The response shows the redirect_url for the newly created redirect flow. An HTTP 303 redirect (or an alternative redirect method) can be used to send your customer to the our payment pages. This should be done immediately, as the redirect link expires after 30 minutes. The customer will then see the GoCardless payment page and can enter their details to authorise a Direct Debit to be set up.

Once the form is complete, we will redirect the customer back to the redirect_uri you originally specified and append the parameter redirect_flow_id like this: http://localhost/success?redirect_flow_id=RE00005H8602K9J5C9V77KQAMHGH8FDB.

In order for the API to know that the customer has been returned safely back to your integration you will need to complete the redirect flow by sending the following request to the API. This is a mandatory step and the customer won’t be set up if this is not completed.

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"
  }
}'

Notice that the ID of the redirect flow and the required action was appended to the URL, and the session_token (as set by your integration when creating the redirect flow) was sent in the body of the request.

The response from the 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"
      }
   }
}

The customer’s details have now been saved, and GoCardless will take care of setting up an authorisation to collect payments from their bank account. You’ll use the mandate ID (provided in the links) to create payments and subscriptions, so you’ll want to store that ID in your database. You may find it useful to store the other references to your customer's resources in your database as well.

Creating a payment will be just one more call to the API, using the payments endpoint. A quick look into the developer documentation shows the three required parameters:

amount The payment amount, given in pence/cents. So to take £10.00 the value would be 1000
currency The currency of the payment you’re taking
links[mandate] The mandate that should be charged

Another helpful parameter is charge_date, which specifies when the payment leaves the customer’s bank account. If no charge_date is provided, the payment will be charged on the earliest possible date.

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"
    }
  }
}
'

The response from the 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"
      }
   }
}

You have now set up a customer and charged your first payment using the GoCardless API!

The API offers you many more options, allowing you to integrate Direct Debit functionality into your existing website or software.

If you’re using PHP, Java, Ruby or Python you can also make use of our client libraries. To get started, check out our easy "getting started" guide with copy and paste code samples.

Any API-related questions or feedback can be sent to our developer support team at api@gocardless.com.