Overview

Introduction

Start collecting payments with the GoCardless API today. No lengthy sign-up process. No fuss.

  1. To start using our API, you'll need to sign up for a merchant account
  2. Enable developer mode within your dashboard under the 'More...' tab
  3. Start using one of our API libraries for your chosen programming language

Note: This is the documentation for our Basic API. If you are already familar with Direct Debit and take over 500 payments a month you might also want to check out our Pro API.

GoCardless anatomy

Payment resources

There are three resources that can be set up through GoCardless to take payments: bill, subscription, and pre-authorisation. Please note that subscriptions and pre-authorisations will create bills for each payment under them.

Bill

A bill resource represents a payment from a customer's bank account. A bill can exist on its own, or it can be created under a subscription or a pre-authorisation. A bill cannot be altered after its creation, however it can be cancelled.

Subscription

A subscription is a resource that will automatically create a bill after a defined interval (eg. monthly). The customer will not need to take any further steps to authorise each recurring payment. A subscription cannot be altered after its creation.

Pre-authorization

A pre-authorisation is a resource that enables you to take variable payments. The customer will not need to take any further steps to authorise each variable payment.

Other resources

Other resources in GoCardless that are not directly related to taking payments.

Payout

A payout is a payment made from GoCardless to a merchant's bank account that consists of payments collected by the merchant, minus fees taken by GoCardless.

Merchant

The merchant represents the business or organisation collecting payments from customers. A merchant can collect payments from users in three ways: one-off bills, subscriptions or pre-authorizations.

User

Represents a user that has a bill, subscription or pre-authorization with the merchant.

Webhook

A webhook is a HTTP POST request sent from GoCardless to notify your server of changes to a resource (for example, when a bill becomes paid or a subscription is cancelled).

For example, if a customer cancels their subscription to your membership system, your website could respond by revoking the customer's access a membership only section.

Payment resource creation

The following state diagrams show the entire state of a resource from setup to payout for the three types of payments you can take with GoCardless: one-off bills, subscriptions and pre-authorizations.

One-off bills

User payment auth flow

Subscriptions

User payment auth flow

Pre-authorizations

User payment auth flow

Example payment flow for customers

Your customers will only have to interact with GoCardless at the time of authorising payments. No interaction from customers is needed for future payments to be collected. The following screencaps illustrate a typical payment flow from a customer's point of views.

Step one – customer is directed to GoCardless payment page (view a live example)

Customers first land on the payment page


Step two – customer completes & confirms their details

The customer confirms their details


Step three – user is redirected to the merchant's redirect_uri OR shown default confirmation

The customer confirms their details


Step four – GoCardless emails the customer to confirm receipt of payment

The customer confirms their details

Storing IDs

You can safely assume resource IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length.

If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).

Dummy bank details

When you're preparing your integration in the sandbox, you'll need to make test payments to ensure that everything is working. For this, you can use our special sample bank details - these will only work in the sandbox:

Account number : 55779911

Sort code : 20-00-00

Even if you use your own bank details, no real money ever changes hands when you're using the sandbox.

Support

Need help with your integration? Check out the troubleshooting guide below, or get in touch.

Troubleshooting

The payment page says 400 error: "Client is invalid"

The developer credentials you entered are incorrect; in particular your client ID (also called your app ID) is incorrect. You should take two steps to remedy this:

  1. Ensure that you have entered your developer credentials correctly.
  2. Ensure that you are using your developer credentials in the correct environment. If your requests begin https://sandbox.gocardless.com you should be using your sandbox developer credentials. If your requests begin https://gocardless.com you should be using your live developer credentials.

The payment page says 400 error: "Signature is invalid"

Assuming that you're using a client library, the developer credentials you entered are incorrect; in particular your app secret is incorrect. You should take two steps to remedy this:

  1. Ensure that you have entered your developer credentials correctly by copying and pasting them from your developer settings again.
  2. Ensure that you are using your developer credentials in the correct environment. If your requests begin https://sandbox.gocardless.com you should be using your sandbox developer credentials. If your requests begin https://gocardless.com you should be using your live developer credentials.

If you're not using a client library, the above error may also be caused by a failure to sign your request correctly. You should review the way you sign requests, and in particular, that you are normalizing the parameters in your requests before signing them.

The payment page says 400 error: "Merchant not found with the ID provided"

The developer credentials you entered are incorrect; in particular your merchant ID is incorrect. You should take two steps to remedy this:

  1. Ensure that you have entered your developer credentials correctly by copying and pasting them from your developer settings again.
  2. Ensure that you are using your developer credentials in the correct environment. If your requests begin https://sandbox.gocardless.com you should be using your sandbox developer credentials. If your requests begin https://gocardless.com you should be using your live developer credentials.

The payment page says 400 error: "Redirect uri does not match the uri registered in the developer panel"

The redirect URI in your code does not match the redirect URI in your GoCardless developer settings.

Please ensure that the port, scheme, host and domain of the two redirect URIs match. If you wish to vary the subdomains of your redirect URIs, check the 'enable subdomains' option in your developer settings.

Please be sure you have the correct redirect URI in both your sandbox and live developer settings.

The payment page says 400 error: "Timestamp has expired"

The payment links that you generate are valid for 3 hours for security reasons - this message indicates that it has been longer than 3 hours since the link was generated.

You should generate payment links as required - if you need to email a link to a customer that might not click it until after 3 hours, it should be to a page on your site that generates a payment link and forwards the customer as appropriate.

The payment page begins https://sandbox.gocardless.com but I want to use the live environment

You have not set your environment to use "production".

My payments are not getting confirmed

Firstly, please ensure that you are attempting to confirm your payment on the redirect URL page (more details here).

Secondly, ensure that you have the correct developer credentials and environment set up on your confirmation page. If you are trying to create payments in the live environment, but you are attempting to confirm using sandbox environment or developer credentials, you will run into an error.

If you payments still fail to confirm, try catching the exception thrown by the GoCardless library when running the confirm function. More details here.

My testing bill webhook says amount = £20

All test webhooks are created from a template, so the amount will always equal £20. The resource ID, source ID and status will be set to those given in the webhook tester.

For more information on testing webhooks, please see the testing webhooks section.

Something else is broken

All our libraries will raise exceptions explaining an issue when something goes wrong. If you don't know the root cause of an issue, you should attempt to catch this exception.

Here are the functions that will catch exceptions in the languages that GoCardless supports:

Contact us

Need help with your integration? We offer two forms of support for developers: IRC and email.

Please try to catch exceptions before contacting support with any troubleshooting related issues.

IRC

Join our developer chat at #gocardless on irc.freenode.net.

Email

Alternatively, please email us at [email protected].

We can provide the most effective support via these two channels as they allow us to see your code.

Payment timings

Merchants can use our API to check when and what their next payout from GoCardless will be. The attributes next_payout_date and next_payout_amount on the merchant resource detail this.

balance, also on the merchant resource, details the entire outstanding balance held on behalf of a merchant, regardless of the holding period. balance will always be greater than or equal to the next_payout_amount.

Payments you take with GoCardless are paid out to your chosen bank account 3 working days after the customer is charged. View full details here.

Changelog

This page serves as a record of changes to the GoCardless API. Any major updates will also be announced to developers via email.

November 22nd, 2013

Adds a cancelled status to bills & webhooks. Previously, when a payment was cancelled by a merchant or customer, the status given would be failed. This update means that, in this scenario, the new cancelled status will be shown.

August 23rd, 2013

Adds a charge_customer_at attribute to choose on what date a payment will be debited from the customer's account when creating a bill against a pre-authorization.

June 28th, 2013

Adds a retried web hook for when a bill is resubmitted to the banks after having previously failed.

May 20th, 2013

Added a is_setup_fee attribute to each bill, allowing you to determine whether a bill was created as an initial charge on a subscription or pre-authorization using the setup_fee parameter.

May 15th, 2013

Added Payouts API. Adds a payout_id to each bill and allows viewing of individual payouts via /api/v1/payouts/:id and payouts for a specific merchant via /api/v1/merchants/:id/payouts.

Added pagination support. Adds support for pagination when querying resources using the per_page and page parameters, as well as useful headers.

Apr 17, 2013

Added retry method to Bill object which allows a failed payment to be resubmitted by making a POST request to /api/v1/bills/:id/retry.

Nov 30, 2012

Added hide_variable_amount attribute to Merchant resource in API, signifying whether a merchant has turned on the option in their Settings.

Aug 10, 2012

Added optional setup fees for subscriptions and pre-authorizations. See the Connect Guide.

Jan 30, 2012

Added the ability to cancel subscriptions and pre-authorisations via the API. For more information, see the API Guide.

API Libraries

Official Libraries

We strongly encourage use of our official libraries for accessing the GoCardless API. Our official libraries are listed below, as well as community supported libraries.

PHP

Install from source:

git clone [email protected]:gocardless/gocardless-php.git

or install from tarball:

curl -L https://github.com/downloads/gocardless/gocardless-php/gocardless-php-v0.4.1.tgz | tar xzv

Check out our PHP docs or view source on Github.


Ruby

Added to your Gemfile:

gem 'gocardless'

Check out our Ruby docs or view source on Github.


Python

Install from pip:

 pip install gocardless

Check out our Python docs or view source on Github.


Node.js

Install with npm:

npm install --save gocardless

Check out our Node.js docs or view source on Github.


.NET

Install with NuGet:

NuGet.exe install GoCardless

If you're using NuGet from within Visual Studio, simply run:

Install-Package GoCardless

Check out our .NET docs or view source on Github.


Java

Install with Maven:

<dependency>
  <groupId>com.gocardless</groupId>
  <artifactId>gocardless-java</artifactId>
  <version>1.1.0</version>
</dependency>

Check out our Java docs or view source on Github.


Community libraries

Please submit a pull request to this page to add any missing libraries that should be featured here. Please note that GoCardless does not offer any support for community libraries.

Wordpress

Clojure

Perl

CFML (ColdFusion/Railo)

Creating Payments

Generating payment links

To create a GoCardless payment you will need to send your customer to a GoCardless payment page (to read more about the GoCardless payment flow, please see the GoCardless anatomy section).

The link must consist of a number of elements:

  • A GoCardless environment: Currently the options are:
    • For the live environment: https://gocardless.com
    • For the sandbox environment: https://sandbox.gocardless.com
  • A GoCardless endpoint: the endpoint will depend on the resource type that you would like to create:
    • For one-off bills: /connect/bills/new?
    • For subscriptions: /connect/subscriptions/new?
    • For pre-authorizations: /connect/pre_authorizations/new?
  • A resource parameters array: the parameters passed will depend upon the resource type. Any parameters must be URL encoded.
    • An example parameter array for a £10 bill with the name 'my first payment' (before URL encoding): bill[amount]=10.0&bill[name]=my first payment
    • An example parameter array for a £10 bill with the name 'my first payment' (after URL encoding): bill%5Bamount%5D=10.0&bill%5Bname%5D=my%20first%20payment
  • An optional users array: this array should contain any customer details that you would like to see pre-populated on the GoCardless payment page.
  • Required parameters: these parameters include a merchant_id, client_id, timestamp and nonce. To see the required parameters for a resource, see the section for the resource type that you are trying to create.
  • Signature: this is a security parameter generated to ensure that you have permission to setup this resource. Please see the signing requests section for more information.

Parameters for different resource types

The URL for the GoCardless payment page will need to contain a number of parameters that specify details for the new resource that you are attempting to create. To see the required and optional parameters, please see the appropiate section in the resource section:

Pre-populating information

Currency information

If your account has been set up to accept international payments (see gocardless.com/europe), you will be able to supply a currency for your payment.

To set the currency, please provide it inside of the payment details when creating a payment link:

{
  "subscription": {
    "amount":"50.00",
    "name": "Gold membership",
    "merchant_id": "MERCHANT_ID",
    "interval_length": 1,
    "interval_unit": "month",
    "currency": "EUR"
  }
}

The currency parameter can be one of the following:

  • EUR: € Euro
  • GBP: £ British Pound Sterling (default)

Billing information

When redirecting users to payment pages, you have the option to provide a user object to pre-populate the user's payment form on GoCardless. This can dramatically increase conversion of your users to paying customers.

The user object should be provided inside of the payment details when creating a payment link:

{
  "subscription": {
    "amount":"50.00",
    "name": "Gold membership",
    "merchant_id": "MERCHANT_ID",
    "interval_length": 1,
    "interval_unit": "month",
    "currency": "GBP",
    "user": {
      "first_name": "Alasdair",
      "last_name": "Monk",
      "company_name": "GoCardless Ltd",
      "email": "[email protected]",
      "billing_address1": "22-25 Finsbury Square",
      "billing_address2": "Royal London House",
      "billing_town": "London",
      "billing_postcode": "E84DQ",
      "country_code": "GB"
    }
  }
}

For EUR payments [user]country_code can be one of the following:

  • AT: Austria
  • BE: Belgium
  • CY: Cyprus
  • EE: Estonia
  • FI: Finland
  • FR: France
  • DE: Germany
  • GR: Greece
  • IE: Ireland
  • IT: Italy
  • LV: Latvia
  • LU: Luxembourg
  • MT: Malta
  • MC: Monaco
  • NL: Netherlands
  • PT: Portugal
  • SM: San Marino
  • SK: Slovakia
  • SI: Slovenia
  • ES: Spain

Signing requests

Signature Guide

You'll only need this guide if you're writing your own client library in another language - otherwise, our official libraries cover all of this for you.

This is used widely throughout the "Connect" web interface and webhooks. The signature ensures that data transmitted over insecure connections cannot be tampered with by attackers.

The process for generating the signature broadly follows the process described in the OAuth 1.0 spec (RFC 5849, §3.4).

Constructing the parameter array

The initial set of parameters is a dictionary mapping parameter names to values. The values may be primitive types (strings, integers) or complex types (arrays, dictionaries). The first step is to convert the dictionary to an array of key-value pairs. If there are any complex values, the dictionary will need to be flattened so that each leaf-level value is promoted to a top-level key-value pair in the resulting array. The following scheme is used for constructing the keys of promoted values:

Values inside arrays each take the array's key, with a set of empty square brackets appended to the end:

{ cars: ['BMW', 'Fiat', 'VW'] }

Becomes:

[ ['cars[]', 'BMW'], ['cars[]', 'Fiat'], ['cars[]', 'VW'] ]

Key-value pairs in nested dictionaries follow a similar scheme. The top-level key is generated by adding '[' + key + ']' to the parent dictionary's key:

{ user: { name: 'Fred', age: 30 } }

Becomes:

[ ['user[name]', 'Fred' ], ['user[age]', '30' ] ]

These rules are used in combination to convert the dictionary to an array:

{ user: { name: 'Fred', cars: ['BMW', 'Fiat'] } }

Becomes:

[ ['user[name]', 'Fred'], ['user[cars][]', 'BMW'], ['user[cars][]', 'Fiat' ] ]

Normalizing the parameters

Both the key and value in each pair are percent-encoded according to RFC 5849, §3.6. Note that the standard URL and query-string encoding functions in most languages are not by default compliant with the RFC. Language specific examples are provided below.

[ ['user[email]', '[email protected]' ], ['user[age]', '30' ] ]

Becomes:

[ ['user%5Bemail%5D', 'fred%40example.com' ], ['user%5Bage%5D', '30' ] ]

Sort the request parameter key-value pairs by key in ascending byte order. If two keys are equal, then they are sorted by value.

[ ['user%5Bemail%5D', 'fred%40example.com' ], ['user%5Bage%5D', '30' ] ]

Becomes:

[ ['user%5Bage%5D', '30' ], ['user%5Bemail%5D', 'fred%40example.com' ] ]

Each of the key-value pairs are joined by an '=' sign:

[ ['user%5Bage%5D', '30' ], ['user%5Bemail%5D', 'fred%40example.com' ] ]

Becomes:

[ 'user%5Bage%5D=30', 'user%5Bemail%5D=fred%40example.com' ]

The resulting array of strings is joined by '&' signs: e.g

[ ['user%5Bage%5D', '30' ], ['user%5Bemail%5D', 'fred%40example.com' ] ]

Becomes:

'user%5Bage%5D=30&user%5Bemail%5D=fred%40example.com'

Signing the parameters

Create a HMAC-SHA256 digest of the normalized string, using the app secret (available in Developer Panel) as the key.

App secret: '5PUZmVMmukNwiHc7V/TJvFHRQZWZumIpCnfZKrVYGpuAdkCcEfv3LIDSrsJ+xOVH'
Parameters: 'user%5Bage%5D=30&user%5Bemail%5D=fred%40example.com'
Signature: '763f02cb9f998a5e06fda2b790bedd503ba1a34fd7cbf9e22f8ce562f73f0470'

The hexadecimal representation of the signature should be included as a request parameter named signature. The complete request would look like:

https://gocardless.com/connect/subscriptions/new?client_id=3QmpV5yi8Ii9Rc2uCwalWRsqkpibtk5ISOk%2FF%2BoyzrOoNpjGguZ4IRn2379agARS&nonce=DGsrJuOpuT%2FUlhM6Ok5gcpod0447E%2F4RJvx%2BG1Xa0eZnb2uRDF9VRRMj00Rj&signature=f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb&subscription%5Bamount%5D=1&subscription%5Bdescription%5D=gold&subscription%5Binterval_length%5D=1&subscription%5Binterval_unit%5D=day&subscription%5Bmerchant_id%5D=WOQRUJU9OH2HH1&timestamp=2011-01-01T08%3A00%3A00Z

Examples

Node JS:

var crypto = require('crypto');
var _ = require('lodash');

function encode(str) {
  return encodeURIComponent(str)
    .replace(/!/g, '%21')
    .replace(/'/g, '%27')
    .replace(/\(/g, '%28')
    .replace(/\)/g, '%29')
    .replace(/\*/g, '%2A');
}

function concat(array) {
  return Array.prototype.concat.apply([], array);
}

function toQuery(params, ns) {
  // Recurse if params is an array
  if (_.isArray(params)) {
    return concat(params.map(function(v) {
      return toQuery(v, ns + '[]');
    }));
  }

  if (_.isObject(params)) {
    var pairs = concat(Object.keys(params).map(function(key) {
      return toQuery(params[key], (ns ? ns + '[' + key + ']' : key));
    }));

    if (ns) return pairs;

    return pairs.sort(function(a, b) {
      return a.join('\0') < b.join('\0') ? -1 : (a === b ? 0 : 1);
    }).map(function(pair) {
      return pair.join('=');
    }).join('&');
  }

  return [[encode(ns), encode(params)]];
}

function sign(query, secret) {
  return crypto.createHmac('sha256', secret).update(query).digest('hex');
}

var signature = sign(toQuery(myParams), mySecret);

Confirming payments

Once a payment has been created, the customer will be redirected back to the redirect URI set in your GoCardless developer panel or the redirect URI set in your payment URL. You must then notify GoCardless that the customer was successfully returned to your website by sending GoCardless a POST request.

Returned parameters

The customer will be returned with a number of parameters. To read about the parameters returned on each payment type, please see the following resources:

Sending the confirmation

A POST should be sent back to GoCardless with the following parameters:

Request params

resource_id

required the id provided in the initial GET request

resource_type

required the resource type provided in the initial GET request

Basic authentication

You must confirm payments using Basic Authentication. This is a header that is constructed using the following method:

  1. App ID and App Secret are combined into a string "AppID:AppSecret" (you can find these values in your developer panel).
  2. The resulting string literal is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line.
  3. The authorization method and a space i.e. "Basic " is then put before the encoded string.

For example, if you were to create an authorisation header for the App ID 'Aladdin' and App Secret 'open sesame', you would generate the following header:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Using the REST API

API endpoints

To use the GoCardless API to query data, you will need to send a request to the correct endpoint. Request endpoints should depend on whether you wish to query the live or sandbox environment:

  • Sandbox: https://sandbox.gocardless.com
  • Live: https://gocardless.com

To see all the available GoCardless endpoints, please see the resources section.

Please note: the GoCardless API does not allow you to set up a GoCardless payment, instead you will need to send your customers a link to a GoCardless payment page.

Authentication

To access the API, simply pass an Authorization header containing bearer for the merchant (you can also find this in the developer panel):

Authorization: bearer INSERT_MERCHANT_ACCESS_TOKEN

The access token will differ between the live and sandbox environments.

You will also need to pass an Accept header (e.g. application/json), or append .json or .xml to the URL requested.

Each token is unique to a merchant. If you are managing several merchants with one app, you will need to specify a different token for each request.

HTTP response codes

You may encounter the following response codes. Any unsuccessful response codes will contain more information to help you identify the cause of the problem.

200

The request has succeeded.

201

The request has been fulfilled and resulted in a new resource being created. The newly create resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field.

400

The request could not be understood by the server, usually due to malformed syntax. The response body will contain more details in the form of an array.

401

Unauthorized. The client has not provided a valid Authentication HTTP header.

403

Forbidden. The client has provided a valid Authentication header, but it does not have permission to access this resource.

404

Not Found. The requested resource was not found. The response body will explain which resource was not found.

412

Precondition Failed. Certain unmet conditions must be fulfilled before the request to be processed e.g. timestamp is too old. More details in response body.

418

I'm a teapot. The webserver cannot respond as it is temporarily a teapot.

422

Unprocessable Entity. Could not process a POST request because the request is invalid. The response body will contain more details in the form of an array.

500

Internal Server Error. The server encountered an error while processing your request and failed. Please report this to the GoCardless support team.

Filtering

Many of the index resources available via the API can be filtered to cut down the number of objects returned. This will result in much faster API response times.

e.g. show paid bills from user with id=29:

https://gocardless.com/api/v1/merchants/INSERT_MERCHANT_ID/bills?user_id=29&paid=true
Filter Value Available on Notes
source_id string Bill The parent resource of the bill e.g. a subscription or pre-authorization
source_type string Bill Returns only bills which were created under a specific type of source; 'subscription', 'pre_authorization' or 'ad_hoc_authorization' (ie one-off)
subscription_id string Bill What is the parent subscription of the bill?
pre_authorization_id string Bill What is the parent pre_authorization of the bill?
user_id string Bill, Subscription, Pre_Authorization All resources belonging to a single user
before Datetime Bill, Subscription, Pre_Authorization Created before a given date. A string representing datetime (must be url-encoded). e.g. "2011-11-17T15:00:23Z"
after Datetime Bill, Subscription, Pre_Authorization Created after a given date. A string representing datetime (must be url-encoded). e.g. "2011-11-17T15:00:23Z"
status string Bill, Subscription, Pre_Authorization Return only resources with the given status.
paid boolean (true/false) Bill Return only paid bills. False will include "pending" and "failed" bills. True will return "paid" and "withdrawn" bills.
name string Bill, Subscription, Pre_Authorization Requires an exact literal match with the resource name
description string Bill, Subscription, Pre_Authorization Requires an exact literal match with the resource description

Pagination

Pagination may optionally be enabled for endpoints that return multiple records. It is strongly advised that pagination is used when a large number of records need be be retrieved; in the future this may be enforced.

There are two parameters that control pagination: page, which specifies the page number to retrieve, and per_page, which indicates how many records each page should contain. To enable pagination, simply include either of these query string parameters in a request.

e.g. show page 2 of all a merchant's bills:

https://gocardless.com/api/v1/merchants/INSERT_MERCHANT_ID/bills?page=2&per_page=20

If pagination is enabled, but page is not provided, it will default to 1 (the first page). per_page defaults to 100.

Paginated responses include extra headers, Link and X-Pagination, which indicate the total number of records and pages, and link to neighbouring pages.

HTTP/1.1 200 OK
Link: <https://gocardless.com/api/v1/merchants/XYZ/bills?page=2&per_page=10>; rel="next",
     <https://gocardless.com/api/v1/merchants/XYZ/bills?page=2&per_page=10>; rel="last"
X-Pagination: {"records":15,"pages":2,"links":{"next":2,"last":2}}
Content-Type: application/json; charset=utf-8
Connection: close
Server: nginx
Webhooks

Webhook overview

To alert you of any changes in the status of your resources, GoCardless provides webhooks. These are POST requests to your server that are sent as soon as a resource changes status. The body of the request contains details of the change.

To read more about how webhooks will fit into your application flow, please see the GoCardless Anatomy

Request

The API server will send a POST request to the web_hook_uri associated with the merchant/app. This can be set in Developer Panel.

The POST request will contain JSON data in the body, providing details of the action completed. The data will contain an HMAC digest signature generated using the merchant's app secret - this prevents attackers imitating valid web hooks.

payload

A hash/dictionary, the top level namespace.

resource_type

A string: "bill", "pre_authorization", or "subscription".

action

A string, description of the event that triggered the webhook. Details below.

objects

An array of hashes/dictionaries of the relevant object, named as the pluralize name of the resource type.

signature

HMAC digest of the contents of payload, signed with the app secret.

Example request

{
    "payload": {
        "resource_type": "bill",
        "action": "paid",
        "bills": [
            {
                "id": "AKJ398H8KA",
                "status": "paid",
                "source_type": "subscription",
                "source_id": "KKJ398H8K8",
                "amount": "20.0",
                "amount_minus_fees": "19.8",
                "paid_at": "2011-12-01T12:00:00Z",
                "uri": "https://gocardless.com/api/v1/bills/AKJ398H8KA"
            },
            {
                "id": "AKJ398H8KB",
                "status": "paid",
                "source_type": "subscription",
                "source_id": "8AKJ398H78",
                "amount": "20.0",
                "amount_minus_fees": "19.8",
                "paid_at": "2011-12-09T12:00:00Z",
                "uri": "https://gocardless.com/api/v1/bills/AKJ398H8KB"
            }
        ],
        "signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
    }
}

Response

Your server should validate the HMAC digest by resigning the contents of the payload object, not including the container payload itself, and respond with status HTTP/1.1 200 OK within 5 seconds.

For more information about generating a signature see Signing Requests in the Connect Guide. The GoCardless client libraries each handle signing requests; if you are building an integration without a client library, check their source code for a reference implementation.

If the API server does not get a 200 OK response within 5 seconds, it will retry up to 10 times at ever-increasing time intervals. If you have time-consuming server-side processes that are triggered by a webhook please consider processing them asynchronously.

In the request above, the object to sign is:

{
    "resource_type": "bill",
    "action": "paid",
    "bills": [
        {
            "id": "AKJ398H8KA",
            "status": "paid",
            "source_type": "subscription",
            "source_id": "KKJ398H8K8",
            "amount": "20.0",
            "amount_minus_fees": "19.8",
            "paid_at": "2011-12-01T12:00:00Z",
            "uri": "https://gocardless.com/api/v1/bills/AKJ398H8KA"
        },
        {
            "id": "AKJ398H8KB",
            "status": "paid",
            "source_type": "subscription",
            "source_id": "8AKJ398H78",
            "amount": "20.0",
            "amount_minus_fees": "19.8",
            "paid_at": "2011-12-09T12:00:00Z",
            "uri": "https://gocardless.com/api/v1/bills/AKJ398H8KB"
        }
    ]
}

The normalized string for the above (before percent encoding and signing) is:

action=paid&bills[][amount]=20.0&bills[][amount]=20.0&bills[][amount_minus_fees]=19.8&bills[][amount_minus_fees]=19.8&bills[][id]=AKJ398H8KA&bills[][id]=AKJ398H8KB&bills[][paid_at]=2011-12-01T12:00:00Z&bills[][paid_at]=2011-12-09T12:00:00Z&bills[][source_id]=8AKJ398H78&bills[][source_id]=KKJ398H8K8&bills[][source_type]=subscription&bills[][source_type]=subscription&bills[][status]=paid&bills[][status]=paid&bills[][uri]=https://gocardless.com/api/v1/bills/AKJ398H8KA&bills[][uri]=https://gocardless.com/api/v1/bills/AKJ398H8KB&resource_type=bill

Available webhooks

Bill webhook

Example bill webhook object:

{
  "payload": {
      "resource_type": "bill",
      "action": "paid",
      "bills": [
          {
              "id": "AKJ398H8KA",
              "status": "paid",
              "source_type": "subscription",
              "source_id": "KKJ398H8K8",
              "amount": "20.0",
              "amount_minus_fees": "19.8",
              "paid_at": "2011-12-01T12:00:00Z",
              "uri": "https://gocardless.com/api/v1/bills/AKJ398H8KA"
          },
          {
              "id": "AKJ398H8KB",
              "status": "paid",
              "source_type": "subscription",
              "source_id": "8AKJ398H78",
              "amount": "20.0",
              "amount_minus_fees": "19.8",
              "paid_at": "2011-12-09T12:00:00Z",
              "uri": "https://gocardless.com/api/v1/bills/AKJ398H8KB"
          }
      ],
      "signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
  }
}

Possible actions

created

This is fired when a bill is created automatically under a subscription, e.g. for a monthly subscription, you will receive this webhook once per month. The bill will be pending for several days until it is paid or has failed.

paid

This is fired when a bill has successfully been debited from a customer's account. It can take up to 5 business days after bill creation if it's the first bill taken from a customer. The cash will be held by GoCardless for the duration of the Merchant's holding period, after which it will be withdrawn (i.e. paid out) directly into the Merchant's registered bank account.

withdrawn

This is fired when a bill that is being held by GoCardless on behalf of a Merchant is withdrawn (i.e. paid out) into the Merchant's bank account. Money should appear in the account no later than 1 business day after the webhook is fired.

failed

This is fired when a bill could not be debited from a customer's account. This is usually because insufficient funds are available. By default, GoCardless will not attempt to take the payment again.

cancelled

This is fired when a bill has been cancelled by you or the customer (through the dashboards). A cancelled bill cannot be retried.

refunded

This is fired when a bill is refunded by you (through the dashboards) or by GoCardless at your request.

chargedback

This is fired when a customer contacts their bank and has them reverse the payment under the Direct Debit Guarantee.

retried

This is fired when a bill is submitted to the bank again after having previously been failed, either at your request or the customer's. The bill's status will be "pending", and you should receive a "paid" or "failed" web hook within 3 business days.

If the bill was created under a subscription or a pre-authorization, the source_id and source_type arguments will enable you to identify the "parent" resource (ie. the "source" of the bill).

The id arguments refer to the id of the each individual bill object.

Pre-authorization webhook

Example pre-authorization webhook object:

{
  "payload": {
    "resource_type": "pre_authorization",
    "action": "cancelled",
    "pre_authorizations": [{
      "id": "AKJ398H8KBOOO3",
      "status": "cancelled",
      "uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOO3"
    }, {
      "id": "AKJ398H8KBOOOA",
      "status": "cancelled",
      "uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOOA"
    }],
    "signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
  }
}

Possible actions

cancelled

This is fired when a pre-authorization is cancelled by a customer. No further bills can be created under this pre-authorization.

expired

This is fired when a pre-authorization reaches its expiry date. No further bills can be created under this pre-authorization.

Subscription webhook

Example subscription webhook object:

{
  "payload": {
    "resource_type": "subscription",
    "action": "cancelled",
    "subscriptions": [{
      "id": "AKJ398H8KBO122A",
      "status": "cancelled",
      "uri": "https://gocardless.com/api/v1/subscriptions/AKJ398H8KBO122A"
    },{
      "id": "BBJ398H8KBO122A",
      "status": "cancelled",
      "uri": "https://gocardless.com/api/v1/subscriptions/BBJ398H8KBO122A"
    }],
    "signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
  }
}

Possible actions

cancelled

This is fired when a subscription is cancelled by a customer. No further bills will be created under the subscription.

expired

This is fired when a subscription reaches its expiry date. No further bills will be created under the subscription.

Guides

Partner guide

Our Partner API allows you to manage multiple merchant accounts.

Partner account setup

If you're interested in using our Partner API, please email us for more information.

Once you have used the API to create merchant(s), see the resources section for more information about how to create new bills and subscriptions for these merchants.

Before you can use the Partner API, you'll need to have set a redirect_uri on your Dashboard's Developer tab.

Creating multiple merchants

The authorization process roughly follows the OAuth 2.0 protocol. To make API requests on behalf of a merchant account, an access token is required. The process of obtaining an access token is described below.

During the process, the user will be prompted to give the referring app permission to manage an existing merchant account, or alternatively to create a new merchant account.

Request

To start the process the user should be redirected to the authorization URL (https://gocardless.com/oauth/authorize) with the following parameters passed in the URL:

client_id

your app identifier

redirect_uri

the URI to redirect the user to once the authorization process has been completed. Please note that the scheme, host and port of a provided redirect_uri must match the URL set for the account

scope

this should be set to manage_merchant

response_type

this should be set to code

You may also include a state argument which is passed back at the end of the process. This may be useful in identifying the user on return from GoCardless.

You may also include a merchant object which will be used to pre-populate fields for the user during the connect flow. See the final section on pre-populating information.

The resulting request will look like this:

https://gocardless.com/oauth/authorize?client_id=XXX&amp;redirect_uri=http%3A%2F%2Fexample.com%2F&amp;cb&amp;response_type=code&amp;scope=manage_merchant

The user will be shown a page confirming that they would like to link a merchant account to your app. They can also create their account at this stage.

Response

If the user approves the request, they will be redirected to the redirect_uri provided in the request with an authorization code passed in the URL:

{
 "code": "",
}

The state variable will also be returned in the URL if it was provided in the original request.

Exchange authorization code for access token

The authorization code needs to be exchanged for an access token before you can make authenticated API requests. To perform the exchange, you need to send a POST request to the access token endpoint: https://gocardless.com/oauth/access_token.

This request should be authenticated by passing the app identifier and app secret via HTTP Basic Authorization. The request should be made with the following parameters:

client_id

your app identifier

code

the authorization code received above

redirect_uri

this must match the original URI exactly

grant_type

this should be set to authorization_code

If the request is successful then the response will look like this:

{
  "access_token": "MvYX0i6snRh3gevXWbE5a56blveHqPLpLFjfOuZoWusd5AewvXuhcMU/1PXfPoc6",
  "token_type": "bearer",
  "scope": "manage_merchant:VSXU7HPAY7OZN6"
}

The ID following the colon within scope is the ID of the merchant account (VSXU7HPAY7OZN6 in this case) that the user linked to the app. This should be used in future API requests to identify the merchant.

Authenticated API requests can now be made by setting the Authorization header to:

bearer MvYX0i6snRh3gevXWbE5a56blveHqPLpLFjfOuZoWusd5AewvXuhcMU/1PXfPoc6

Pre-populating information

You can provide certain information in the initial request to enable GoCardless to pre-populate registration fields for your user. This is highly encouraged, as it increases user conversion.

You may provide the following information:

{
  "merchant": {
    "user": {
      "email": "[email protected]",
      "first_name": "Roy",
      "last_name": "Roy"
    },
    "name": "Dr Roy",
    "phone_number": "07500000000",
    "description": "Burgers and mash",
    "merchant_type": "business",
    "company_name": "Roy's Burger Emporium",
    "company_registration": "0112358132134",
    "bank_reference": "ROYSBURGERS"
  }
}

The variable merchant['merchant_type'] can be set to one of the following values:

'business' | 'charity' | 'individual'
Resources

Bill

A bill is a one-off payment from a user. Bills can be created ad-hoc or a bill can be created after a user has already pre-authorized Direct Debit payments to a merchant.

Create a one-off bill

A user pays a one-off amount to the merchant. The user should be redirected to the url and will be asked for authorisation.

If the user has an existing active pre-authorization, you may wish to create a bill under a pre-authorization

Request params

bill[amount]

required the amount of the bill.

bill[merchant_id]

required your merchant ID.

bill[name]

Brief description used to identify the payment, displayed to the user alongside the amount. Often useful for an invoice reference.

bill[description]

A more verbose description, which will be displayed to the user.

bill[user]

Allows pre-population of user information - see pre-populating information

signature

required Generated from the request prams according to the signature guide

nonce

required A random string to ensure the uniqueness of each request. This prevents multiple customers using the same link to access the payments process. The nonce is stored for a period of 3 hours, after which it may be re-used. We recommend a random base64-encoded string, but any non-nil value may be used.

client_id

required Your app's identifier/app ID

timestamp

required UTC date and time in ISO 8601 format, e.g. 2011-01-01T12:00:00Z. The request must hit our server within 3 hours of this timestamp, otherwise it will be rejected.

redirect_uri

Where the user should be returned to after the authorization process. If it is not provided, the redirect_uri registered in the dashboard will be used. The scheme, host and port of a provided redirect_uri must match the URL set for the account.

cancel_uri

Where the user should be returned to if he or she chooses to cancel the connect process before completion. If it is not provided, the cancel_uri registered in the developer panel will be used. Note that the scheme, host and port of a provided cancel_uri must match those of the registered one. A cancel_uri can only be provided in the request if one is also set on the account.

state

This allows you to pass a value of your choice through the payment process, receiving it in the redirect page. If present, it will be passed back as a parameter when the user is returned to the merchant's site at the end of an authorization process. If a merchant's site passes in state="id_9SX5G36", it will receive back state="id_9SX5G36" when the user returns to the merchant's site. This state is not persisted in the GoCardless database.

Return value

Returns a link to a one-off payment mandate.

Confirmation

Once the user has given authorization for one of these resources to be created, it will exist in an 'inactive' state. The user will be redirected (a GET request) back to the URI specified.

You must confirm the resource otherwise it will be removed within a short period of time.

GET https://gocardless.com/connect/bills/new?client_id=123ABC&timestamp=2014-06-10T08%3A42%3A22Z&nonce=ABCDEF123%3D&bill[amount]=10.00&bill[merchant_id]=123ABC&signature=11abc2d3e1 HTTP/1.1

Confirm a new one-off bill

Redirection of customer after GoCardless payment page

When a user has completed the authorization process, the bill will exist in an 'inactive' state. The resource must be confirmed within a short period of time otherwise it will be removed from the database.

The user will be redirected (a GET request) back to the redirect URI specified in the developer panel with the following parameters:

resource_uri

The URI at which the new resource may be accessed via the API

resource_id

The unique id of the create resource

resource_type

The type of resource created. In this case "bill"

signature

A signature of the parameters

state

The state parameter passed in with the initial request if present

Checking the signature

Important - the signature is generated according to the signature guide (also using the merchant's app secret). It should be verified to check that the request has not been tampered with, i.e. - you should re-sign the other 4 params (3 if state is not used) and check that the signature matches the one provided. If it does not match, the request has been tampered with and should be rejected.

Completing the process

A POST should be sent back to GoCardless. You will need to send a Basic Authentication authorization header. The request must be sent with the following parameters:

Request params

resource_id

required the id provided in the initial GET request

resource_type

required the resource type provided in the initial GET request

POST https://gocardless.com/api/v1/confirm HTTP/1.1
{
  "resource_id": "1234ABCD",
  "resource_type": "bill"
}

HTTP/1.1 200 OK
{
  "success": true
}

List all bills

Request params

id

required id of merchant

Response

Returns an array of bills

GET https://gocardless.com/api/v1/merchants/{MERCHANT_ID}/bills HTTP/1.1

HTTP/1.1 200 OK
[
  {
    "amount": "44.0",
    "gocardless_fees": "0.44",
    "partner_fees": "0",
    "currency": "GBP",
    "created_at": "2014-08-20T21:41:25Z",
    "description": "Month 2 payment",
    "id": "123ABCD",
    "name": "Bill 2 for Subscription description",
    "paid_at":  null,
    "status": "pending",
    "merchant_id": "06Z06JWQW1",
    "user_id": "FIVWCCVEST6S4D",
    "source_type": "ad_hoc_authorization",
    "source_id": "YH1VEVQHYVB1UT",
    "uri": "https://gocardless.com/api/v1/bills/123ABCD",
    "can_be_retried": false,
    "payout_id": null,
    "is_setup_fee": false,
    "charge_customer_at": "2014-09-01"
  }
]

Retrieve an existing bill

Request params

id

required id of bill to retrieve

Response

Returns a bill object

GET https://gocardless.com/api/v1/bills/0P1AVA0D6A HTTP/1.1

HTTP/1.1 200 OK
{
  "amount": "44.0",
  "gocardless_fees": "0.44",
  "partner_fees": "0",
  "currency": "GBP",
  "created_at": "2014-08-20T21:41:25Z",
  "description": "Month 2 payment",
  "id": "0P1AVA0D6A",
  "name": "Bill 2 for Subscription description",
  "paid_at":  null,
  "status": "pending",
  "merchant_id": "06Z06JWQW1",
  "user_id": "FIVWCCVEST6S4D",
  "source_type": "ad_hoc_authorization",
  "source_id": "YH1VEVQHYVB1UT",
  "uri": "https://gocardless.com/api/v1/bills/0P1AVA0D6A",
  "can_be_retried": false,
  "payout_id": null,
  "is_setup_fee": false,
  "charge_customer_at": "2014-09-01"
}

Retry a failed bill

If a bill fails, its status will change to failed. At this point it can be retried if the can_be_retried attribute is true.

This operation is irreversible.

If a bill is retried, GoCardless will attempt to collect it again. You will receive a web hook confirming this. Eventually, the status will become paid or failed and you will receive appropriate web hooks.

Request params

id

required id of bill to retry

Response

Returns a bill object

POST https://gocardless.com/api/v1/bills/{BILL_ID}/retry HTTP/1.1

HTTP/1.1 201 CREATED
{
  "amount": "44.0",
  "gocardless_fees": "0.44",
  "partner_fees": "0",
  "currency": "GBP",
  "created_at": "2014-08-20T21: 41: 25Z",
  "description": "Month 2 payment",
  "id": "123ABCD",
  "name": "Bill 2 for Subscription description",
  "paid_at":  null,
  "status": "pending",
  "merchant_id": "06Z06JWQW1",
  "user_id": "FIVWCCVEST6S4D",
  "source_type": "ad_hoc_authorization",
  "source_id": "YH1VEVQHYVB1UT",
  "uri": "https://gocardless.com/api/v1/bills/123ABCD",
  "can_be_retried": false,
  "payout_id": null,
  "is_setup_fee": false,
  "charge_customer_at": "2014-09-01"
}

Cancel a pending bill

A pending bill can be cancelled if it has not yet been submitted to the banking system, which is the case if the can_be_cancelled attribute is true.

This operation is irreversible.

Request params

id

required id of bill to cancel

PUT https://gocardless.com/api/v1/bills/{BILL_ID}/cancel HTTP/1.1

HTTP/1.1 200 OK
{
  "amount": "44.0",
  "gocardless_fees": "0.44",
  "amount_minus_fees": "43.56",
  "partner_fees": "0.0",
  "currency": "GBP",
  "created_at": "2014-05-12T16:06:54Z",
  "description": "Bill description",
  "id": "0P1AVA0D6A",
  "name": "Bill name",
  "paid_at":  null,
  "status": "cancelled",
  "merchant_id": "0A1B2C3D4E",
  "user_id": "4A3B2C1D0E",
  "source_type": "ad_hoc_authorization",
  "source_id": "0B1B2B3B4B",
  "uri": "https://gocardless.com/api/v1/bills/0P1AVA0D6A",
  "can_be_retried": false,
  "can_be_cancelled": false,
  "payout_id": null,
  "is_setup_fee": false,
  "charge_customer_at": "2014-05-27"
}

Refund a bill

A bill can be refunded if its can_be_refunded attribute is true, and it has a status of paid or withdrawn.

This operation is irreversible.

This endpoint will only be available if refunds have been enabled on your merchant account. You can contact [email protected] to request that we enable this for you.

Request params

id

required id of bill to refund

POST https://gocardless.com/api/v1/bills/{BILL_ID}/refund HTTP/1.1

HTTP/1.1 201 CREATED
{
  "amount": "1.0",
  "gocardless_fees": "0.01",
  "amount_minus_fees": "0.99",
  "partner_fees": "0.0",
  "currency": "GBP",
  "created_at": "2014-05-12T16:06:54Z",
  "description": "Bill description",
  "id": "0P1AVA0D6A",
  "name": "Bill name",
  "paid_at":  null,
  "status": "refunded",
  "merchant_id": "0A1B2C3D4E",
  "user_id": "4A3B2C1D0E",
  "source_type": "subscription",
  "source_id": "0B1B2B3B4B",
  "uri": "https://gocardless.com/api/v1/bills/0P1AVA0D6A",
  "can_be_retried": false,
  "can_be_cancelled": false,
  "payout_id": null,
  "is_setup_fee": false,
  "charge_customer_at": "2014-05-27"
}

Bill statuses

pending

Waiting for the money to clear from the customer's account.

paid

Bill has been successfully been debited from the customer's account. It is being held by GoCardless pending a withdrawal to the merchant.

failed

Bill could not be debited from a customer's account. This usually means that there were insufficient funds in the customer's account.

refunded

Bill has been refunded by you or by GoCardless at your request.

chargedback

Bill has been reversed by the customer at their bank under the Direct Debit Guarantee.

cancelled

Bill was cancelled by the merchant or customer before it was submitted to the banks.

withdrawn

The bill has been paid out to the merchant. Takes up to one business day to reach the merchant's bank account. You can find more details by using the bill's payout_id with the payouts resource.

Merchant

A merchant can collect payments from users in three ways: one-off bills, subscriptions or pre-authorizations.

Retrieve merchant details

Retrieve your merchant details (you can find your merchant id in the developer panel).

Request params

id

required id of merchant to retrieve

Response

Returns merchant details

GET https://gocardless.com/api/v1/merchants/{MERCHANT_ID} HTTP/1.1

HTTP/1.1 200 OK
{
  "created_at": "2011-11-18T17:07:09Z",
  "description": "Payments for monthly magazine subscriptions",
  "id": "MERCHANT_ID",
  "name": "Tom's Magazine",
  "first_name": "Tom",
  "last_name": "Blomfield",
  "email": "[email protected]",
  "uri": "https://gocardless.com/api/v1/merchants/MERCHANT_ID",
  "balance": "12.00",
  "pending_balance": "20.00",
  "next_payout_date": "2014-08-01",
  "next_payout_amount": "12.00",
  "hide_variable_amount": true,
  "sub_resource_uris": {
    "users": "https://gocardless.com/api/v1/merchants/MERCHANT_ID/users",
    "bills": "https://gocardless.com/api/v1/merchants/MERCHANT_ID/bills",
    "pre_authorizations": "https://gocardless.com/api/v1/merchants/MERCHANT_ID/pre_authorizations",
    "subscriptions": "https://gocardless.com/api/v1/merchants/MERCHANT_ID/subscriptions",
    "payouts": "https://gocardless.com/api/v1/merchants/MERCHANT_ID/payouts"
  }
}

Payout

A payout is a payment made from GoCardless to a merchant's bank account that consists of payments collected by the merchant, minus fees taken by GoCardless.

List all payouts

Request params

id

required id of merchant

Response

Returns an array of payout objects

paid_at is the date that the funds will reach your bank account.

GET https://gocardless.com/api/v1/merchants/{MERCHANT_ID}/payouts HTTP/1.1

HTTP/1.1 200 OK
[
  {
    "amount": "12.37",
    "bank_reference": "JOHNSMITH-Z5DRM",
    "app_ids": [
      "ABC"
    ],
    "created_at": "2013-05-10T16:34:34Z",
    "id": "0BKR1AZNJF",
    "paid_at": "2013-05-10T17:00:26Z",
    "transaction_fees": "0.13"
  },
  {
    "amount": "148.50",
    "bank_reference": "JOHNSMITH-A6GCK",
    "app_ids": [
      "BCD"
    ],
    "created_at": "2013-05-27T18:28:12Z",
    "id": "0BER2BDFRT",
    "paid_at": "2013-05-27T19:00:23Z",
    "transaction_fees": "1.50"
  }
]

Retrieve an existing payout

Request params

id

required id of payout to retrieve

Response

Returns a payout object

paid_at is the date that the funds will reach your bank account.

GET https://gocardless.com/api/v1/payouts/{PAYOUT_ID} HTTP/1.1

HTTP/1.1 200 OK
{
  "amount": "12.37",
  "bank_reference": "JOHNSMITH-Z5DRM",
  "created_at": "2013-05-10T16:34:34Z",
  "id": "0BKR1AZNJF",
  "paid_at": "2013-05-10T17:00:26Z",
  "transaction_fees": "0.13"
}

Pre-authorization

A pre-authorization should be used in the case where the merchant wants to collect variable Direct Debit payments from a user until expires_at.

Once a pre-authorization has been made, the merchant can collect bills from a user without the need for re-authorization.

Create a pre-auth

A user agrees to allow the merchant to create bills up to a pre-defined amount every pre-defined interval of time, until an expiry date e.g., up to £10 per week until 1 January 2015.

Pre-authorizations you make via the API can currently only be charged through the API. This means that you can't request payments from the Dashboard or through another partner app, for example.

Note that a pre-authorization allows the Merchant to bill the User in future without asking for explicit permission each time

Request params

pre_authorization [max_amount]

required the maximum amount that can be collected within one of the specified intervals.

pre_authorization [interval_length]

required The number of interval_units that make up the interval.

pre_authorization [interval_unit]

required The unit of measurement for the interval. Can be day, week or month.

pre_authorization [expires_at]

Date the pre-authorization expires. Note that pre-authorization will be expired just after midnight (UTC) of the expires_at date. Should be ISO8601 format.

pre_authorization [name]

brief description used to identify the pre-authorization, displayed to the user alongside the amount. Often useful for an "invoice reference".

pre_authorization [description]

A more detailed description, which will be displayed to the user.

pre_authorization [user]

Allows pre-population of user information - see pre-populating information

pre_authorization [interval_count]

Calculates the expires_at date based on the number of payment intervals that you would like the resource to have. Must be a positive integer greater than 0. Also if you specify an interval_count and a expires_at date, the later takes precedence. For example if the pre-authorization is created on the 15th of February and has a 1 day interval and an interval_count of 2 then the expires_at will be set for the 17th of February. The two intervals will be from the 15th to the 16th and from the 16th to the 17th.

pre_authorization [setup_fee]

A one-off amount to add to the beginning of the subscription. For example, adding a £25.00 setup fee to a £5 per month subscription would mean that the customer is charged £30 at sign up, and then £5 per month.

pre_authorization [calendar_intervals]

Boolean describing whether the interval attribute should be aligned with calendar weeks or months, default: false.

signature

required Generated from the request prams according to the signature guide

nonce

required A random string to ensure the uniqueness of each request. This prevents multiple customers using the same link to access the payments process. The nonce is stored for a period of 3 hours, after which it may be re-used. We recommend a random base64-encoded string, but any non-nil value may be used.

client_id

required Your app's identifier/app ID

timestamp

required UTC date and time in ISO 8601 format, e.g. 2011-01-01T12:00:00Z. The request must hit our server within 3 hours of this timestamp, otherwise it will be rejected.

redirect_uri

Where the user should be returned to after the authorization process. If it is not provided, the redirect_uri registered in the dashboard will be used. The scheme, host and port of a provided redirect_uri must match the URL set for the account.

cancel_uri

Where the user should be returned to if he or she chooses to cancel the connect process before completion. If it is not provided, the cancel_uri registered in the developer panel will be used. Note that the scheme, host and port of a provided cancel_uri must match those of the registered one. A cancel_uri can only be provided in the request if one is also set on the account.

state

This allows you to pass a value of your choice through the payment process, receiving it in the redirect page. If present, it will be passed back as a parameter when the user is returned to the merchant's site at the end of an authorization process. If a merchant's site passes in state="id_9SX5G36", it will receive back state="id_9SX5G36" when the user returns to the merchant's site. This state is not persisted in the GoCardless database.

Calendar interval examples:

calendar_intervals: true
interval_length: 1
interval_unit: month
Resource created: 15th January

The first interval will be from the 15th-31st January. The second interval will begin on the 1st of February and last for one month. Subsequent intervals will begin on the first of the month and last a calendar month.

calendar_intervals: true
interval_length: 1
interval_unit: week
Resource created: Wednesday

The first interval will run Wednesday - Sunday. The second interval will start on the following Monday and last a week. Subsequent intervals will be from Monday to Sunday.

If a pre-authorization is created at the beginning of a normal calendar interval (ie. Monday for a weekly interval or the first of the month for a monthly interval) then the first interval will run from that day until the end of that particular calendar interval.

If a pre-authorization is created with an interval_length greater than 1 then the second interval will commence at the start of the next typical calendar interval.

calendar_intervals: true
interval_length: 2
interval_unit: month
Resource created: 15th March

The first interval will run from 15-31st March. The second interval willcommence on the 1st April and last two months. Subsequent intervals will last two months.

Return value

Returns a link to a pre-authorisation mandate.

Variable payments

We also support payments using pre-authorizations which are more like traditional Direct Debit that you might be used to.

With this option enabled, when setting up a pre-authorization the customer will not be shown the maximum amount, but rather they will authorise for "Direct Debit payments". This provides great flexibility to take payments as you need.

To take advantage of this, simply enable the "Variable payments" option in the "Settings" tab of your dashboard and then set up a pre-authorization as usual. You should specify a maximum amount higher than you ever expect to bill your customer.

GET https://gocardless.com/connect/pre_authorizations/new?client_id=123ABC&timestamp=2014-06-10T08%3A42%3A22Z&nonce=ABCDEF123%3D&pre_authorization[interval_length]=1&pre_authorization[interval_unit]=month&pre_authorization[max_amount]=750.00&pre_authorization[merchant_id]=06Z06JWQW1&signature=11abc2d3e1 HTTP/1.1

Confirm a new pre-auth

Redirection of customer after GoCardless payment page

When a user has completed the authorization process, the pre-authorization will exist in an 'inactive' state. The resource must be confirmed within a short period of time otherwise it will be removed from the database.

The user will be redirected (a GET request) back to the redirect URI specified in the developer panel with the following parameters:

resource_uri

The URI at which the new resource may be accessed via the API

resource_id

The unique id of the create resource

resource_type

The type of resource created. In this case "pre_authorization"

signature

A signature of the parameters

state

The state parameter passed in with the initial request if present

Checking the signature

Important - the signature is generated according to the signature guide (also using the merchant's app secret). It should be verified to check that the request has not been tampered with, i.e. - you should re-sign the other 4 params (3 if state is not used) and check that the signature matches the one provided. If it does not match, the request has been tampered with and should be rejected.

Completing the process

A POST should be sent back to GoCardless. You will need to send a Basic Authentication authorization header. The request must be sent with the following parameters:

Request params

resource_id

required the id provided in the initial GET request

resource_type

required the resource type provided in the initial GET request

Response

Returns a success message or an error message

POST https://gocardless.com/api/v1/confirm HTTP/1.1
{
  "resource_id": "1234ABCD",
  "resource_type": "pre_authorization"
}

HTTP/1.1 200 OK
{
  "success": true
}

Create a bill under a pre-auth

Create a bill via the API under an existing pre-authorization.

The pre-authorization must have not yet expired, and the new bill must be within the pre-authorization max_amount.

Pre-authorizations that you've created with the API can only be charged this way, and not via the Dashboard or another partner app.

Request params

amount

required amount to charge customer (e.g. "10.00")

pre_authorization_id

required id of pre-authorization to charge bill under.

name

name of the bill. This will be shown to the customer.

description

further description of the bill.

charge_customer_at

should be in the format YYYY-MM-DD. Attribute to choose when a payment will leave the customer's account.

Response

Returns a bill object.

POST https://gocardless.com/api/v1/bills HTTP/1.1
{
  "bill": {
    "amount":"10.00",
    "pre_authorization_id": "UQSTF7AMQMYWBL"
  }
}

HTTP/1.1 Created
{
  "amount": "10.00",
  "gocardless_fees": "0.10",
  "partner_fees": "0",
  "currency": "GBP",
  "created_at": "2011-11-22T11:59:12Z",
  "description": null,
  "id": "PWSDXRYSCOKA7Z",
  "name": null,
  "status": "pending",
  "merchant_id": "6UFY9IJWGYBTAP",
  "user_id": "BWJ2GP659OXPAU",
  "paid_at": null,
  "source_type": "pre_authorization",
  "source_id": "UQSTF7AMQMYWBL",
  "uri": "https://gocardless.com/api/v1/bills/PWSDXRYSCOKA7Z",
  "can_be_retried": false,
  "payout_id": null,
  "is_setup_fee": false,
  "charge_customer_at": null
}

List all pre-auths

Request params

id

required id of merchant

Response

Returns an array of pre-authorization objects

GET https://gocardless.com/api/v1/merchants/{MERCHANT_ID}/pre_authorizations HTTP/1.1

HTTP/1.1 200 OK
[
  {
    "created_at":"2011-02-18T15:25:58Z",
    "currency":"GBP",
    "name":"Variable Payments For Tennis Court Rental",
    "description":"You will be charged according to your monthly usage of the tennis courts",
    "expires_at":null,
    "id": "1234JKH8KLJ",
    "interval_length":1,
    "interval_unit":"month",
    "merchant_id": "06Z06JWQW1",
    "status":"active",
    "remaining_amount": "65.0",
    "next_interval_start": "2012-02-20T00:00:00Z",
    "user_id": "834JUH8KLJ",
    "max_amount":"70.0",
    "uri":"https://gocardless.com/api/v1/pre_authorizations/1609",
    "sub_resource_uris":{
       "bills":"https://gocardless.com/api/v1/merchants/06Z06JWQW1/bills?source_id=1609"
    }
  }
]

Retrieve an existing pre-auth

Request params

id

required id of pre-authorization to retrieve

Response

Returns a pre-authorization object

next_interval_start indicates when the next interval starts for the pre-authorization. If there will be no next interval because the pre-authorization expires then we will return a null value.

GET https://gocardless.com/api/v1/pre_authorizations/{PRE_AUTH_ID} HTTP/1.1

HTTP/1.1 200 OK
{
  "created_at":"2011-02-18T15:25:58Z",
  "currency":"GBP",
  "name":"Variable Payments For Tennis Court Rental",
  "description":"You will be charged according to your monthly usage of the tennis courts",
  "expires_at":null,
  "id": "1234JKH8KLJ",
  "interval_length":1,
  "interval_unit":"month",
  "merchant_id": "06Z06JWQW1",
  "status":"active",
  "remaining_amount": "65.0",
  "next_interval_start": "2012-02-20T00:00:00Z",
  "user_id": "834JUH8KLJ",
  "max_amount":"70.0",
  "uri":"https://gocardless.com/api/v1/pre_authorizations/1609",
  "sub_resource_uris":{
     "bills":"https://gocardless.com/api/v1/merchants/06Z06JWQW1/bills?source_id=1609"
  }
}

Cancel a pre-auth

Updates status to cancelled. You will no longer be able to create bills under this pre-authorization. This will trigger an email to the customer explaining that the pre-authorization has been cancelled.

Request params

id

required id of pre-authorization to cancel

Response

Returns a pre-authorization object

PUT https://gocardless.com/api/v1/pre_authorizations/{PRE_AUTH_ID}/cancel HTTP/1.1

HTTP/1.1 200 OK
{
  "created_at":"2011-02-18T15:25:58Z",
  "currency":"GBP",
  "name":"Variable Payments For Tennis Court Rental",
  "description":"You will be charged according to your monthly usage of the tennis courts",
  "expires_at":null,
  "id": "1234JKH8KLJ",
  "interval_length":1,
  "interval_unit":"month",
  "merchant_id": "06Z06JWQW1",
  "status":"cancelled",
  "remaining_amount": "65.0",
  "next_interval_start": "2012-02-20T00:00:00Z",
  "user_id": "834JUH8KLJ",
  "max_amount":"70.0",
  "uri":"https://gocardless.com/api/v1/pre_authorizations/1609",
  "sub_resource_uris":{
     "bills":"https://gocardless.com/api/v1/merchants/06Z06JWQW1/bills?source_id=1609"
  }
}

Statuses

inactive

A pre-authorization that has not been confirmed at the end of the Connect flow. It will be deleted from the database after a few hours.

active

A valid pre-authorization. The merchant can now create bills under this pre-authorization.

cancelled

Pre-authorization been terminated. No more bills can be created.

expired

Pre-authorization reached its expiration date. No more bills can be created.

Subscription

A subscription is a recurring Direct Debit for a fixed amount (e.g. £10.00 every month). Once a user has authorized a subscription, it will continue until expires_at.

Create a subscription

A user pays a fixed amount to a merchant each fixed interval of time, until an expiry date e.g. £50 every month.

Request params

subscription [amount]

required amount to collect at each interval_unit.

subscription [interval_length]

required The number of interval_units between payments.

subscription [interval_unit]

required The unit of measurement for the interval. Can be day, week or month.

subscription [name]

Brief description used to identify the payment, displayed to the user alongside the amount. Often useful for an invoice reference.

subscription [description]

A more detailed description, which will be displayed to the user.

subscription [user]

Allows pre-population of user information - see pre-populating information

subscription [start_at]

The date the first bill will be created on. If you don't provide a start_at, it will result in a bill being created immediately after the subscription is confirmed. Note that it needs to be in the future and be before the expires_at if provided. Should be ISO8601 format.

subscription [expires_at]

Date the subscription expires. Note that subscriptions will expire at 00:00 (UTC) of the expiry date (ie the very start of the day). GoCardless won't create any new bills on the expiration day. Should be ISO8601 format.

subscription [interval_count]

Calculates the expires_at date based on the number of payments that you would like to collect from the subscription. Must be a positive integer greater than 0. Also if you specify an interval_count and a expires_at date, the later takes precedence. For example if the subscription is created on the 14th of February and has an 1 week intervals and an interval_count of 2 then the expires_at will be set for the 28th of February. The two payments will be one at creation on the 14th and the other on the 21st.

subscription [setup_fee]

A one-off amount to add to the beginning of the subscription. For example, adding a £25.00 setup fee to a £5 per month subscription would mean that the customer is charged £30 at sign up, and then £5 per month.

signature

required Generated from the request prams according to the signature guide

nonce

required A random string to ensure the uniqueness of each request. This prevents multiple customers using the same link to access the payments process. The nonce is stored for a period of 3 hours, after which it may be re-used. We recommend a random base64-encoded string, but any non-nil value may be used.

client_id

required Your app's identifier/app ID

timestamp

required UTC date and time in ISO 8601 format, e.g. 2011-01-01T12:00:00Z. The request must hit our server within 3 hours of this timestamp, otherwise it will be rejected.

redirect_uri

Where the user should be returned to after the authorization process. If it is not provided, the redirect_uri registered in the dashboard will be used. The scheme, host and port of a provided redirect_uri must match the URL set for the account.

cancel_uri

Where the user should be returned to if he or she chooses to cancel the connect process before completion. If it is not provided, the cancel_uri registered in the developer panel will be used. Note that the scheme, host and port of a provided cancel_uri must match those of the registered one. A cancel_uri can only be provided in the request if one is also set on the account.

state

This allows you to pass a value of your choice through the payment process, receiving it in the redirect page. If present, it will be passed back as a parameter when the user is returned to the merchant's site at the end of an authorization process. If a merchant's site passes in state="id_9SX5G36", it will receive back state="id_9SX5G36" when the user returns to the merchant's site. This state is not persisted in the GoCardless database.

Return value

Returns a link to a subscription mandate.

GET https://gocardless.com/connect/subscriptions/new?client_id=123ABC&timestamp=2014-06-10T08%3A42%3A22Z&nonce=ABCDEF123%3D&subscription[amount]=10.00&subscription[interval_length]=1&subscription[interval_unit]=month&subscription[merchant_id]=06Z06JWQW1&signature=11abc2d3e1 HTTP/1.1

Confirm a new subscription

Redirection of customer after GoCardless payment page

When a user has completed the authorization process, the subscription will exist in an 'inactive' state. The resource must be confirmed within a short period of time otherwise it will be removed from the database.

The user will be redirected (a GET request) back to the redirect URI specified in the developer panel with the following parameters:

resource_uri

The URI at which the new resource may be accessed via the API

resource_id

The unique id of the create resource

resource_type

The type of resource created. In this case "subscription"

signature

A signature of the parameters

state

The state parameter passed in with the initial request if present

Checking the signature

Important - the signature is generated according to the signature guide (also using the merchant's app secret). It should be verified to check that the request has not been tampered with, i.e. - you should re-sign the other 4 params (3 if state is not used) and check that the signature matches the one provided. If it does not match, the request has been tampered with and should be rejected.

Completing the process

A POST should be sent back to GoCardless. You will need to send a Basic Authentication authorization header. The request must be sent with the following parameters:

Request params

resource_id

required the id provided in the initial GET request

resource_type

required the resource type provided in the initial GET request

Response

Returns a success message or an error message

POST https://gocardless.com/api/v1/confirm HTTP/1.1
{
  "resource_id": "0NZ71WBMVF",
  "resource_type": "subscription"
}

HTTP/1.1 200 OK
{
  "success": true
}

List all subscriptions

Request params

id

required id of merchant

Response

Returns an array of subscriptions object.

GET https://gocardless.com/api/v1/merchants/{MERCHANT_ID}/subscriptions HTTP/1.1

HTTP/1.1 200 OK
[
  {
    "amount":"44.0",
    "interval_length":1,
    "interval_unit":"month",
    "created_at":"2011-09-12T13:51:30Z",
    "currency":"GBP",
    "name":"London Gym Membership",
    "description":"Entitles you to use all of the gyms around London",
    "expires_at":null,
    "next_interval_start":"2011-10-12T13:51:30Z",
    "id": "AJKH638A99",
    "merchant_id":"06Z06JWQW1",
    "status":"active",
    "user_id":"HJEH638AJD",
    "uri":"https://gocardless.com/api/v1/subscriptions/1580",
    "sub_resource_uris":{
       "bills":"https://gocardless.com/api/v1/merchants/06Z06JWQW1/bills?source_id=1580"
    }
  }
]

Retrieve an existing subscription

Request params

id

required id of subscription to retrieve

Response

Returns a subscription object.

next_interval_start indicates when does the next interval starts. If there will be no next interval because the subscription expires then we will return a null value.

GET https://gocardless.com/api/v1/subscriptions/{SUBSCRIPTION_ID} HTTP/1.1

HTTP/1.1 200 OK
{
  "amount":"44.0",
  "interval_length":1,
  "interval_unit":"month",
  "created_at":"2011-09-12T13:51:30Z",
  "currency":"GBP",
  "name":"London Gym Membership",
  "description":"Entitles you to use all of the gyms around London",
  "expires_at":null,
  "next_interval_start":"2011-10-12T13:51:30Z",
  "id": "AJKH638A99",
  "merchant_id":"06Z06JWQW1",
  "status":"active",
  "user_id":"HJEH638AJD",
  "uri":"https://gocardless.com/api/v1/subscriptions/1580",
  "sub_resource_uris":{
     "bills":"https://gocardless.com/api/v1/merchants/06Z06JWQW1/bills?source_id=1580"
  }
}

Cancel a subscription

Updates status to cancelled.

Bills will no longer be created for the subscription, effective immediately. This will trigger an email to the customer explaining that the subscription has been cancelled.

Request params

id

required id of subscription to cancel

Response

Returns a subscription object

PUT https://gocardless.com/api/v1/subscriptions/{SUBSCRIPTION_ID}/cancel HTTP/1.1

HTTP/1.1 200 OK
{
  "amount":"44.0",
  "interval_length":1,
  "interval_unit":"month",
  "created_at":"2011-09-12T13:51:30Z",
  "currency":"GBP",
  "name":"London Gym Membership",
  "description":"Entitles you to use all of the gyms around London",
  "expires_at":null,
  "next_interval_start":"2011-10-12T13:51:30Z",
  "id": "AJKH638A99",
  "merchant_id":"06Z06JWQW1",
  "status":"cancelled",
  "user_id":"HJEH638AJD",
  "uri":"https://gocardless.com/api/v1/subscriptions/1580",
  "sub_resource_uris":{
     "bills":"https://gocardless.com/api/v1/merchants/06Z06JWQW1/bills?source_id=1580"
  }
}

Statuses

inactive

A subscription that has not been confirmed at the end of the Connect flow. It will be deleted from the database after a few hours.

active

A subscription that has not yet expired or been cancelled. Bills will automatically be created by GoCardless according to the interval (e.g. monthly).

cancelled

A subscription that has been terminated by the customer or merchant. No more bills will be created.

expired

A subscription that has reached its expiration date. No more bills will be created.

User

Represents a user that has a bill, subscription or pre-authorization with the merchant.

List all users

Request params

id

required id of merchant

Response

Returns an array of customers for the given merchant (any user with a subscription, pre-authorization or bill).

GET https://gocardless.com/api/v1/merchants/{MERCHANT_ID}/users HTTP/1.1

HTTP/1.1 200 OK
[
  {
    "created_at":"2011-11-18T17:06:15Z",
    "email":"customer40@gocardless.com",
    "id": "JKH8HGKL9H",
    "first_name":"Frank",
    "last_name":"Smith"
  },
  {
    "created_at":"2011-11-19T14:16:15Z",
    "email":"customer41@gocardless.com",
    "id":"JKH8HGKL9I",
    "first_name":"James",
    "last_name":"Dean"
  }
]