To make it quick and easy for you to build your GoCardless integration, we maintain libraries in Java, Python, Ruby, PHP, and .NET to talk to our API in those languages without writing lots of boilerplate code.

Setting up your client library

Let’s install the API library using a package manager (you can also, if you prefer, download the source yourself from the links above):

# We strongly recommend using Composer, but if you'd prefer to
# install the PHP library manually, see the instructions at
# https://github.com/gocardless/gocardless-pro-php#manual-installation
composer require gocardless/gocardless-pro "~1.1"
pip install gocardless_pro
echo "gem 'gocardless_pro'" >> Gemfile
bundle install
# Add the following to <dependencies> in your pom.xml
<dependency>
    <groupId>com.gocardless</groupId>
    <artifactId>gocardless-pro</artifactId>
    <version>3.0.0</version>
</dependency>
# Install our Nuget package:
install-package GoCardless
Our API libraries have pro in their names, but don’t worry: if you’re starting a new integration, these are the right libraries for you, whichever GoCardless package you’re using.

Now we can import the library into our code so that it’s ready to use:

require 'vendor/autoload.php';
import gocardless_pro
# In a Rails app, this will happen automatically
require 'gocardless_pro'
import com.gocardless.GoCardlessClient;
using GoCardless;
Of course, you can also use our RESTful API without a library by building the HTTP requests yourself - see our API reference to get started.

Creating an access token

To start using the API, you’ll need an access token.

First, sign up for an account in our sandbox: the sandbox is our dedicated testing environment where you can build and test your integration without touching real money.

Next, create an access token. Head to https://manage-sandbox.gocardless.com/developers/access-tokens/create, then give your access token a name and make sure you give it read-write access. Click “Create access token”, and copy the token to your clipboard.

Your very first API request

You’re now ready to initialise the client:

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    // We recommend storing your access token in an
    // environment variable for security, but you could
    // include it as a string directly in your code
    'access_token' => getenv('GC_ACCESS_TOKEN'),
    // Change me to LIVE when you're ready to go live
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);
import os
import gocardless_pro

client = gocardless_pro.Client(
    # We recommend storing your access token in an 
    # environment variable for security, but you could
    # include it as a string directly in your code.
    access_token=os.environ['GC_ACCESS_TOKEN'], 
    # Change this to 'live' when you are ready to go live.
    environment='sandbox'
)
require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  # We recommend storing your access token in an
  # environment variable for security, but you could
  # include it as a string directly in your code
  access_token: ENV['GC_ACCESS_TOKEN'],
  # Remove the following line when you're ready to go live
  environment: :sandbox
)
package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Customer;

import java.util.List;
import java.util.Arrays;

public class GCIntegration {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            // We recommend storing your access token in an
            // environment variable for security, but you could
            // include it as a string directly in your code
            .newBuilder(System.getenv("GC_ACCESS_TOKEN"))
            // Change me to LIVE when you're ready to go live
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();
    }
}
GoCardlessClient client = GoCardlessClient.Create(
    // We recommend storing your access token in an
    // configuration setting for security, but you could
    // include it as a string directly in your code
    ConfigurationManager.AppSettings["GoCardlessAccessToken"],
    // Change me to LIVE when you're ready to go live
    GoCardlessClient.Environment.SANDBOX
);

Now, let’s check that the client is working by making our first request to the API: listing our customers (there won’t be any at the moment). Just run the following:

$customers = $client->customers()->list()->records;
print_r($customers);
customers = client.customers.list().records
print(customers)
print([customer.email for customer in customers])
# `pp` is Ruby's built-in pretty printing functionality
require 'pp'

pp client.customers.list.records
List<Customer> customers = client.customers().list().execute().getItems();
System.out.println(Arrays.toString(customers.toArray()));
var listResponse = await client.Customers.ListAsync();
var customers = listResponse.Customers;
Console.WriteLine("Customers: " + string.Join(", ", customers.Select(c => c.Id)));

Run that code and you should get an empty array, as you haven’t added any customers yet - but the fact that you got a response back shows that you’re authenticated and ready to go.

Array
(
)
[]
[]
[]
[]
Customers:

Next, let’s add our first customer.