Set up

This guide covers all the essential steps to prepare for your integration with the GoCardless API.

What you’ll learn

Understand the GoCardless API basics
Set up a sandbox account and create an access token
Prepare your development environment to make API requests

The GoCardless API makes it easy to collect bank payments from your customers' bank accounts. With one integration, you can collect payments from the UK, Eurozone, Sweden, Denmark, Australia, New Zealand, Canada, and the United States. Our API has two main functions:

Collect payments

Collect recurring payments via Direct Debit or take instant, one-off payments through open banking schemes, like the UK's Faster Payments service.

Send payments

Send secure payouts to customers, suppliers, or third parties from a funded payment account. Payments use instant payment rails where available and include security checks like Confirmation of Payee.

We also have a range of developer tools to help you with your integration, the rest of this guide will however focus on using one of our client libraries to make requests.

Step-by-step guide

GoCardless has two environments: A free Sandbox for testing and Live for processing real payments. Each environment is completely separate, with its own account, dashboard, access tokens, and API URLs.

For this guide, we will only use the Sandbox environment.

Sandbox environment

A dedicated testing environment to build your integration without moving real money.

Dashboard URL: manage-sandbox.gocardless.com
API URL: https://api-sandbox.gocardless.com/

Live environment

The production environment for taking real payments from customers after your integration is complete!

Dashboard URL: manage.gocardless.com
API URL: https://api.gocardless.com/

To start, you will need a read-write access token from your Sandbox account.

Create one here if you haven't already.

Create an access token

In your Sandbox dashboard, go to the Developers tab and select Create access token. Give your token a name and choose Read-Write access.

Copy your token

Click the ‘Copy’ button and copy the token to a safe place. For security, you will not be able to view it again.

Now it's time to set up your application to communicate with the GoCardless API. You have two main options: using one of our official client libraries for a streamlined experience, or making direct HTTP requests.

Option 1: Use a GoCardless client library Recommended

Our client libraries make it easier to integrate by handling boilerplate code, authentication, and request signing for you. We recommend using a library if one is available for your language. We maintain official libraries for:

Below are the steps to install and initialise the client. Select your programming language to see the relevant instructions.

Install the library

You can install the library using a package manager. If you are using Go modules, the toolchain will fetch it automatically when you import it.

Initialise the client

Once the library is part of your project, you can initialise the client in your code. You will need the access token you created in the previous step. Remember to use the Sandbox endpoint for testing.

import os
import gocardless_pro

client = gocardless_pro.Client(
    # We recommend storing your access token in an
    # environment variable for security
    access_token=os.environ['GC_ACCESS_TOKEN'],
    # Change this to 'live' when you are ready to go live.
    environment='sandbox'
)

Option 2: Use direct HTTP requests

If you prefer, you can interact with our REST API directly. You will need to build the HTTP requests yourself, making sure to include your access token in the Authorization header with the Bearer scheme.

Export access token

In the next section of this guide, we will also provide cURL examples for each API request that you can adapt, if you wish to use them, now is a good time to set the token in your environment.