GoCardless Pro Ruby Client
Latest commit 1b09631 Feb 21, 2017 Crankshaft Robot Crankshaft[BU000003H0JKG8] Client - Ruby @ 2017-02-21 10:51:26 +0000
0729374 Jacob Pargin <jacobpgn@users.noreply.github.com>
Merge pull request #47 from gocardless/jacob/remove-overrides

Remove config overrides from template


18518eb Jacob Pargin <jacob@gocardless.com>
Remove config overrides from template

Failed to load latest commit information.
spec Crankshaft[BU000003GFGB12] Client - Ruby @ 2017-02-20 15:13:56 +0000 Feb 20, 2017
circle.yml Crankshaft Build #BU000000N964QM @ 2015-04-20 20:09:42 +0000 Apr 20, 2015
demo.rb Crankshaft Build #BU0000014A2SEV @ 2015-06-24 14:22:00 +0000 Jun 24, 2015
gocardless_pro.gemspec Crankshaft[BU000002C2ANN7] Client - Ruby @ 2015-12-15 15:25:51 +0000 Dec 15, 2015


Ruby Client for the GoCardless API

A Ruby client for the GoCardless API. For full details of the GoCardless API, see the API docs.

Gem Version Build Status

Usage Examples

This README will use customers throughout but each of the resources in the API is available in this library.


Add this line to your application's Gemfile:

gem 'gocardless_pro'

And then load it into your application:

require 'gocardless_pro'

Initialising the client

The client is initialised with an Access Token. You can also pass in environment as :sandbox to make requests to the sandbox environment rather than production.

@client = GoCardlessPro::Client.new(
  access_token: ENV["GOCARDLESS_TOKEN"]

GET requests

You can get details about one or many resources in the API by calling the #get, #list and #all methods.

Getting a single resource

To request a single resource, use the #get method:


A call to get returns an instance of the resource:

p @client.customers.get(customer_id).given_name

Getting a list of resources

To get a list of resources, use the #list method:


A call to list returns an instance of GoCardlessPro::ListResponse. You can call records on this to iterate through results:

@client.customers.list.records.each do |customer|
  p customer.given_name

If you need to pass any options, the last (or in the absence of URL params, the only) argument is an options hash. This is used to pass query parameters for GET requests:

@client.customers.list(params: { limit: 400 })

Getting all resources

If you want to get all of the records for a given resource type, you can use the #all method to get a lazily paginated list. #all will deal with making extra API requests to paginate through all the data for you:

@client.customers.all.each do |customer|
  p customer.given_name

Raw response details

In addition to providing details of the requested resource(s), all GET requests give you access the following properties of the response:

  • status
  • headers
  • body

POST/PUT Requests

For POST and PUT requests you need to pass in the body in under the params key:

  params: {
    first_name: "Pete",
    last_name: "Hamilton",

If any parameters are required they come first:

@client.customers.update(customer_id, {...})

Custom headers

Custom headers can be provided for a POST request under the headers key.

The most common use of a custom header would be to set an idempotency key when making a request:

  params: {
    first_name: "Pete",
    last_name: "Hamilton",
  headers: {
    "Idempotency-Key": "1f9630a9-0487-418d-bd37-8b77793c9985"

Handling failures

When the API returns an error, the client will raise a corresponding one. There are four classes of error which could be thrown, allof which subclass GoCardlessPro::Error:

  • GoCardlessPro::GoCardlessError
  • GoCardlessPro::InvalidApiUsageError
  • GoCardlessPro::InvalidStateError
  • GoCardlessPro::ValidationError

These errors are fully documented in the API documentation.

All errors have the following methods to facilitate access to information in the API response:

  • #documentation_url
  • #message
  • #type
  • #code
  • #request_id
  • #errors

Using the OAuth API

The API includes OAuth functionality, which allows you to work with other users' GoCardless accounts. Once a user approves you, you can use the GoCardless API on their behalf and receive their webhooks.

OAuth simply provides a means by which you obtain an access token - once you have this access token, you can use this gem as usual.

We recommend using the oauth2 gem to handle the authorisation process and gain a token. For an example of this in action, see our open-source OAuth demo app.

Supporting Ruby < 2.0.0

The client only supports Ruby >= 2.0.0 out of the box due to our use of Enumerable::Lazy for lazy loading of paginated API resources.

If you wish to use this gem with a previous ruby version, you should be able to do so with the backports gem:

  1. Add backports to your Gemfile gem 'backports'
  2. Require lazy enumerables require 'backports/2.0.0/enumerable/lazy.rb'


This client is auto-generated from Crank, a toolchain that we hope to open source soon. For now, issues should be reported on this repository. Please do not modify the source code yourself, your changes will be overriden!