Overview

This is the documentation for the GoCardless API.

If you’re just exploring or want to start building an integration, check out our getting started guide for a step-by-step introduction with PHP, Ruby, Java, and Python code samples

If you’re using the Legacy GoCardless API, you can find documentation here.

For testing purposes we recommend you sign up for a sandbox account.

Supported Direct Debit Schemes

The GoCardless API currently supports the following Direct Debit schemes:

Scheme Countries
Bacs United Kingdom
SEPA Core*
Åland Islands
Austria
Belgium
Cyprus
Estonia
Finland
France
French Guiana
Germany
Greece
Guadeloupe
Ireland
Italy
Latvia
Lithuania
Luxembourg
Malta
Martinique
Mayotte
Monaco
Netherlands
Portugal
Réunion
San Marino
Slovakia
Slovenia
Spain
Saint Barthélemy
Saint Martin
Saint Pierre and Miquelon
Autogiro
Sweden

Note: There are practical issues with SEPA Direct Debit in some countries that mean we would not recommend using it to collect payments from end customers in those markets. Local implementation can cause problems in the Baltic states in particular - please contact us for more information.

* Collection from all non-Eurozone SEPA countries is also supported through the API, but since only a small percentage of bank accounts in these countries are reachable they have not been listed above.

Beta: support for Autogiro is currently in beta. We may not respect the usual backwards compatibility practices and it may be less reliable than our Bacs and SEPA Direct Debit systems. Please contact us if you have any issues.

Support for the following schemes is coming soon:

  • Direct Entry (Australia)
  • ACH Debit (United States)
  • AvtaleGiro (Norway)
  • BECS (New Zealand)
  • SEPA B2B

Getting started

There are three key parts to an integration with the API - you can do one, two or all three of them:

  • Setting up mandates with your customers’ bank accounts
  • Collecting payments against your mandates
  • Staying up-to-date with webhooks

To get started with the API, check out our “getting started” guide, with copy and paste code samples in PHP, Ruby and Python guiding you through your integration from start to finish.

Restrictions

Whilst the entire GoCardless API is accessible in the sandbox environment, the following restrictions exist in live.

Payment page restrictions

Unless your payment pages have been approved as scheme rules compliant by our sponsor bank you must use the Redirect Flow API to create customers, bank accounts and mandates.

The following endpoints are therefore restricted:

  • Customers: Create
  • Customer bank accounts: Create
  • Mandate: Create, Reinstate
  • Javascript flow: All endpoints

Please get in touch to discuss having your payment pages approved.

Creditor management restrictions

Unless your account has been approved as a whitelabel partner you may only collect payments on behalf of a single creditor. The following endpoints are therefore restricted:

  • Creditors: Create

Please get in touch if you’re interested in making use of these endpoints in your integration.

Anatomy

The following state diagrams explain the flows of mandate setup to setup customers on a Direct Debit and payment creation, to collect payment against said mandate. There’s also a short section on how timings work.

Mandate setup

Mandate setup flow

Payment creation

Payment creation flow

How timings work

Direct debit payments don’t process instantly, and work differently to card payments.

For the UK:

  • If a Direct Debit mandate is already in place, payment is collected 2 working days after submission, can be considered 95% confirmed 3 working days after submission, and 100% confirmed after 4 working days.
  • If a Direct Debit mandate needs to be created, payment is collected 4 working days after submission, can be considered 95% confirmed 5 working days after submission, and 100% confirmed after 6 working days.

There’s also a requirement to notify your customers 3 working days before payment leaves their account. See the notifications section for more detail.

For more information on UK timings, see our detailed guide.

For SEPA Core:

  • For all payment collections, you must submit the collection to the banks 3 interbank business days before the payment due date.

You will need to notify your customers between 14 and 3 calendar days in advance of the payment being collected.

For more information on SEPA timings, see our detailed guide.

For Autogiro:

  • New mandates take up to 6 interbank business days before payments can be submitted under them.
  • For all payment collections, you must submit the collection to the banks 2 interbank business days before the payment due date.

You will need to notify your customers at least 8 working days in advance of the payment being collected.

For more information on Autogiro timings, see our Bg Autogiro guide.

In all cases, you can still test these as if they were instant - for more detail, see the section on testing your integration.

Backwards compatibility

The following changes are considered backwards compatible:

  • Adding new API endpoints
  • Adding new properties to the responses from existing API endpoints
  • Reordering properties returned from existing API endpoints
  • Adding optional request parameters to existing API endpoints
  • Altering the format or length of IDs
    • These strings will never exceed 255 characters, but you should be able to handle anything up to that length
  • Altering the message attributes returned by validation failures / other errors
  • Sending webhooks for new event types

Changelog

20th February 2017
Added scheme_identifiers to the creditors API.
2nd February 2017
Added new event for mandate replaced action.
2nd August 2016
Added deducted_fees to the payouts API.
7th July 2016
Added payments_require_approval to the mandates API.
11th February 2016
Added arrival_date to the payouts API.
21st January 2016
Restricted specifying payment references on Bacs payments to only those organisations using their own Service User Number.
6th January 2016
Added filtering by created_at to the customer bank accounts API.
20th October 2015
Added filtering by created_at to the mandates API.
16th October 2015
Added filtering by created_at to the payouts API.
30th September 2015
Added support for app fees to the OAuth API, in beta.
29th September 2015
Added support for Autogiro, the Direct Debit scheme in Sweden, in beta.
16th September 2015
Added request_pointer field to validation errors, in the form of JSON pointer. See validation errors for more details.
10th September 2015
Added reference to the refund API. This sets a reference which will appear with the refund on the customer’s bank statement.
17th August 2015
Added language to the customer API. This sets the language of notification emails sent by GoCardless to the customer. Defaults to the native language of the customer’s country.
2nd August 2015
Added support for SEPA COR1, a faster version of SEPA Direct Debit available in Spain, Germany and Austria. COR1 will be used automatically if possible when creating new SEPA mandates, unless you specify the scheme attribute explicitly. The returned scheme attribute will be sepa_cor1.
29th July 2015
Added customer_bank_account and customer to the complete redirect flow endpoint returned properties.
23rd July 2015
Removed support for API version 2014-11-03.
22nd July 2015
Added bic to the bank details lookups endpoint returned properties.
6th July 2015
Released API version 2015-07-06. See blog post for more details and upgrade guide.
  • Removes Helpers endpoint from the API

  • Renames start_at and end_at on subscriptions to start_date and end_date

  • Enforces date format (not datetime) for payment charge_date

2nd July 2015
Renamed the beta modulus checks endpoint to bank details lookups and took it out of beta.
30th June 2015
Added mandate PDFs endpoint, which will replace the previous mandate helper endpoint and the ability to request a PDF from the “get a single mandate” endpoint in a future version.
26th June 2015
Added top level modulus checks endpoint, which will replace the previous modulus check helper endpoint in a future version.
15th June 2015
Updated MIME type negotiation to 406 if a bad Accept header is provided.
9th June 2015
Added new events for payment created, subscription created, and refund paid.
29th April 2015
Released API version 2015-04-29. See blog post for more details and upgrade guide.
  • Removes Roles and Users from the API

  • Replaces Api Keys with Access Tokens

  • Replaces Publishable Api Keys with Publishable Access Tokens

  • Removes explicit sort_code field from bank account creation APIs in favour of local details

  • Removes Webhook-Key-Id header from webhooks we send

API Usage

Making requests

Base URLs

The base URLs for the GoCardless API are - https://api.gocardless.com/ for live - https://api-sandbox.gocardless.com/ for sandbox

The API is only available over HTTPS. Attempting to access the API over an unsecured HTTP connection will return a tls_required error.

Authentication

After creating an access token in the dashboard, you must provide it in an Authorization request header (using the bearer authentication scheme) when making API requests.

Authorization: Bearer TOP_SECRET_ACCESS_TOKEN

Versions

Every request must specify a GoCardless-Version header, with a released API version.

GoCardless-Version: 2015-07-06

Currently available versions:

2015-07-06
Removed helper endpoint (replaced with new individual endpoints).

Historic versions which are no longer available:

2015-04-29
Changed auth and removed sort_code.
2014-11-03
Changed validations on charge_customer_at.
2014-10-03
Enforced validation of keys passed to all endpoints.
2014-09-01
First Pro API release.

MIME Types

All requests and responses are JSON-formatted and UTF-8 encoded. Providing the Accept header is optional, but recommended. The Content-Type header must be provided when sending data to the API (using POST and PUT endpoints). You may pass either the standard JSON MIME type (application/json), or the JSON-API variant (application/vnd.api+json). You will receive an invalid_content_type error if you attempt to make a POST/PUT request without one of these MIME types.

PUT, PATCH and DELETE

If your HTTP client or proxy doesn’t support PUT or DELETE, you can instead make a POST request with the header X-HTTP-Method-Override: PUT or X-HTTP-Method-Override: DELETE.

The HTTP PATCH verb is not allowed by the API, and will result in a method_not_allowed error. Please use PUT to alter an existing resource.

Rate Limiting

All endpoints are rate limited.

You can check the returned HTTP headers of any API request to see your current rate limit status, for example:

RateLimit-Limit: 837
RateLimit-Remaining: 1993
RateLimit-Reset: Thu, 01 May 2014 16:00:00 GMT

RateLimit-Reset uses the HTTP header date format as specified by RFC 1123 (Thu, 01 Dec 1994 16:00:00 GMT).

Exceeding the rate limit results in a rate_limit_exceeded error.

Idempotency Keys

Some requests are dangerous to make twice. With these requests, a badly timed error can prevent the client from receiving a response from us that specifies if creation has been successful. In a situation like submitting payments, if the request gets retried then a payment could be taken twice. This is clearly undesirable.

Creation routes on our API support idempotent creation. By making the request with an Idempotency-Key header, we can invalidate the given key for future creations if the original create has been persisted. This means there is no danger in retrying a creation request so long as the same idempotency key is supplied both times.

Any requests to create a resource with a key that has previously been used will not succeed, and will respond with a 409 idempotent_creation_conflict error.

Idempotency keys are intended to prevent conflicts over short periods of time, and will not be persisted indefinitely.

Time zones / dates

All timestamps are formatted as ISO8601 with timezone information. For API calls that allow for a timestamp to be specified, we use that exact timestamp. These timestamps look something like 2014-02-27T15:05:06.123Z.

For endpoints that require dates, we expect a date string of the format YYYY-MM-DD, where an example would look like 2014-02-27.

Cursor Pagination

All list/index endpoints are ordered and paginated reverse chronologically by default.

Options

The following options are available on all cursor-paginated endpoints:

before
ID of the object immediately following the array of objects to be returned.
after
ID of the object immediately preceding the array of objects to be returned.
limit
Upper bound for the number of objects to be returned. Defaults to 50. Maximum of 500.

Response

Paginated results are always returned in an array, and include the following meta data:

before
The ID of the first resource that has been returned.
after
The ID of the last resource that has been returned.
limit
The upper bound placed on the number of objects returned. If there were not enough remaining objects in the list of data then fewer than this number will have been returned.
GET https://api.gocardless.com/resources?after=ID789 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "after": "ID456",
      "before": "ID123"
    },
    "limit": 50
  },
  "resources": [{
    ...
  }]
}

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
OK. The request has succeeded.
201
Created. The request has been fulfilled and resulted in a new resource being created. The newly created 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.
204
No Content. The request was successful but no body was returned.
400
Bad Request. 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 or the user making the request has been disabled.
403
Forbidden. The client has provided a valid Authentication header, but does not have permission to access this resource.
404
Not Found. The requested resource was not found or the authenticated user cannot access the resource. The response body will explain which resource was not found.
405
Method Not Allowed. The HTTP verb used, or resource requested is not allowed. Note that we do not allow the PATCH verb to be used, and PUT should be used instead.
406
Not Acceptable. The content type specified in the Accept header was not acceptable to this endpoint.
409
Conflict. The resource to be created by your request already exists.
415
Unsupported Media Type. The response error will explain what types are accepted.
422
Unprocessable Entity. Could not process a POST or PUT request because the request is invalid. The response body will contain more details.
426
Upgrade Required. An unsecured connection was refused. Upgrade to TLS/SSL.
429
Too Many Requests. A rate limit has been reached. The headers will explain the details of the rate limit.
500
Internal Server Error. The server encountered an error while processing your request and failed. Please report this to the GoCardless support team and quote the request_id.

Scenario simulators

When you’re building an integration with the API, there are some common paths you should make sure your integration handles successfully, for example a customer cancelling their mandate or a payment failing due to lack of funds.

In the sandbox environment, we provide scenario simulators: special customer names that trigger these sequences of events almost instantly. For example, if you create a customer with the given_name “Successful”, their payments will succeed immediately.

For a list of all the simulators available, see our guide.

Errors

Every error includes a type, the HTTP status code, a short message, a documentation_url, linking to the relevant section of this document, and a unique request_id which can be used to help the GoCardless support team find your error quickly.

There is also an errors key which is an array listing any errors that have been raised in one of two formats.

When the type is validation_failed, each error will be composed of a field and a message describing what is wrong with that field.

For all other errors, the structure will contain a reason and a message describing what the problem encountered.

There are 4 types of errors, depending on the root cause. These are:

Error types

gocardless
An internal error occurred while processing your request. This should be reported to our support team with the id, so we can resolve the issue.
invalid_api_usage
This is an error with the request you made. It could be an invalid URL, the authentication header could be missing, invalid, or grant insufficient permissions, you may have reached your rate limit, or the syntax of your request could be incorrect. The errors will give more detail of the specific issue.
invalid_state
The action you are trying to perform is invalid due to the state of the resource you are requesting it on. For example, a payment you are trying to cancel might already have been submitted. The errors will give more details.

validation_failed
The parameters submitted with your request were invalid. Details of which fields were invalid and why are included in the response. The request_pointer parameter indicates the exact field of the request that triggered the validation error.

These four types should be handled very differently: gocardless errors should send an alert to your dev team, or directly to GoCardless support; invalid_api_usage should send an alert to your dev team; invalid_state should alert the end user and not allow them to retry; validation_failed should alert the end user and prompt them to correct their input.

Invalid API usage errors

The errors key may also hold an array of type errors if the JSON you sent was incorrectly typed. These are in the same format as validation errors (with a message and field per error). A type error will also be returned if you include any additional, unknown parameters.

path_not_found
The path was not recognised. Check that you spelled the resource name correctly, and that the URL is formatted correctly.

resource_not_found
The ID in the request was not found in our database.

link_not_found
One of the link[resource] IDs in the request was not found. Your integration should ensure that end users can only use existing resources.
unauthorized
Your username/password was not recognised.
forbidden
You were authenticated, but you do not have permission to access that resource.

feature_disabled
You are trying to use a feature which hasn’t been enabled on your account. Please contact support if you would like to enable it.

not_acceptable
The content type specified in your Accept header was not acceptable to this endpoint.

request_entity_too_large
The body of your request is too large.
unsupported_media_type
The API communicates using JSON only. Make sure that your Accept header permits JSON, and your Content-Type header is supported, if you are sending JSON data (e.g. with a POST or PUT request).
rate_limit_exceeded
You have exceeded the rate limit. See the included headers for when your rate limit will be reset.
access_token_not_found
No access token with the ID specified was found.
access_token_not_active
The access token you are using has been disabled.
missing_authorization_header
No Authorization header was included in your request. See making requests for details on how to structure your authorisation header.
invalid_authorization_header
The Authorization header sent was not valid. Make sure it was constructed as described in making requests.
insufficient_permissions
The access token you are using does not have the right scope to perform the requested action.
method_not_allowed
The HTTP verb used is not permitted. Note that we do not allow PATCH requests, and PUT must be used to update resources.
bad_request
The request syntax was incorrect.
idempotency_key_too_long
An idempotency key was supplied for this request but exceeded the max length of this key. See idempotency keys for details on how to work with idempotency.

invalid_document_structure
The JSON sent to the server was not in the correct structure. Note that JSON parameters may not be sent at the top level, but must be sent under the name of the resource. See the examples for details on how this is done for each endpoint.
invalid_content_type
When including a JSON body with a request you must also include a Content-Type header, set to application/json or application/vnd.api+json.
tls_required
The GoCardless API can only be accessed over TLS/SSL. Make sure you are sending requests to urls starting with https://, not http://.
missing_version_header
No GoCardless-Version header was included in your request. See making requests for details on how to set your version header.
version_not_found
The GoCardless-Version specified was not found. The version must be one of those listed in the changelog.

invalid_filters
The combination of filters specified in the query string of your request are not allowed. Only certain combinations of filters may be applied to each list endpoint, as documented on each endpoint.

Invalid state errors

cancellation_failed
The mandate, payment or subscription was not in a cancellable state. It might have already been cancelled, failed, or it might be too late in the submission process to cancel. For example, payments cannot be cancelled once they are submitted to the banks.
retry_failed
The payment could not be retried.

disable_failed
The customer or creditor bank account could not be disabled, as it is already disabled.
mandate_is_inactive
The payment could not be created, because the mandate linked is cancelled, failed, or expired.

mandate_replaced
The resource could not be created, because the mandate it links to has been replaced (for example, because the creditor has moved to a new Service User Number). The new mandate can be found through the reference to links[new_mandate] in the error response, or by retrieving the original mandate and checking links[new_mandate].

bank_account_disabled
The mandate could not be created because the customer bank account linked is disabled.
mandate_not_inactive
The mandate could not be reinstated, because it is already being submitted, or is active.
refund_payment_invalid_state
The refund could not be created, because the payment specified is not confirmed or paid_out.
total_amount_confirmation_invalid
The refund could not be created because the total amount refunded does not match.
number_of_refunds_exceeded
The refund could not be created because five refunds have already been created for the given payment.
idempotent_creation_conflict
The resource has not been created as a resource has already been created with the supplied idempotency key. See idempotency keys for details.

customer_bank_account_token_used
The customer bank account could not be created because the token given has already been used.

Validation errors

The errors key may also hold an array of individual validation failures in this case, or one of the following errors.

bank_account_exists
The customer or creditor bank account you are trying to create already exists. These resources must be unique.

You should use the corresponding update endpoints to update the details on the existing bank account instead, which will be referenced as links[customer_bank_account] or links[creditor_bank_account] (as appropriate) in the error response.
POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
{
  "customer_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "I'm not a sort code",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "links": {
      "customer": "CU123"
    }
  }
}

HTTP/1.1 422 (Unprocessable Entity)
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/#validation_failed",
    "message": "Validation failed",
    "type": "validation_failed",
    "code": 422,
    "request_id": "dd50eaaf-8213-48fe-90d6-5466872efbc4",
    "errors": [
      {
        "message": "must be a number",
        "field": "branch_code",
        "request_pointer": "/customer_bank_accounts/branch_code"
      }, {
        "message": "is the wrong length (should be 8 characters)",
        "field": "branch_code",
        "request_pointer": "/customer_bank_accounts/branch_code"
      }
    ]
  }
}

POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
{
  "customer_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "links": {
      "customer": "CU123"
    }
  }
}

HTTP/1.1 400 (Bad Request)
{
  "error": {
    "message": "Invalid document structure",
    "documentation_url": "https://developer.gocardless.com/#invalid_document_structure",
    "type": "invalid_api_usage",
    "request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
    "code": 400,
    "errors": [
      {
        "reason": "invalid_document_structure",
        "message": "Invalid document structure"
      }
    ]
  }
}

POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
{
  "creditor_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB",
    "set_as_default_payout_account": true,
    "account_holder_name": "Nude Wines",
    "links": {
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 409 (Conflict)
{
  "error": {
    "message": "Bank account already exists",
    "documentation_url": "https://developer.gocardless.com/#bank_account_exists",
    "type": "validation_failed",
    "request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
    "code": 409,
    "errors": [
      {
        "reason": "bank_account_exists",
        "message": "Bank account already exists",
        "links": {
          "creditor_bank_account": "BA123"
        }
      }
    ]
  }
}

Core Endpoints

Creditors

Each payment taken through the API is linked to a “creditor”, to whom the payment is then paid out. In most cases your organisation will have a single “creditor”, but the API also supports collecting payments on behalf of others.

Please get in touch if you wish to use this endpoint. Currently, for Anti Money Laundering reasons, any creditors you add must be directly related to your organisation.

Properties

id
Unique identifier, beginning with “CR”.
address_line1
The first line of the creditor’s address.
address_line2
The second line of the creditor’s address.
address_line3
The third line of the creditor’s address.
city
The city of the creditor’s address.
country_code
ISO 3166-1 alpha-2 code.
created_at
Fixed timestamp, recording when this resource was created.
logo_url
URL for the creditor’s logo, which may be shown on their payment pages.
name
The creditor’s name.
postal_code
The creditor’s postal code.
region
The creditor’s address region, county or department.
scheme_identifiers
An array of the scheme identifiers this creditor can create mandates against.

The support address, phone_number and email fields are for customers to contact the merchant for support purposes. They must be displayed on the payment page, please see our compliance requirements for more details.

Each instance will contain these properties:

  • address_line1: The first line of the support address.

  • address_line2: The second line of the support address.

  • address_line3: The third line of the support address.

  • can_specify_mandate_reference: Whether a custom reference can be submitted for mandates using this scheme identifier.

  • city: The city of the support address.

  • country_code: The support ISO 3166-1 country code.

  • currency: The currency of the scheme identifier.

  • email: The support email address.

  • minimum_advance_notice: The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.

    By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.

  • name: The name which appears on customers’ bank statements.

  • phone_number: The support phone number.

  • postal_code: The support postal code.

  • reference: The scheme-unique identifier against which payments are submitted.

  • region: The support address region, county or department.

  • scheme: The scheme which this scheme identifier applies to.

links[default_eur_payout_account]
ID of the bank account which is set up to receive payouts in EUR.
links[default_gbp_payout_account]
ID of the bank account which is set up to receive payouts in GBP.
links[default_sek_payout_account]
ID of the bank account which is set up to receive payouts in SEK.

Create a creditor

Creates a new creditor.

Relative endpoint: POST /creditors

Restricted: this endpoint is restricted to accounts which have been approved as whitelabel partners. Please contact support if you’re interested in managing multiple creditors.

Parameters

address_line1
The first line of the creditor’s address.
address_line2
The second line of the creditor’s address.
address_line3
The third line of the creditor’s address.
city
The city of the creditor’s address.
country_code
ISO 3166-1 alpha-2 code.
name
required The creditor’s name.
postal_code
The creditor’s postal code.
region
The creditor’s address region, county or department.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditors()->create([
  "params" => ["name" => "The Wine Club",
               "address_line1" => "9 Acer Gardens",
               "city" => "Birmingham",
               "postal_code" => "B4 7NJ",
               "country_code" => "GB"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditors.create(params={
  "name": "The Wine Club",
  "address_line1": "9 Acer Gardens",
  "city": "Birmingham",
  "postal_code": "B4 7NJ",
  "country_code": "GB"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditors.create(
  params: {
    name: "Example Ltd",
    address_line1: "338 Goswell Road",
    city: "London",
    postal_code: "EC1V 7LQ",
    country_code: "GB"
  }
)



POST https://api.gocardless.com/creditors HTTP/1.1
{
  "creditors": {
    "name": "The Cheese Club",
    "address_line1": "123 Street",
    "city": "London",
    "postal_code": "E2 8DP",
    "country_code": "GB"
  }
}

HTTP/1.1 201 (Created)
Location: /creditors/CR123
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "The Cheese Club",
    "address_line1": "123 Street",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E2 8DP",
    "country_code": "GB",
    "logo_url": null,
    "scheme_identifiers": [
      {
        "name": "GoCardless",
        "scheme": "bacs",
        "reference": "420042",
        "minimum_advance_notice": 3,
        "currency": "GBP",
        "address_line1": "338 Goswell Road",
        "address_line2": null,
        "address_line3": null,
        "city": "London",
        "region": null,
        "postal_code": "EC1V 7LQ",
        "country_code": "GB",
        "email": "[email protected]",
        "phone_number": "+44 20 7183 8674",
        "can_specify_mandate_reference": false
      }
    ],
    "links": {
    }
  }
}

List creditors

Returns a cursor-paginated list of your creditors.

Relative endpoint: GET /creditors

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
limit
Number of records to return.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditors()->list();

$client->creditors()->list([
  "params" => ["created_at[gt]" => "2014-05-08T17:01:06.000Z"]
])



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditors.list().records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditors.list

@client.creditors.list(params: { limit: 2 })



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Creditor creditor : client.creditors().all().execute()) {
  System.out.println(creditor.getId());
}


GET https://api.gocardless.com/creditors HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": "CR123",
    },
    "limit": 50
  },
  "creditors":[{
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "The Cheese Club",
    "address_line1": "123 Street",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E2 8DP",
    "country_code": "GB",
    "logo_url": null,
    "scheme_identifiers": [
      {
        "name": "GoCardless",
        "scheme": "bacs",
        "reference": "420042",
        "minimum_advance_notice": 3,
        "currency": "GBP",
        "address_line1": "338 Goswell Road",
        "address_line2": null,
        "address_line3": null,
        "city": "London",
        "region": null,
        "postal_code": "EC1V 7LQ",
        "country_code": "GB",
        "email": "[email protected]",
        "phone_number": "+44 20 7183 8674",
        "can_specify_mandate_reference": false
      }
    ],
    "links": {
      "default_gbp_payout_account": "BA123",
      "default_eur_payout_account": "BA456"
    }
  }, {
  ...
  }]
}

Get a single creditor

Retrieves the details of an existing creditor.

Relative endpoint: GET /creditors/CR123

Parameters


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditors()->get("CR123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditors.get("CR123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditors.get("CR123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Creditor creditor = client.creditors().get("CR123").execute();


GET https://api.gocardless.com/creditors/CR123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "The Cheese Club",
    "address_line1": "123 Street",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E2 8DP",
    "country_code": "GB",
    "logo_url": null,
    "scheme_identifiers": [
      {
        "name": "GoCardless",
        "scheme": "bacs",
        "reference": "420042",
        "minimum_advance_notice": 3,
        "currency": "GBP",
        "address_line1": "338 Goswell Road",
        "address_line2": null,
        "address_line3": null,
        "city": "London",
        "region": null,
        "postal_code": "EC1V 7LQ",
        "country_code": "GB",
        "email": "[email protected]",
        "phone_number": "+44 20 7183 8674",
        "can_specify_mandate_reference": false
      }
    ],
    "links": {
      "default_gbp_payout_account": "BA123",
      "default_eur_payout_account": "BA456"
    }
  }
}

Update a creditor

Updates a creditor object. Supports all of the fields supported when creating a creditor.

Relative endpoint: PUT /creditors/CR123

Parameters

address_line1
The first line of the creditor’s address.
address_line2
The second line of the creditor’s address.
address_line3
The third line of the creditor’s address.
city
The city of the creditor’s address.
country_code
ISO 3166-1 alpha-2 code.
name
The creditor’s name.
postal_code
The creditor’s postal code.
region
The creditor’s address region, county or department.
links[default_eur_payout_account]
ID of the bank account which is set up to receive payouts in EUR.
links[default_gbp_payout_account]
ID of the bank account which is set up to receive payouts in GBP.
links[default_sek_payout_account]
ID of the bank account which is set up to receive payouts in SEK.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditors()->update("CR123", [
  "params" => ["name" => "Nude Wines",
               "links" => ["default_gbp_payout_account" => "BA789"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditors.update("CR123", params={
  "name": "Nude Wines",
  "links": {
    "default_gbp_payout_account": "BA789"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditors.update(
  "CR123",
  params: {
    links: { default_gbp_payout_account: "BA123" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.creditors().update("CR123")
  .withName("Nude Wines")
  .withLinksDefaultGbpPayoutAccount("BA789")
  .execute();


PUT https://api.gocardless.com/creditors/CR123 HTTP/1.1
{
  "creditors": {
    "name": "The Wine Club",
    "links": {
      "default_gbp_payout_account": "BA789"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "The Wine Club",
    "address_line1": "123 Street",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E2 8DP",
    "country_code": "GB",
    "logo_url": null,
    "scheme_identifiers": [
      {
        "name": "GoCardless",
        "scheme": "bacs",
        "reference": "420042",
        "minimum_advance_notice": 3,
        "currency": "GBP",
        "address_line1": "338 Goswell Road",
        "address_line2": null,
        "address_line3": null,
        "city": "London",
        "region": null,
        "postal_code": "EC1V 7LQ",
        "country_code": "GB",
        "email": "[email protected]",
        "phone_number": "+44 20 7183 8674",
        "can_specify_mandate_reference": false
      }
    ],
    "links": {
      "default_gbp_payout_account": "BA789",
      "default_eur_payout_account": "BA456"
    }
  }
}

Creditor Bank Accounts

Creditor Bank Accounts hold the bank details of a creditor. These are the bank accounts which your payouts will be sent to.

Note that creditor bank accounts must be unique, and so you will encounter a bank_account_exists error if you try to create a duplicate bank account. You may wish to handle this by updating the existing record instead, the ID of which will be provided as links[creditor_bank_account] in the error response.

Properties

id
Unique identifier, beginning with “BA”.
account_holder_name
Name of the account holder, as known by the bank. Usually this is the same as the name stored with the linked creditor. This field will be transliterated, upcased and truncated to 18 characters.
account_number_ending
Last two digits of account number.
bank_name
Name of bank, taken from the bank details.
country_code
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code, defaults to national currency of country_code.
enabled
Boolean value showing whether the bank account is enabled or disabled.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
links[creditor]
ID of the creditor that owns this bank account.

Create a creditor bank account

Creates a new creditor bank account object.

Relative endpoint: POST /creditor_bank_accounts

Parameters

account_holder_name
required Name of the account holder, as known by the bank. Usually this is the same as the name stored with the linked creditor. This field will be transliterated, upcased and truncated to 18 characters.
account_number
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_code
Bank code - see local details for more information. Alternatively you can provide an iban.
branch_code
Branch code - see local details for more information. Alternatively you can provide an iban.
country_code
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
currency
ISO 4217 currency code, defaults to national currency of country_code.
iban
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for accounts in SEK.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
set_as_default_payout_account
Defaults to false. When this is set to true, it will cause this bank account to be set as the account that GoCardless will pay out to.
links[creditor]
required ID of the creditor that owns this bank account.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditorBankAccounts()->create([
  "params" => ["account_number" => "55779911",
               "branch_code" => "200000",
               "country_code" => "GB",
               "set_as_default_payout_account" => true,
               "account_holder_name" => "Nude Wines",
               "links" => ["creditor" => "CR123"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditor_bank_accounts.create(params={
  "account_number": "55779911",
  "branch_code": "200000",
  "country_code": "GB",
  "set_as_default_payout_account": true,
  "account_holder_name": "Nude Wines",
  "links": {
    "creditor": "CR123"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditor_bank_accounts.create(
  params: {
    account_holder_name: "Example Ltd",
    account_number: "55779911",
    branch_code: "200000",
    country_code: "GB",
    set_as_default_payout_account: true,
    links: {
      creditor: "CR123"
    }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .withSetAsDefaultPayoutAccount(true)
  .withAccountHolderName("Nude Wines")
  .withLinksCreditor("CR123")
  .execute();


POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
{
  "creditor_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB",
    "set_as_default_payout_account": true,
    "account_holder_name": "Nude Wines",
    "links": {
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /creditor_bank_accounts/BA123
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Nude Wines",
    "account_number_ending": "11",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    }
  }
}

List creditor bank accounts

Returns a cursor-paginated list of your creditor bank accounts.

Relative endpoint: GET /creditor_bank_accounts

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
creditor
Unique identifier, beginning with “CR”.
enabled
Get enabled or disabled creditor bank accounts.
limit
Number of records to return.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditorBankAccounts()->list();

$client->creditorBankAccounts()->list([
  "params" => ["enabled" => true]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditor_bank_accounts.list().records

client.creditor_bank_accounts.list(params={"creditor": "CR123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditor_bank_accounts.list

@client.creditor_bank_accounts.list(params: { enabled: true })



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (CreditorBankAccount creditorBankAccount : client.creditorBankAccounts().all().withCreditor("CR123").execute()) {
  System.out.println(creditorBankAccount.getId());
}


GET https://api.gocardless.com/creditor_bank_accounts HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": "BA123",
    },
    "limit": 50
  },
  "creditor_bank_accounts":[{
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Nude Wines",
    "account_number_ending": "11",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    }
  }, {
  ...
  }]
}

Get a single creditor bank account

Retrieves the details of an existing creditor bank account.

Relative endpoint: GET /creditor_bank_accounts/BA123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditorBankAccounts()->get("BA123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditor_bank_accounts.get("BA123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditor_bank_accounts.get("BA123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().get("BA123").execute();


GET https://api.gocardless.com/creditor_bank_accounts/BA123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Nude Wines",
    "account_number_ending": "11",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    }
  }
}

Disable a creditor bank account

Immediately disables the bank account, no money can be paid out to a disabled account.

This will return a disable_failed error if the bank account has already been disabled.

A disabled bank account can be re-enabled by creating a new bank account resource with the same details.

Relative endpoint: POST /creditor_bank_accounts/BA123/actions/disable


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->creditorBankAccounts()->disable("BA123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditor_bank_accounts.disable("BA123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditor_bank_accounts.disable("BA123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.creditorBankAccounts().disable("BA123").execute();


POST https://api.gocardless.com/creditor_bank_accounts/BA123/actions/disable HTTP/1.1

HTTP/1.1 200 (OK)
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Nude Wines",
    "account_number_ending": "11",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": false,
    "links": {
      "creditor": "CR123"
    }
  }
}

Customers

Customer objects hold the contact details for a customer. A customer can have several customer bank accounts, which in turn can have several Direct Debit mandates.

Note: the swedish_identity_number field may only be supplied for Swedish customers, and must be supplied if you intend to set up an Autogiro mandate with the customer.

Properties

id
Unique identifier, beginning with “CU”.
address_line1
The first line of the customer’s address.
address_line2
The second line of the customer’s address.
address_line3
The third line of the customer’s address.
city
The city of the customer’s address.
company_name
Customer’s company name. Required unless a given_name and family_name are provided.
country_code
ISO 3166-1 alpha-2 code.
created_at
Fixed timestamp, recording when this resource was created.
email
Customer’s email address.
family_name
Customer’s surname. Required unless a company_name is provided.
given_name
Customer’s first name. Required unless a company_name is provided.
language
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
postal_code
The customer’s postal code.
region
The customer’s address region, county or department.
swedish_identity_number
For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set. Beta: this field is only used for Autogiro, which is currently in beta.

Create a customer

Creates a new customer object.

Relative endpoint: POST /customers

Restricted: this endpoint is restricted to GoCardless Pro accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.

Parameters

address_line1
The first line of the customer’s address.
address_line2
The second line of the customer’s address.
address_line3
The third line of the customer’s address.
city
The city of the customer’s address.
company_name
Customer’s company name. Required unless a given_name and family_name are provided.
country_code
ISO 3166-1 alpha-2 code.
email
Customer’s email address.
family_name
Customer’s surname. Required unless a company_name is provided.
given_name
Customer’s first name. Required unless a company_name is provided.
language
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
postal_code
The customer’s postal code.
region
The customer’s address region, county or department.
swedish_identity_number
For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set. Beta: this field is only used for Autogiro, which is currently in beta.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customers()->create([
  "params" => ["email" => "[email protected]",
               "given_name" => "Tim",
               "family_name" => "Rogers",
               "country_code" => "GB"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customers.create(params={
  "email": "[email protected]",
  "given_name": "Frank",
  "family_name": "Osborne",
  "address_line1": "27 Acer Road",
  "address_line2": "Apt 2",
  "city": "London",
  "postal_code": "E8 3GX",
  "country_code": "GB",
  "metadata": {
    "salesforce_id": "ABCD1234"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customers.create(
  params: {
    email: "[email protected]",
    given_name: "Jacob",
    family_name: "Pargin",
    country_code: "GB"
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Customer customer = client.customers().create()
  .withEmail("[email protected]")
  .withGivenName("Frank")
  .withFamilyName("Osborne")
  .withAddressLine1("27 Acer Road")
  .withAddressLine2("Apt 2")
  .withCity("London")
  .withPostalCode("E8 3GX")
  .withCountryCode("GB")
  .withMetadata("salesforce_id", "ABCD1234")
  .execute();


POST https://api.gocardless.com/customers HTTP/1.1
{
  "customers": {
    "email": "[email protected]",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "city": "London",
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /customers/CU123
{
  "customers": {
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "[email protected]",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "swedish_identity_number": null,
"metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}

List customers

Returns a cursor-paginated list of your customers.

Relative endpoint: GET /customers

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
limit
Number of records to return.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customers()->list();

$client->customers()->list([
  "params" => ["created_at[gt]" => "2015-11-03T09:30:00Z"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customers.list().records

client.customers.list(params={"after": "CU123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customers.list

@client.customers.list(
  params: {
    "created_at[gt]" => "2016-08-06T09:30:00Z"
  }
)

@client.customers.list.records.each { |customer| puts customer.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Customer customer : client.customers().all().execute()) {
  System.out.println(customer.getId());
}


GET https://api.gocardless.com/customers?after=CU123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": "CU000",
      "after": "CU456",
    },
    "limit": 50
  },
  "customers": [{
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "[email protected]",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }, {
  ...
  }]
}

Get a single customer

Retrieves the details of an existing customer.

Relative endpoint: GET /customers/CU123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customers()->get("CU123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customers.get("CU123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customers.get("CU123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Customer customer = client.customers().get("CU123").execute();


GET https://api.gocardless.com/customers/CU123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "customers": {
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "[email protected]",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "swedish_identity_number": null,
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}

Update a customer

Updates a customer object. Supports all of the fields supported when creating a customer.

Relative endpoint: PUT /customers/CU123

Parameters

address_line1
The first line of the customer’s address.
address_line2
The second line of the customer’s address.
address_line3
The third line of the customer’s address.
city
The city of the customer’s address.
company_name
Customer’s company name. Required unless a given_name and family_name are provided.
country_code
ISO 3166-1 alpha-2 code.
email
Customer’s email address.
family_name
Customer’s surname. Required unless a company_name is provided.
given_name
Customer’s first name. Required unless a company_name is provided.
language
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
postal_code
The customer’s postal code.
region
The customer’s address region, county or department.
swedish_identity_number
For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set. Beta: this field is only used for Autogiro, which is currently in beta.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customers()->update("CU123", [
  "params" => ["email" => "[email protected]"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customers.update("CU123", params={
  "email": "[email protected]"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customers.update(
  "CU123",
  params: {
    metadata: { custom_reference: "EXAMPLELTD01" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.customers().update("CU123")
  .withEmail("[email protected]")
  .withGivenName("Jenny")
  .execute();


PUT https://api.gocardless.com/customers/CU123 HTTP/1.1
{
  "customers": {
    "email": "[email protected]",
    "given_name": "Jenny",
    "family_name": "Osborne",
    "metadata": {
      "salesforce_id": "EFGH5678"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "customers": {
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "[email protected]",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "29 Acer Road",
    "address_line2": "Apt 3",
    "address_line3": "Block 4",
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "swedish_identity_number": null,
    "metadata": {
      "salesforce_id": "EFGH5678"
    }
  }
}

Customer Bank Accounts

Customer Bank Accounts hold the bank details of a customer. They always belong to a customer, and may be linked to several Direct Debit mandates.

Note that customer bank accounts must be unique, and so you will encounter a bank_account_exists error if you try to create a duplicate bank account. You may wish to handle this by updating the existing record instead, the ID of which will be provided as links[customer_bank_account] in the error response.

Properties

id
Unique identifier, beginning with “BA”.
account_holder_name
Name of the account holder, as known by the bank. Usually this matches the name of the linked customer. This field will be transliterated, upcased and truncated to 18 characters.
account_number_ending
Last two digits of account number.
bank_name
Name of bank, taken from the bank details.
country_code
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code, defaults to national currency of country_code.
enabled
Boolean value showing whether the bank account is enabled or disabled.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
links[customer]
ID of the customer that owns this bank account.

Create a customer bank account

Creates a new customer bank account object.

There are three different ways to supply bank account details:

For more information on the different fields required in each country, see local bank details.

Relative endpoint: POST /customer_bank_accounts

Restricted: this endpoint is restricted to GoCardless Pro accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.

Parameters

account_holder_name
required Name of the account holder, as known by the bank. Usually this matches the name of the linked customer. This field will be transliterated, upcased and truncated to 18 characters.
account_number
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_code
Bank code - see local details for more information. Alternatively you can provide an iban.
branch_code
Branch code - see local details for more information. Alternatively you can provide an iban.
country_code
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
currency
ISO 4217 currency code, defaults to national currency of country_code.
iban
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for accounts in SEK.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
links[customer]
required ID of the customer that owns this bank account.
links[customer_bank_account_token]
ID of a customer bank account token to use in place of bank account parameters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customerBankAccounts()->create([
  "params" => ["account_number" => "55779911",
               "branch_code" => "200000",
               "account_holder_name" => "Frank Osborne",
               "country_code" => "GB",
               "links" => ["customer" => "CU123"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customer_bank_accounts.create(params={
  "account_number": "55779911",
  "branch_code": "200000",
  "account_holder_name": "Frank Osborne",
  "country_code": "GB",
  "links": {
    "customer": "CU123"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customer_bank_accounts.create(
  params: {
    account_holder_name: "Fran Cosborne",
    account_number: "55779911",
    branch_code: "200000",
    country_code: "GB",
    links: {
      customer: "CU123"
    }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

CustomerBankAccount customerBankAccount = client.customerBankAccounts().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withAccountHolderName("Frank Osborne")
  .withCountryCode("GB")
  .withLinksCustomer("CU123")
  .execute();


POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
{
  "customer_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "links": {
      "customer": "CU123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /customer_bank_accounts/BA123
{
  "customer_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "account_holder_name": "Frank Osborne",
    "account_number_ending": "11",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {},
    "enabled": true,
    "links": {
      "customer": "CU123"
    }
  }
}

List customer bank accounts

Returns a cursor-paginated list of your bank accounts.

Relative endpoint: GET /customer_bank_accounts

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
customer
Unique identifier, beginning with “CU”.
enabled
Get enabled or disabled customer bank accounts.
limit
Number of records to return.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customerBankAccounts()->list();

$client->customerBankAccounts()->list([
  "params" => ["customer" => "CU123",
               "enabled" => true]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customer_bank_accounts.list(params={"customer": "CU123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customer_bank_accounts.list

@client.customer_bank_accounts.list(
  params: {
    customer: "CU123",
    enabled: true
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (CustomerBankAccount customerBankAccount : client.customerBankAccounts().all().withCustomer("CU123").withEnabled(true).execute()) {
  System.out.println(customerBankAccount.getAccountHolderName());
}


GET https://api.gocardless.com/customer_bank_accounts HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "customer_bank_accounts": [{
    "id": "BA123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "account_holder_name": "Frank Osborne",
    "account_number_ending": "11",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {},
    "enabled": true,
    "links": {
      "customer": "CU123"
    }
  }]
}

Get a single customer bank account

Retrieves the details of an existing bank account.

Relative endpoint: GET /customer_bank_accounts/BA123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customerBankAccounts()->get("BA123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customer_bank_accounts.get("BA123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customer_bank_accounts.get("BA123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

CustomerBankAccount customerBankAccount = client.customerBankAccounts.get("BA123").execute();


GET https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "customer_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "account_number_ending": "11",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {},
    "enabled": true,
    "links": {
      "customer": "CU123"
    }
  }
}

Update a customer bank account

Updates a customer bank account object. Only the metadata parameter is allowed.

Relative endpoint: PUT /customer_bank_accounts/BA123

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customerBankAccounts()->update("BA123", [
  "params" => ["metadata" => ["key" => "value"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customer_bank_accounts.update("BA123", params={
  "metadata": {"key": "value"}
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customer_bank_accounts.update(
  "BA123",
  params: {
    metadata: { description: "Business account" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.customerBankAccounts().update("BA123")
  .withMetadata("description", "Business account")
  .execute();


PUT https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
{
  "customer_bank_accounts": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "customer_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "account_number_ending": "11",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {
      "key": "value"
    },
    "enabled": true,
    "links": {
      "customer": "CU123"
    }
  }
}

Disable a customer bank account

Immediately cancels all associated mandates and cancellable payments.

This will return a disable_failed error if the bank account has already been disabled.

A disabled bank account can be re-enabled by creating a new bank account resource with the same details.

Relative endpoint: POST /customer_bank_accounts/BA123/actions/disable


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customerBankAccounts()->disable("BA123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customer_bank_accounts.disable("BA123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.customer_bank_accounts.disable("BA123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.customerBankAccounts.disable("BA123").execute();


POST https://api.gocardless.com/customer_bank_accounts/BA123/actions/disable HTTP/1.1

HTTP/1.1 200 (OK)
{
  "customer_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "account_number_ending": "11",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {},
    "enabled": false,
    "links": {
      "customer": "CU123"
    }
  }
}

Events

Events are stored for all webhooks. An event refers to a resource which has been updated, for example a payment which has been collected, or a mandate which has been transferred.

Properties

id
Unique identifier, beginning with “EV”.
action
What has happened to the resource.
created_at
Fixed timestamp, recording when this resource was created.
details[cause]
What triggered the event.
details[description]
Human readable description of the cause. Note: Changes to event descriptions are not considered breaking.
details[origin]
Who initiated the event. One of:
  • bank: this event was triggered by a report from the banks

  • gocardless: this event was performed by GoCardless automatically

  • api: this event was triggered by an API endpoint

details[reason_code]
Set when a bank is the origin of the event. This is the reason code received in the report from the customer’s bank. See the GoCardless Direct Debit guide for information on the meanings of different reason codes.
details[scheme]
Set when a bank is the origin of the event.
metadata
If the details[origin] is api, this will contain any metadata you specified when triggering this event. In other cases it will be an empty object.
resource_type
The resource type for this event. One of:
  • payments

  • mandates

  • payouts

  • refunds

  • subscriptions

links[mandate]
If resource_type is mandates, this is the ID of the mandate which has been updated.
links[new_customer_bank_account]
This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred to.
links[new_mandate]
This is only included for mandate replaced events, when it is the ID of the new mandate that replaces the existing mandate.
links[organisation]
If the event is included in a webhook to an OAuth app, this is the ID of the account to which it belongs.
links[parent_event]
If this event was caused by another, this is the ID of the cause. For example, if a mandate is cancelled it automatically cancels all pending payments associated with it; in this case, the payment cancellation events would have the ID of the mandate cancellation event in this field.
links[payment]
If resource_type is payments, this is the ID of the payment which has been updated.
links[payout]
If resource_type is payouts, this is the ID of the payout which has been updated.
links[previous_customer_bank_account]
This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred from.
links[refund]
If resource_type is refunds, this is the ID of the refund which has been updated.
links[subscription]
If resource_type is subscription, this is the ID of the subscription which has been updated.

List events

Returns a cursor-paginated list of your events.

Relative endpoint: GET /events

Parameters

action
Limit to events with a given action.
after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
include
Includes linked resources in the response. Must be used with the resource_type parameter specified. The include should be one of:
  • payment

  • mandate

  • payout

  • refund

  • subscription

limit
Number of records to return.
mandate
ID of a mandate. If specified, this endpoint will return all events for the given mandate.
parent_event
ID of an event. If specified, this endpint will return all events whose parent_event is the given event ID.
payment
ID of a payment. If specified, this endpoint will return all events for the given payment.
payout
ID of a payout. If specified, this endpoint will return all events for the given payout.
refund
ID of a refund. If specified, this endpoint will return all events for the given refund.
resource_type
Type of resource that you’d like to get all events for. Cannot be used together with the payment, mandate, subscription, refund or payout parameter. The type can be one of:
  • payments

  • mandates

  • payouts

  • subscriptions

  • refunds

subscription
ID of a subscription. If specified, this endpoint will return all events for the given subscription.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->events()->list();

$client->events()->list([
  "params" => ["resource_type" => "payments"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.events.list().records

client.events.list(params={"resource_type": "payments"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.events.list

@client.events.list(params: { resource_type: "payments" })

@client.events.list.records.each { |event| puts event.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Event event : client.events().all().withResourceType("payments").execute()) {
  System.out.println(event.getAction());
}


GET https://api.gocardless.com/events HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  },
  "events":[
    {
      "id": "EV123",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "mandates",
      "action": "cancelled",
      "details": {
        "origin": "bank",
        "cause": "bank_account_disabled",
        "description": "Customer's bank account closed",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      },
      "metadata": {},
      "links": {
        "mandate": "MD123"
      }
    },
    {
      "id": "EV456",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "payments",
      "action": "cancelled",
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "The mandate for this payment was cancelled at a bank branch.",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      },
      "metadata": {},
      "links": {
        "payment": "PM123",
        "parent_event": "EV123"
      }
    }
  ]
}

GET https://api.gocardless.com/events?resource_type=payments&include=payment HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  },
  "events":[
    {
      "id": "EV456",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "payments",
      "action": "cancelled",
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "The mandate for this payment was cancelled at a bank branch.",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      },
      "metadata": {},
      "links": {
        "payment": "PM123",
        "parent_event": "EV123"
      }
    }
  ],
  "linked": {
    "payments": [
      {
        "id": "PM123",
        "created_at": "2014-05-08T17:01:06.000Z",
        "charge_date": "2014-05-15",
        "amount": 100,
        "description": null,
        "currency": "GBP",
        "status": "paid_out",
        "reference": "WINEBOX001",
        "metadata": {
          "order_dispatch_date": "2014-05-22"
        },
        "amount_refunded": 0,
        "links": {
          "mandate": "MD123",
          "creditor": "CR123"
        }
      }
    ]
  }
}

Get a single event

Retrieves the details of a single event.

Relative endpoint: GET /events/EV123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->events()->get("EV123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.events.get("EV123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.events.get("EV123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Event event = client.events().get("EV123").execute();


GET https://api.gocardless.com/events/EV123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payments",
    "action": "confirmed",
    "details": {
      "origin": "gocardless",
      "cause": "payment_confirmed",
      "description": "Payment confirmed"
    },
    "metadata": {},
    "links": {
      "payment": "PM123"
    }
  }
}

Mandate actions

created
The mandate has been created.
submitted
The mandate has been submitted to the banks, and should become active in a few days, unless the bank declines the request.
active
The mandate has been successfully set up by the customer’s bank.
reinstated
The mandate has become active again, after it was cancelled or expired. This can be due to the customer’s bank wishing to undo a cancellation or expiry notice they sent, or because the mandate was successfully reinstated via the reinstate endpoint.
transferred
The mandate has been transferred to a different bank account. The event will include links[previous_customer_bank_account] and links[new_customer_bank_account], and the mandate may have been submitted again, depending on how the banks involved handled the transfer.
cancelled
The mandate has been cancelled, either by the customer through their bank or this API, or automatically when their bank account is closed.
failed
The mandate could not be set up, generally because the specified bank account does not accept Direct Debit payments or is closed.
expired
No collection attempts were made against the mandate for over 13 months. As a result it has expired, and no further collections can be taken against it. If you wish to continue taking payments from this customer you should request their permission and use the reinstate endpoint.
resubmission_requested
A request to resubmit the mandate was made by the mandate reinstate endpoint.
replaced
The mandate has been cancelled and replaced by a new mandate (for example, because the creditor has moved to a new Service User Number). The event will include links[new_mandate] with the ID of the new mandate.

Mandate causes

mandate_created

The mandate was created through the API or by GoCardless (in the case of a bulk change).

Origin Consequences
api Mandate created
gocardless Mandate created

mandate_submitted

The mandate has been submitted to the banks.

Origin Consequences
gocardless Mandate submitted

mandate_activated

The time window after submission for the banks to refuse a mandate has ended without any errors being received, so this mandate is now active.

Origin Consequences
gocardless Mandate active

mandate_cancelled

The mandate was cancelled either via an API call, or at the bank.

Origin Scheme Reason code Consequences
api - - Mandate cancelled
bank bacs ADDACS-0 Mandate cancelled
bank bacs ADDACS-1 Mandate cancelled
bank bacs ARUDD-1 Payment failed, mandate cancelled
bank sepa_core MD01 Payment failed, mandate cancelled

links[parent_event] will be the payment failure event for the latter two reason codes.

mandate_expired

The mandate is being marked as expired, because no payments have been collected against it for the dormancy period of your Service User Number. You may use the mandate reinstation endpoint to attempt to set this mandate up again.

Origin Consequences
gocardless Mandate expired

resubmission_requested

A request to resubmit a mandate was made via the mandate reinstate endpoint.

Origin Consequences
api Mandate resubmitted to banks in next batch

mandate_reinstated

A cancelled mandate has been re-instated by the customer’s bank.

Origin Scheme Reason code Consequences
gocardless - - Mandate reinstated
bank bacs ADDACS-R Mandate reinstated

bank_account_closed

The bank account for this mandate is closed. This can be from the customer bank account disable endpoint, or in a message from the banks, indicating that the account has been closed

Origin Scheme Reason code Consequences
api - - Mandate cancelled, bank account disabled
bank bacs AUDDIS-2 Mandate failed
bank bacs AUDDIS-B Mandate failed
bank bacs ADDACS-2 Mandate cancelled
bank bacs ADDACS-B Mandate cancelled
bank bacs ARUDD-2 Payment failed, mandate cancelled
bank bacs ARUDD-B Payment failed, mandate cancelled
bank sepa_core AC04 Payment failed, mandate cancelled
bank sepa_core MD07 Payment failed, mandate cancelled

invalid_bank_details

The bank details used to set up this mandate were rejected.

Origin Scheme Reason code Consequences
bank bacs AUDDIS-5 Mandate failed
bank bacs ARUDD-5 Payment failed, mandate failed
bank bacs ARUDD-Y Payment failed, mandate failed
bank sepa_core AC01 Payment failed, mandate cancelled

direct_debit_not_enabled

The bank account specified does not support direct debit.

Origin Scheme Reason code Consequences
bank bacs AUDDIS-F Mandate failed
bank bacs AUDDIS-G Mandate failed
bank bacs AUDDIS-N Mandate failed
bank sepa_core AC06 Payment failed, mandate cancelled
bank sepa_core AG01 Payment failed, mandate cancelled

bank_account_transferred

The customer’s bank account was transferred to a different bank or building society. Depending on the bank the account is being transferred to, this may require the mandate to be resubmitted. If so, there will first be an event with action set to submitted, and details[cause] set to bank_account_transferred, followed by a standard mandate_activated event 2 days later, or potentially a failure event if the new bank rejects the mandate. Otherwise, there will just be a single event with action set to transferred, and details[cause] set to bank_account_transferred.

Very occasionally, the transfer message from the banks will not include details of the new bank account. In this case the mandate will fail (if it is being set up), or be cancelled (if it is active).

Origin Scheme Reason code Consequences
bank bacs AUDDIS-3 Mandate submitted to new bank
bank bacs ADDACS-3 Mandate submitted to new bank
bank bacs AUDDIS-C Mandate transferred
bank bacs ADDACS-C Mandate transferred
bank bacs ADDACS-E Mandate transferred

links[previous_customer_bank_account] and links[new_customer_bank_account] will be included in this event, when the action is transferred.

authorisation_disputed

The customer disputes authorising the mandate.

Origin Scheme Reason code Consequences
bank bacs ADDACS-D Mandate cancelled
bank bacs DDICA-4 Payment charged back, mandate cancelled
bank bacs DDICA-5 Payment charged back, mandate cancelled
bank bacs DDICA-6 Payment charged back, mandate cancelled
bank bacs DDICA-8 Payment charged back, mandate cancelled

scheme_identifier_changed

The mandate has been cancelled and replaced by a new mandate, as a result of changing to a new scheme identifier. This occurs when the creditor has upgraded to the Plus or Pro package. The event and requests to retrieve the mandate itself will include links[new_mandate], which contains the ID of the new mandate.

Origin Consequences
gocardless Mandate cancelled, new mandate created
GET https://api.gocardless.com/events/EV123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "mandates",
    "action": "cancelled",
    "details": {
      "origin": "bank",
      "cause": "bank_account_closed",
      "description": "The bank account for this mandate has been closed.",
      "scheme": "bacs",
      "reason_code": "ADDACS-B"
    },
    "metadata": {},
    "links": {
      "mandate": "MD123"
    }
  }
}


GET https://api.gocardless.com/events/EV456 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV456",
    "created_at": "2014-04-08T17:03:12.000Z",
    "resource_type": "mandates",
    "action": "cancelled",
    "details": {
      "origin": "api",
      "cause": "mandate_cancelled",
      "description": "The mandate was cancelled via an API call."
    },
    "metadata": {
      "cancellor_id": "some_id"
    },
    "links": {
      "mandate": "MD456"
    }
  }
}


GET https://api.gocardless.com/events/EV789 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV789",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "mandates",
    "action": "transferred",
    "details": {
      "origin": "bank",
      "cause": "bank_account_transferred",
      "description": "The customer's bank account was transferred to a different bank or building society.",
      "scheme": "bacs",
      "reason_code": "AUDDIS-C"
    },
    "metadata": {},
    "links": {
      "mandate": "MD789",
      "previous_customer_bank_account": "BA123",
      "new_customer_bank_account": "BA456"
    }
  }
}

Payment actions

created
The payment has been created.
submitted
The payment has been submitted to the banks. It will be a few days until it is collected, or fails.
confirmed
The payment has been collected from the customer’s bank account, and is now being held by GoCardless. It can take up to 5 working days for a payment to be collected, and will then be held for a short time before becoming paid_out.
cancelled
The payment was cancelled.
failed
The payment could not be collected, usually because the customer did not have sufficient funds available. GoCardless will not automatically retry the payment.
charged_back
The customer asked their bank to refund the payment under the Direct Debit Guarantee, and it has been returned to the customer.
chargeback_cancelled
The customer’s bank has cancelled the chargeback request. This is almost always at the request of the customer.
paid_out
The payment has left GoCardless and has been sent to the creditor’s bank account.
late_failure_settled
The payment was a late failure which had already been paid out, and has been debited from a payout.
chargeback_settled
The payment was charged back, having previously been paid out, and has been debited from a payout.
resubmission_requested
A request to resubmit the payment was made by the payment retry endpoint.

Payment causes

payment_created

The payment was created through the API or by GoCardless (in the case of a subscription).

Origin Consequences
api Payment created
gocardless Payment created

payment_cancelled

Payment cancelled via an API call.

Origin Consequences
api Payment cancelled

payment_submitted

The payment has now been submitted to the banks, and cannot be cancelled

Origin Consequences
gocardless Payment submitted

payment_confirmed

Either enough time has passed since the payment was submitted for the banks to return an error, so this payment is now confirmed, or a chargeback on this payment was cancelled by the banks.

Origin Scheme Reason code Consequences
gocardless - - Payment confirmed
bank bacs DDICA-1 Payment chargeback cancelled
bank bacs DDICA-2 Payment chargeback cancelled
bank bacs DDICA-3 Payment chargeback cancelled
bank bacs DDICA-4 Payment chargeback cancelled
bank bacs DDICA-5 Payment chargeback cancelled
bank bacs DDICA-6 Payment chargeback cancelled
bank bacs DDICA-7 Payment chargeback cancelled
bank bacs DDICA-8 Payment chargeback cancelled

payment_paid_out

The payment has been paid out by GoCardless.

Origin Consequences
gocardless Payment paid out

payment_retried

A request to resubmit a payment was made via the payment retry endpoint.

Origin Consequences
api Payment resubmitted to banks in next batch

late_failure_settled

The payment has been debited from a payout by GoCardless.

Origin Consequences
gocardless Payment settled against a payout.

chargeback_settled

The payment has been debited from a payout by GoCardless.

Origin Consequences
gocardless Payment settled against a payout.

test_failure

In the sandbox environment, some SEPA payments will be marked as failed, to help with testing of your integration. This cause and reason code will never appear in the live environment.

Origin Scheme Reason code Consequences
bank sepa_core TEST Payment failed

insufficient_funds

The customer did not have funds available to make the payment.

Origin Scheme Reason code Consequences
bank sepa_core AM04 Payment failed

refer_to_payer

The customer’s bank wasn’t able to pay the Direct Debit. For Bacs, this is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. For SEPA these codes are instead used to obfuscate the failure cause for privacy and other regulatory reasons.

Origin Scheme Reason code Consequences
bank bacs ARUDD-0 Payment failed
bank sepa_core MS02 Payment failed
bank sepa_core MS03 Payment failed
bank sepa_core RR04 Payment failed
bank sepa_core SL01 Payment failed

bank_account_closed

The customer’s bank account was closed before the payment could be taken. The mandate will be cancelled.

Origin Scheme Reason code Consequences
api - - Bank account disabled, payment cancelled
bank bacs ADDACS-2 Mandate cancelled, payment cancelled
bank bacs ADDACS-B Mandate cancelled, payment cancelled
bank bacs AUDDIS-2 Mandate failed, payment cancelled
bank bacs AUDDIS-B Mandate failed, payment cancelled
bank bacs ARUDD-2 Payment failed, mandate cancelled
bank bacs ARUDD-B Payment failed, mandate cancelled
bank sepa_core AC04 Payment failed, mandate cancelled
bank sepa_core MD07 Payment failed, mandate cancelled

direct_debit_not_enabled

The customer’s bank account does not allows direct debit payments. The mandate will also be cancelled.

Origin Scheme Reason code Consequences
bank bacs AUDDIS-F Mandate failed, payment cancelled
bank bacs AUDDIS-G Mandate failed, payment cancelled
bank bacs AUDDIS-N Mandate failed, payment cancelled
bank sepa_core AC06 Payment failed, mandate cancelled
bank sepa_core AG01 Payment failed, mandate cancelled

invalid_bank_details

The bank account details used to set up the mandate for this payment were incorrect. The mandate will be cancelled.

Origin Scheme Reason code Consequences
bank bacs ARUDD-5 Payment failed, mandate cancelled
bank bacs ARUDD-Y Payment failed, mandate cancelled
bank bacs AUDDIS-5 Mandate failed, payment cancelled
bank sepa_core AC01 Payment failed, mandate cancelled

bank_account_transferred

The customer has asked their bank to transfer the mandate for this payment to a new account, but this payment has been submitted to the old account. GoCardless will have automatically transferred the mandate to the new bank account if possible, so this payment can be retried unless the mandate has been cancelled.

Origin Scheme Reason code Consequences
bank bacs ARUDD-3 Payment failed
bank bacs ADDACS-3 Mandate cancelled, payment cancelled
bank bacs ADDACS-C Mandate cancelled, payment cancelled
bank bacs AUDDIS-3 Mandate failed, payment cancelled
bank bacs AUDDIS-C Mandate failed, payment cancelled

mandate_cancelled

Either: * the mandate for this payment is being cancelled by an API call; or * the payment failed using a code that indicated that the mandate has been cancelled; or * the customer cancelled the mandate via their bank.

Origin Scheme Reason code Consequences
api - - Payment cancelled, mandate cancelled
bank bacs ARUDD-1 Payment failed, mandate cancelled
bank bacs ADDACS-0 Mandate cancelled, payment cancelled
bank bacs ADDACS-1 Mandate cancelled, payment cancelled
bank sepa_core MD01 Payment failed, mandate cancelled

links[parent_event] will be the ID of the mandate cancellation event if the payment is being cancelled rather than failed.

authorisation_disputed

In SEPA, customers are entitled to a refund of payments they did not authorise within 13 months. In Bacs, there is no time limit on this entitlement.

Origin Scheme Reason code Consequences
bank bacs ARUDD-4 Payment failed
bank bacs ARUDD-7 Payment failed
bank bacs ADDACS-D Mandate cancelled, payment cancelled
bank bacs DDICA-1 Payment charged back
bank bacs DDICA-2 Payment charged back
bank bacs DDICA-4 Payment charged back, mandate cancelled
bank bacs DDICA-5 Payment charged back, mandate cancelled
bank bacs DDICA-6 Payment charged back, mandate cancelled
bank bacs DDICA-8 Payment charged back, mandate cancelled
bank sepa_core MD01 Payment charged back

refund_requested

In SEPA, customers are entitled to a refund for authorised transactions within 8 weeks

Origin Scheme Reason code Consequences
bank sepa_core MD06 Payment charged back
GET https://api.gocardless.com/events/EV1234 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payments",
    "action": "failed",
    "details": {
      "origin": "bank",
      "cause": "insufficient_funds",
      "description": "The customer's account had insufficient funds to make this payment.",
      "scheme": "sepa_core",
      "reason_code": "AM04"
    },
    "metadata": {},
    "links": {
      "payment": "PM123"
    }
  }
}


GET https://api.gocardless.com/events/EV4567 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV4567",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payments",
    "action": "cancelled",
    "details": {
      "origin": "bank",
      "cause": "mandate_cancelled",
      "description": "The mandate for this payment was cancelled as the customer's bank account has been closed.",
      "scheme": "bacs",
      "reason_code": "ADDACS-B"
    },
    "metadata": {},
    "links": {
      "payment": "PM456",
      "parent_event": "EV789"
    }
  }
}


GET https://api.gocardless.com/events/EV8901 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV8901",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payments",
    "action": "cancelled",
    "details": {
      "origin": "api",
      "cause": "payment_cancelled",
      "description": "Payment cancelled."
    },
    "metadata": {
      "cancellor_id": "some_id"
    },
    "links": {
      "payment": "PM789"
    }
  }
}


GET https://api.gocardless.com/events/EV2345 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV2345",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payments",
    "action": "confirmed",
    "details": {
      "origin": "gocardless",
      "cause": "payment_confirmed",
      "description": "Payment confirmed"
    },
    "metadata": {},
    "links": {
      "payment": "PM999"
    }
  }
}

Payout actions

paid
GoCardless has transferred the payout to the creditor’s bank account. The details[cause] will always be payout_paid, and the details[origin] will be gocardless.
GET https://api.gocardless.com/events/EV123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payouts",
    "action": "paid",
    "details": {
      "origin": "gocardless",
      "cause": "payout_paid",
      "description": "Payout sent"
    },
    "metadata": {},
    "links": {
      "payout": "PO123"
    }
  }
}

Refund actions

created
A refund has been created. The details[cause] will be payment_refunded, and the details[origin] will be api.
paid
The refund has been paid to your customer. The details[cause] will be refund_paid, and the details[origin] will be gocardless.
refund_settled
The refund has been deducted from a payout. The details[cause] will be refund_settled, and the details[origin] will be gocardless.
GET https://api.gocardless.com/events/EV123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "refunds",
    "action": "created",
    "details": {
      "origin": "api",
      "cause": "payment_refunded",
      "description": "The refund has been created, and will be submitted in the next batch."
    },
    "metadata": {},
    "links": {
      "refund": "RF123"
    }
  }
}

Subscription actions

created
The subscription has been created.
payment_created
A payment has been created by this subscription.
cancelled
This subscription has been cancelled. No further payments will be created.
finished
This subscription has finished. No further payments will be created.

Subscription causes

subscription_created

The subscription was created through the API.

Origin Consequences
api Subscription created

subscription_cancelled

The subscription was cancelled via the API.

Origin Consequences
api Subscription cancelled

subscription_finished

The subscription has finished, as an end date or payment count was specified when the subscription was created.

Origin Consequences
gocardless Subscription finished

mandate_cancelled

The mandate for this subscription was cancelled by an API call, or at the customer’s bank.

Origin Scheme Reason code Consequences
api - - Mandate cancelled, subscription cancelled
bank bacs ADDACS-0 Mandate cancelled, subscription cancelled
bank bacs ADDACS-1 Mandate cancelled, subscription cancelled
bank bacs ARUDD-1 Payment failed, subscription cancelled
bank sepa_core MD01 Payment failed, subscription cancelled

mandate_expired

The mandate for this subscription expired, because no payments have been collected against it for the dormancy period of your Service User Number. You may use the mandate reinstation endpoint to attempt to set this mandate up again.

Origin Consequences
gocardless Mandate expired, subscription cancelled

bank_account_closed

The customer’s bank account was closed by an API call, or at their bank.

Origin Scheme Reason code Consequences
api - - Bank account disabled, subscription cancelled
bank bacs ADDACS-2 Mandate cancelled, subscription cancelled
bank bacs ADDACS-B Mandate cancelled, subscription cancelled
bank bacs AUDDIS-2 Mandate failed, subscription cancelled
bank bacs AUDDIS-B Mandate failed, subscription cancelled
bank bacs ARUDD-2 Payment failed, subscription cancelled
bank bacs ARUDD-B Payment failed, subscription cancelled
bank sepa_core AC04 Payment failed, subscription cancelled
bank sepa_core MD07 Payment failed, subscription cancelled

direct_debit_not_enabled

The customer’s bank account does not allows direct debit payments.

Origin Scheme Reason code Consequences
bank bacs AUDDIS-F Mandate failed, subscription cancelled
bank bacs AUDDIS-G Mandate failed, subscription cancelled
bank bacs AUDDIS-N Mandate failed, subscription cancelled
bank sepa_core AC06 Payment failed, subscription cancelled
bank sepa_core AG01 Payment failed, subscription cancelled

invalid_bank_details

The bank account details used to set up the mandate for this subscription were incorrect.

Origin Scheme Reason code Consequences
bank bacs ARUDD-5 Payment failed, subscription cancelled
bank bacs ARUDD-Y Payment failed, subscription cancelled
bank bacs AUDDIS-5 Mandate failed, subscription cancelled
bank sepa_core AC01 Payment failed, subscription cancelled

bank_account_transferred

The customer asked their bank to transfer this mandate to another account, but their bank failed to tell GoCardless the details of the new account, so the mandate has been cancelled.

Origin Scheme Reason code Consequences
bank bacs ADDACS-3 Mandate cancelled, subscription cancelled
bank bacs ADDACS-C Mandate cancelled, subscription cancelled
bank bacs AUDDIS-3 Mandate failed, subscription cancelled
bank bacs AUDDIS-C Mandate failed, subscription cancelled

authorisation_disputed

The customer disputes authorising the mandate for this subscription.

Origin Scheme Reason code Consequences
bank bacs ADDACS-D Mandate cancelled, subscription cancelled
bank bacs DDICA-3 Payment charged back, subscription cancelled
bank bacs DDICA-4 Payment charged back, subscription cancelled
bank sepa_core MD01 Payment charged back, subscription cancelled

plan_cancelled

The plan associated with this subscription was cancelled.

Origin Consequences
api Plan cancelled, subscription cancelled
GET https://api.gocardless.com/events/EV123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "subscriptions",
    "action": "payment_created",
    "links": {
      "subscription": "SB123",
      "payment": "PM123"
    }
  }
}

Reconciling Payouts with Events

When a payout is created not only does it have an event created for it, but all payments and refunds within that payout have events created for them too. If you know the payout’s ID, you can fetch all of these events using two API requests.

The first step is to find the “paid” event for the Payout you’re interested in. You can do this by filtering events based on the ID of the payout and the action, which is “paid”:

GET https://api.gocardless.com/events?payout=PY123&action=paid

To find child events for a payout, filter for events with a parent_event equal to the Payout’s paid event:

GET https://api.gocardless.com/events?parent_event=EV123

This will return a paginated list of all child events for payments and refunds associated with the payout.

If you’d also like to return the associated payments or refunds, you can scope the request to a resource_type and include those resources:

GET https://api.gocardless.com/events?parent_event=EV123&resource_type=payments&include=payment

GET https://api.gocardless.com/events?parent_event=EV123&resource_type=refunds&include=refund
GET https://api.gocardless.com/events?payout=PY123&action=paid HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  },
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "payouts",
      "action": "paid",
      "details": {
        "origin": "gocardless",
        "cause": "payout_paid",
        "description": "Payout sent"
      },
      "metadata": {},
      "links": {
        "payout": "PO123"
      }
    }
  ]
}

GET https://api.gocardless.com/events?parent_event=EV123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  },
  "events": [
    {
      "id": "EV456",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "payments",
      "action": "paid_out",
      "details": {
        "origin": "gocardless",
        "cause": "payment_paid_out",
        "description": "The payment has been paid out by GoCardless."
      },
      "metadata": {},
      "links": {
        "payment": "PM123"
      }
    }
  ]
}

Mandates

Mandates represent the Direct Debit mandate with a customer.

GoCardless will notify you via a webhook whenever the status of a mandate changes.

Properties

id
Unique identifier, beginning with “MD”.
created_at
Fixed timestamp, recording when this resource was created.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
next_possible_charge_date
The earliest date a newly created payment for this mandate could be charged.
payments_require_approval
Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.
reference
Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
scheme
Direct Debit scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer’s bank account. Currently only “autogiro”, “bacs”, and “sepa_core” are supported.
status
One of:
  • pending_customer_approval: the mandate has not yet been signed by the second customer

  • pending_submission: the mandate has not yet been submitted to the customer’s bank

  • submitted: the mandate has been submitted to the customer’s bank but has not been processed yet

  • active: the mandate has been successfully set up by the customer’s bank

  • failed: the mandate could not be created

  • cancelled: the mandate has been cancelled

  • expired: the mandate has expired due to dormancy

links[creditor]
ID of the associated creditor.
links[customer]
ID of the associated customer
links[customer_bank_account]
ID of the associated customer bank account which the mandate is created and submits payments against.
links[new_mandate]
ID of the new mandate if this mandate has been replaced.

Create a mandate

Creates a new mandate object.

Relative endpoint: POST /mandates

Restricted: this endpoint is restricted to GoCardless Pro accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.

Warning: by default, the ability to provide a custom mandate reference is switched off. The banking system rules for valid references are quite complex, and we recommend allowing GoCardless to generate it. If you would like to provide custom references, please contact support.

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
reference
Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
scheme
Direct Debit scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer’s bank account. Currently only “autogiro”, “bacs”, and “sepa_core” are supported.
links[creditor]
ID of the associated creditor. Only required if your account manages multiple creditors.
links[customer_bank_account]
required ID of the associated customer bank account which the mandate is created and submits payments against.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandates()->create([
  "params" => ["scheme" => "bacs", "metadata" => ["contract" => "ABCD1234"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandates.create(params={
  "scheme": "bacs",
  "metadata": {
    "contract": "ABCD1234"
   },
  "links": {
    "customer_bank_account": "BA123",
    "creditor": "CR123"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandates.create(
  params: {
    scheme: "bacs",
    links: {
      customer_bank_account: "BA123"
    }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Mandate mandate = client.mandates.create()
  .withScheme("bacs")
  .withLinksCustomerBankAccount("BA123")
  .withMetadata("contract", "ABCD1234")
  .execute();


POST https://api.gocardless.com/mandates HTTP/1.1
{
  "mandates": {
    "scheme": "bacs",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /mandates/MD123
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

List mandates

Returns a cursor-paginated list of your mandates.

Relative endpoint: GET /mandates

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
creditor
ID of a creditor. If specified, this endpoint will return all mandates for the given creditor. Cannot be used in conjunction with customer or customer_bank_account
customer
ID of a customer. If specified, this endpoint will return all mandates for the given customer. Cannot be used in conjunction with customer_bank_account or creditor
customer_bank_account
ID of a customer bank account. If specified, this endpoint will return all mandates for the given bank account. Cannot be used in conjunction with customer or creditor
limit
Number of records to return.
reference
Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
status
At most three valid status values

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandates()->list();

$client->mandates()->list([
  "params" => ["customer" => "CU123"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandates.list().records

client.mandates.list(params={"customer": "CU123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandates.list

@client.mandates.list(params: { customer: "CU123" })

@client.mandates.list.records.each { |mandate| puts mandate.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Mandate mandate : client.mandates().all().withCustomer("CU123").execute()) {
  System.out.println(mandate.getId());
}


GET https://api.gocardless.com/mandates HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "mandates": [{
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }]
}

Get a single mandate

Retrieves the details of an existing mandate.

Relative endpoint: GET /mandates/MD123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandates()->get("MD123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandates.get("MD123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandates.get("MD123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Mandate mandate = client.mandates().get("MD123").execute();


GET https://api.gocardless.com/mandates/MD123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Update a mandate

Updates a mandate object. This accepts only the metadata parameter.

Relative endpoint: PUT /mandates/MD123

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandates()->update("MD123", [
  "params" => ["metadata" => ["key" => "value"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandates.update("MD123", params={
  "metadata": {"key": "value"}
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandates.update(
  "MD123",
  params: {
    metadata: { contract_id: "ref_09011991" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.mandates().update("MD123").withMetadata("contract_id", "ref_09011991").execute();


PUT https://api.gocardless.com/mandates/MD123 HTTP/1.1
{
  "mandates": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "key": "value"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Cancel a mandate

Immediately cancels a mandate and all associated cancellable payments. Any metadata supplied to this endpoint will be stored on the mandate cancellation event it causes.

This will fail with a cancellation_failed error if the mandate is already cancelled.

Relative endpoint: POST /mandates/MD123/actions/cancel

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandates()->cancel("MD123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandates.cancel("MD123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandates.cancel("MD123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.mandates().cancel("MD123").execute();


POST https://api.gocardless.com/mandates/MD123/actions/cancel HTTP/1.1
{
  "data": {
    "metadata": {}
  }
}

HTTP/1.1 200 (OK)
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "cancelled",
    "scheme": "bacs",
    "next_possible_charge_date": null,
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Reinstate a mandate

Reinstates a cancelled or expired mandate to the banks. You will receive a resubmission_requested webhook, but after that reinstating the mandate follows the same process as its initial creation, so you will receive a submitted webhook, followed by a reinstated or failed webhook up to two working days later. Any metadata supplied to this endpoint will be stored on the resubmission_requested event it causes.

This will fail with a mandate_not_inactive error if the mandate is already being submitted, or is active.

Mandates can be resubmitted up to 3 times.

Relative endpoint: POST /mandates/MD123/actions/reinstate

Restricted: this endpoint is restricted to accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandates()->reinstate("MD123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandates.reinstate("MD123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandates.reinstate("MD123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.mandates().reinstate("MD123").execute();


POST https://api.gocardless.com/mandates/MD123/actions/reinstate HTTP/1.1
{
  "data": {
    "metadata": {
      "ticket_id": "TK123"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "submitted",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Payments

Payment objects represent payments from a customer to a creditor, taken against a Direct Debit mandate.

GoCardless will notify you via a webhook whenever the state of a payment changes.

Properties

id
Unique identifier, beginning with “PM”.
amount
Amount in pence (GBP), cents (EUR), or öre (SEK).
amount_refunded
Amount refunded in pence/cents/öre.
charge_date
A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. This must be on or after the mandate’s next_possible_charge_date, and will be rolled-forwards by GoCardless if it is not a working day.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. Currently only “GBP”, “EUR”, and “SEK” are supported.
description
A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
reference
An optional payment reference that will appear on your customer’s bank statement. For Bacs payments this can be up to 10 characters, for SEPA payments the limit is 140 characters, and for Autogiro payments the limit is 11 characters. Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
status
One of:
  • pending_customer_approval: we’re waiting for the customer to approve this payment

  • pending_submission: the payment has been created, but not yet submitted to the banks

  • submitted: the payment has been submitted to the banks

  • confirmed: the payment has been confirmed as collected

  • paid_out: the payment has been included in a payout

  • cancelled: the payment has been cancelled

  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly

  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.

  • charged_back: the payment has been charged back

links[creditor]
ID of creditor to which the collected payment will be sent.
links[mandate]
ID of the mandate against which this payment should be collected.
links[payout]
ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.
links[subscription]
ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

Create a payment

Creates a new payment object.

This fails with a mandate_is_inactive error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pending_customer_approval, pending_submission, submitted, and active.

Relative endpoint: POST /payments

Warning: in Bacs, you have the option to provide a payment reference up to 10 characters in length. However, if you are providing custom mandate references (which can only be enabled by contacting support), the combined length of the two references separated by a dash character must not exceed 18 characters. For SEPA and Autogiro, payment references may be up to 140 and 16 characters respectively, irrespective of the mandate reference.

Parameters

amount
required Amount in pence (GBP), cents (EUR), or öre (SEK).
app_fee
The amount to be deducted from the payment as the OAuth app’s fee, in pence or cents.
charge_date
A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. This must be on or after the mandate’s next_possible_charge_date, and will be rolled-forwards by GoCardless if it is not a working day.
currency
required ISO 4217 currency code. Currently only “GBP”, “EUR”, and “SEK” are supported.
description
A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
reference
An optional payment reference that will appear on your customer’s bank statement. For Bacs payments this can be up to 10 characters, for SEPA payments the limit is 140 characters, and for Autogiro payments the limit is 11 characters. Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
links[mandate]
required ID of the mandate against which this payment should be collected.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payments()->create([
  "params" => ["amount" => 100,
               "currency" => "GBP",
               "metadata" => [
                 "order_dispatch_date" => "2016-08-04"
               ],
               "links" => [
                 "mandate" => "MD123"
               ]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payments.create(params={
  "amount": 100,
  "currency": "GBP",
  "charge_date": "2014-05-19",
  "reference": "WINEBOX001",
  "metadata": {
    "order_dispatch_date": "2014-05-22"
  },
  "links": {
    "mandate": "MD123"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payments.create(
  params: {
    amount: 1000,
    currency: "GBP",
    description: "Club membership fee",
    links: {
      mandate: "MD123"
    }
  },
  headers: {
    "Idempotency-Key": "aaf50eb0-8ddb-4900-a97b-40ed794570a1"
  }
)



POST https://api.gocardless.com/payments HTTP/1.1
{
  "payments": {
    "amount": 100,
    "currency": "GBP",
    "charge_date": "2014-05-19",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /payments/PM123
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-21",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }
}

List payments

Returns a cursor-paginated list of your payments.

Relative endpoint: GET /payments

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
creditor
ID of a creditor to filter payments by. If you pass this parameter, you cannot also pass customer.
currency
ISO 4217 currency code. Currently only “GBP”, “EUR”, and “SEK” are supported.
customer
ID of a customer to filter payments by. If you pass this parameter, you cannot also pass creditor.
limit
Number of records to return.
mandate
Unique identifier, beginning with “MD”.
status
One of:
  • pending_customer_approval: we’re waiting for the customer to approve this payment

  • pending_submission: the payment has been created, but not yet submitted to the banks

  • submitted: the payment has been submitted to the banks

  • confirmed: the payment has been confirmed as collected

  • paid_out: the payment has been included in a payout

  • cancelled: the payment has been cancelled

  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly

  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.

  • charged_back: the payment has been charged back

subscription
Unique identifier, beginning with “SB”.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payments()->list();

$client->payments()->list([
  "params" => ["customer" => "CU123"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payments.list().records

client.payments.list(params={"customer": "CU123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payments.list

@client.payments.list(params: { customer: "CU123" })

@client.payments.list.records.each { |payment| puts payment.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Payment payment : client.payments().all().withCustomer("CU123").execute()) {
  System.out.println(payment.getId());
}


GET https://api.gocardless.com/payments HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "payments": [{
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-15",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }]
}

Get a single payment

Retrieves the details of a single existing payment.

Relative endpoint: GET /payments/PM123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payments()->get("PM123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payments.get("PM123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payments.get("PM123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Payment payment = client.payments().get("PM123").execute();


GET https://api.gocardless.com/payments/PM123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-15",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }
}

Update a payment

Updates a payment object. This accepts only the metadata parameter.

Relative endpoint: PUT /payments/PM123

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payments()->update("PM123", [
  "params" => ["metadata" => ["internal_id" => "XX123"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payments.update("PM123", params={
  "metadata": {"key": "value"}
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payments.update(
  "PM123",
  params: {
    metadata: { order_id: "transaction-0HE9WQ0WDE" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.payments().update("PM123")
  .withMetadata("order_id", "transaction-0HE9WQ0WDE")
  .execute();


PUT https://api.gocardless.com/payments/PM123 HTTP/1.1
{
  "payments": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-15",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "key": "value"
    },
    "amount_refunded": 0,
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }
}

Cancel a payment

Cancels the payment if it has not already been submitted to the banks. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.

This will fail with a cancellation_failed error unless the payment’s status is pending_submission.

Relative endpoint: POST /payments/PM123/actions/cancel

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payments()->cancel("PM123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payments.cancel("PM123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payments.cancel("PM123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.payments().cancel("PM123").execute();


POST https://api.gocardless.com/payments/PM123/actions/cancel HTTP/1.1
{
  "data": {
    "metadata": {
      "ticket_id": "TK123"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-21",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "cancelled",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }
}

Retry a payment

Retries a failed payment if the underlying mandate is active. You will receive a resubmission_requested webhook, but after that retrying the payment follows the same process as its initial creation, so you will receive a submitted webhook, followed by a confirmed or failed event. Any metadata supplied to this endpoint will be stored against the payment submission event it causes.

This will return a retry_failed error if the payment has not failed.

Payments can be retried up to 3 times.

Relative endpoint: POST /payments/PM123/actions/retry

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payments()->retry("PM123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payments.retry("PM123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payments.retry("PM123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.payments().retry("PM123").execute();


POST https://api.gocardless.com/payments/PM123/actions/retry HTTP/1.1

{
  "data": {
    "metadata": {
      "reason": "Customer request"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-21",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "submitted",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }
}

Payouts

Payouts represent transfers from GoCardless to a creditor. Each payout contains the funds collected from one or many payments. Payouts are created automatically after a payment has been successfully collected.

Properties

id
Unique identifier, beginning with “PO”.
amount
Amount in pence or cents.
arrival_date
Date the payout is due to arrive in the creditor’s bank account. One of:
  • yyyy-mm-dd: the payout has been paid and is due to arrive in the creditor’s bank account on this day

  • null: the payout hasn’t been paid yet

created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. Currently only “GBP”, “EUR”, and “SEK” are supported.
deducted_fees
Fees that have already been deducted from the payout amount in pence or cents.

For each late_failure_settled or chargeback_settled action, we refund the transaction fees in a payout. This means that a payout can have a negative deducted_fees. This field is calculated as GoCardless fees + app fees - refunded fees

If the merchant is invoiced for fees separately from the payout, then deducted_fees will be 0.

reference
Reference which appears on the creditor’s bank statement.
status
One of:
  • pending: the payout has been created, but not yet sent to the banks

  • paid: the payout has been sent to the banks

links[creditor]
ID of creditor who will receive this payout, i.e. the owner of the creditor_bank_account.
links[creditor_bank_account]
ID of bank account which this will be sent to.

List payouts

Returns a cursor-paginated list of your payouts.

Relative endpoint: GET /payouts

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
creditor
Unique identifier, beginning with “CR”.
creditor_bank_account
Unique identifier, beginning with “BA”.
currency
ISO 4217 currency code. Currently only “GBP”, “EUR”, and “SEK” are supported.
limit
Number of records to return.
status
One of:
  • pending: the payout has been created, but not yet sent to the banks

  • paid: the payout has been sent to the banks


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payouts()->list();

$client->payouts()->list([
  "params" => ["creditor" => "CR123"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payouts.list().records

client.payouts.list(params={"status": "pending"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payouts.list

@client.payouts.list(params: { creditor_bank_account: "BA123" })

@client.payouts.list.records.each { |payout| puts payout.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Payout payout : client.payouts().all().withStatus("pending").execute()) {
  System.out.println(payout.getId());
}


GET https://api.gocardless.com/payouts HTTP/1.1

HTTP/1.1 200 (OK)
{
  "payouts": [{
    "id": "PO123",
    "amount": 1000,
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "reference": "ref-1",
    "status": "pending",
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }],
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  }
}

Get a single payout

Retrieves the details of a single payout. For an example of how to reconcile the transactions in a payout, see this guide.

Relative endpoint: GET /payouts/PO123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payouts()->get("PO123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payouts.get("PO123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payouts.get("PO123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.payouts().get("PO123").execute();


GET https://api.gocardless.com/payouts/PO123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "payouts": {
    "id": "PO123",
    "amount": 1000,
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "reference": "ref-1",
    "arrival_date": "2014-06-27",
    "status": "pending",
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Redirect Flows

Redirect flows enable you to use GoCardless’ hosted payment pages to set up mandates with your customers. These pages are fully compliant and have been translated into Dutch, French, German, Italian, Portuguese, Spanish and Swedish.

The overall flow is:

  1. You create a redirect flow for your customer, and redirect them to the returned redirect url, e.g. https://pay.gocardless.com/flow/RE123.

  2. Your customer supplies their name, email, address, and bank account details, and submits the form. This securely stores their details, and redirects them back to your success_redirect_url with redirect_flow_id=RE123 in the querystring.

  3. You complete the redirect flow, which creates a customer, customer bank account, and mandate, and returns the ID of the mandate. You may wish to create a subscription or payment at this point.

It is recommended that you link the redirect flow to your user object as soon as it is created, and attach the created resources to that user in the complete step.

Redirect flows expire 30 minutes after they are first created. You cannot complete an expired redirect flow.

Properties

id
Unique identifier, beginning with “RE”.
created_at
Fixed timestamp, recording when this resource was created.
description
A description of the item the customer is paying for. This will be shown on the hosted payment pages.
redirect_url
The URL of the hosted payment pages for this redirect flow. This is the URL you should redirect your customer to.
scheme
The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer’s bank account.
session_token
The customer’s session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.
success_redirect_url
The URL to redirect to upon successful mandate setup. You must use a URL beginning https in the live environment.
links[creditor]
The creditor for whom the mandate will be created. The name of the creditor will be displayed on the payment page.
links[customer]
ID of customer created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.
links[customer_bank_account]
ID of customer bank account created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.
links[mandate]
ID of mandate created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

Create a redirect flow

Creates a redirect flow object which can then be used to redirect your customer to the GoCardless hosted payment pages.

Relative endpoint: POST /redirect_flows

Parameters

description
A description of the item the customer is paying for. This will be shown on the hosted payment pages.
scheme
The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer’s bank account.
session_token
required The customer’s session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.
success_redirect_url
required The URL to redirect to upon successful mandate setup. You must use a URL beginning https in the live environment.
links[creditor]
The creditor for whom the mandate will be created. The name of the creditor will be displayed on the payment page. Required if your account manages multiple creditors.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->redirectFlows()->create([
  "params" => ["description" => "Wine boxes",
               "session_token" => "SESS_wSs0uGYMISxzqOBq",
               "success_redirect_url" => "https://example.com/pay/confirm"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.redirect_flows.create(params={
  "description": "Wine boxes",
  "session_token": "SESS_wSs0uGYMISxzqOBq",
  "success_redirect_url": "https://example.com/pay/confirm"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.redirect_flows.create(
  params: {
    description: "Team membership",
    session_token: "my_unique_tracking_id",
    success_redirect_url: "https://example.com/pay/confirm"
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

RedirectFlow redirectFlow = client.redirectFlows().create()
  .withDescription("Wine boxes")
  .withSessionToken("SESS_wSs0uGYMISxzqOBq")
  .withSuccessRedirectUrl("https://example.com/pay/confirm")
  .execute();


POST https://api.gocardless.com/redirect_flows HTTP/1.1

{
  "redirect_flows": {
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "success_redirect_url": "https://example.com/pay/confirm"
  }
}

HTTP/1.1 201 (Created)
Location: /redirect_flows/RE123
{
  "redirect_flows": {
    "id": "RE123",
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "scheme": null,
    "success_redirect_url": "https://example.com/pay/confirm",
    "redirect_url": "http://pay.gocardless.dev/flow/RE123",
    "created_at": "2014-10-22T13:10:06.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

Get a single redirect flow

Returns all details about a single redirect flow

Relative endpoint: GET /redirect_flows/RE123456


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->redirectFlows()->get("RE123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.redirect_flows.get("RE123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.redirect_flows.get("RE123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

RedirectFlow redirectFlow = client.redirectFlows.get("RE123").execute();


GET https://api.gocardless.com/redirect_flows/RE123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "redirect_flows": {
    "id": "RE123",
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "scheme": null,
    "success_redirect_url": "https://example.com/pay/confirm",
    "redirect_url": "http://pay.gocardless.dev/flow/RE123",
    "created_at": "2014-10-22T13:10:06.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

Complete a redirect flow

This creates a customer, customer bank account, and mandate using the details supplied by your customer and returns the ID of the created mandate.

This will return a redirect_flow_incomplete error if your customer has not yet been redirected back to your site, and a redirect_flow_already_completed error if your integration has already completed this flow. It will return a bad_request error if the session_token differs to the one supplied when the redirect flow was created.

Relative endpoint: POST /redirect_flows/RE123456/actions/complete

Parameters

session_token
required The customer’s session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->redirectFlows()->complete("RE123", [
  "params" => ["session_token" => "SESS_wSs0uGYMISxzqOBq"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.redirect_flows.complete("RE123", params={
  "session_token": "SESS_wSs0uGYMISxzqOBq"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.redirect_flows.complete(
  "RE123",
  params: {
    session_token: "my_unique_tracking_id"
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.redirectFlows().complete("RE123")
  .withSessionToken("SESS_wSs0uGYMISxzqOBq")
  .execute();


POST https://api.gocardless.com/redirect_flows/RE123/actions/complete HTTP/1.1

{
  "data": {
    "session_token": "SESS_wSs0uGYMISxzqOBq"
  }
}

HTTP/1.1 200 (OK)
{
  "redirect_flows": {
    "id": "RE123",
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "scheme": null,
    "success_redirect_url": "https://example.com/pay/confirm",
    "created_at": "2014-10-22T13:10:06.000Z",
    "links": {
      "creditor": "CR123",
      "mandate": "MD123",
      "customer": "CU123",
      "customer_bank_account": "BA123"
    }
  }
}

Refunds

Refund objects represent (partial) refunds of a payment back to the customer.

GoCardless will notify you via a webhook whenever a refund is created, and will update the amount_refunded property of the payment.

Properties

id
Unique identifier, beginning with “RF”.
amount
Amount in pence/cents/öre.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. This is set to the currency of the refund’s payment.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
reference
An optional refund reference, displayed on your customer’s bank statement. This can be up to 18 characters long for Bacs payments, 140 characters for SEPA payments, or 25 characters for Autogiro payments.
links[payment]
ID of the payment against which the refund is being made.

Create a refund

Creates a new refund object.

This fails with:

  • refund_payment_invalid_state error if the linked payment isn’t either confirmed or paid_out.

  • total_amount_confirmation_invalid if the confirmation amount doesn’t match the total amount refunded for the payment. This safeguard is there to prevent two processes from creating refunds without awareness of each other.

  • number_of_refunds_exceeded if five or more refunds have already been created against the payment.

Relative endpoint: POST /refunds

Restricted: this endpoint is disabled by default. You can contact us to request that we enable this for you.

Warning: a payment that has been (partially) refunded can still receive a late failure or chargeback from the customer’s bank.

Parameters

amount
required Amount in pence/cents/öre.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
reference
An optional refund reference, displayed on your customer’s bank statement. This can be up to 18 characters long for Bacs payments, 140 characters for SEPA payments, or 25 characters for Autogiro payments.
total_amount_confirmation
required Total expected refunded amount in pence/cents/öre. If there are other partial refunds against this payment, this value should be the sum of the existing refunds plus the amount of the refund being created.
links[payment]
required ID of the payment against which the refund is being made.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->refunds()->create([
  "params" => ["amount" => 100,
               "total_amount_confirmation" => 150,
               "reference" => "Nude Wines refund",
               "metadata" => ["reason" => "Late delivery"],
               "links" => ["payment" => "PM123"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.refunds().create()
  .withAmount(100)
  .withTotalAmountConfirmation(150)
  .withReference("Nude Wines refund")
  .withMetadata("reason", "late delivery")
  .withLinksPayment("PM123")
  .execute();



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.refunds.create(
  params: {
    amount: 100,
    total_amount_confirmation: 150,
    reference: "Service refund",
    metadata: { reason: "Late delivery" },
    links: { payment: "PM123"}
  }
)



POST https://api.gocardless.com/refunds HTTP/1.1
{
  "refunds": {
    "amount": 100,
    "total_amount_confirmation": 150,
    "reference": "Nude Wines refund",
    "metadata": {
      "reason": "late delivery"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /payments/RF123
{
  "refunds": {
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Nude Wines refund",
    "metadata": {
      "reason": "late delivery"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

List refunds

Returns a cursor-paginated list of your refunds.

Relative endpoint: GET /refunds

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
limit
Number of records to return.
payment
Unique identifier, beginning with “PM”.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->refunds()->list();

$client->refunds()->list([
  "params" => ["payment" => "PM123"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.refunds.list().records

client.refunds.list(params={"payment": "PM123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.refunds.list

@client.refunds.list(params: { payment: "PM123" })

@client.refunds.list.records.each { |refund| puts refund.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Refund refund : client.refunds().all().withPayment("PM123").execute()) {
  System.out.println(refund.getId());
}


GET https://api.gocardless.com/refunds HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "refunds": [{
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Nude Wines refund",
    "metadata": {
      "reason": "late failure"
    },
    "links": {
      "payment": "PM123"
    }
  }]
}

Get a single refund

Retrieves all details for a single refund

Relative endpoint: GET /refunds/RF123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->refunds()->get("RF123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.refunds.get("RF123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.refunds.get("RF123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Refund refund = client.refunds().get("RF123").execute();


GET https://api.gocardless.com/refunds/RF123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "refunds": {
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Nude Wines refund",
    "metadata": {
      "reason": "late failure"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

Update a refund

Updates a refund object.

Relative endpoint: PUT /refunds/RF123

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->refunds->update("RF123", [
  "params" => ["metadata" => ["key" => "value"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.refunds.update("RF123", params={
  "metadata": {"key": "value"}
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.refunds.update(
  "RF123",
  params: {
    metadata: { reason: "Late delivery", internal_code: "refund_1A" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.refunds().update("RF123")
  .withMetadata("internal_code", "refund_1A")
  .execute();


PUT https://api.gocardless.com/refunds/RF123 HTTP/1.1
{
  "refunds": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "refunds": {
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Nude Wines refund",
    "metadata": {
      "key": "value"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

Subscriptions

Subscriptions create payments according to a schedule.

Recurrence Rules

The following rules apply when specifying recurrence:

  • The first payment must be charged within 1 year.
  • When neither month nor day_of_month are present, the subscription will recur from the start_date based on the interval_unit.
  • If month or day_of_month are present, the recurrence rules will be applied from the start_date, and the following validations apply:
interval_unit month day_of_month
yearly optional (required if day_of_month provided) optional (required if month provided)
monthly invalid required
weekly invalid invalid

Examples:

interval_unit interval month day_of_month valid?
yearly 1 january -1 valid
yearly 1 march   invalid - missing day_of_month
monthly 6   12 valid
monthly 6 august 12 invalid - month must be blank
weekly 2     valid
weekly 2 october 10 invalid - month and day_of_month must be blank

Rolling dates

When a charge date falls on a non-business day, one of two things will happen:

  • if the recurrence rule specified -1 as the day_of_month, the charge date will be rolled backwards to the previous business day (i.e., the last working day of the month).
  • otherwise the charge date will be rolled forwards to the next business day.

    Properties

id
Unique identifier, beginning with “SB”.
amount
Amount in pence or cents.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. Currently only GBP and EUR are supported.
day_of_month
As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.
end_date
Date on or after which no further payments should be created. If blank, the subscription will continue forever. Alternatively, count can be set to achieve a specific number of payments.
interval
Number of interval_units between customer charge dates. Must result in at least one charge date per year. Defaults to 1.
interval_unit
The unit of time between customer charge dates. One of weekly, monthly or yearly.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
month
Name of the month on which to charge a customer. Must be lowercase.
name
Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
payment_reference
An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details. Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
start_date
The date on which the first payment should be charged. Must be within one year of creation and on or after the mandate’s next_possible_charge_date. When blank, this will be set as the mandate’s next_possible_charge_date.
status
One of:
  • pending_customer_approval: the subscription is waiting for customer approval before becoming active

  • customer_approval_denied: the customer did not approve the subscription

  • active: the subscription is currently active and will continue to create payments

  • finished: all of the payments scheduled for creation under this subscription have been created

  • cancelled: the subscription has been cancelled and will no longer create payments

upcoming_payments
Up to 10 upcoming payments with the amount, in pence, and charge date for each.

Each instance will contain these properties:

  • amount: The amount of this payment, in pence.

  • charge_date: The date on which this payment will be charged.

links[mandate]
ID of the associated mandate which the subscription will create payments against.

Create a subscription

Creates a new subscription object

Relative endpoint: POST /subscriptions

Parameters

amount
required Amount in pence or cents.
count
An alternative way to set end_date. The total number of payments that should be taken by this subscription. This will set end_date automatically.
currency
required ISO 4217 currency code. Currently only GBP and EUR are supported.
day_of_month
As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.
end_date
Date on or after which no further payments should be created. If blank, the subscription will continue forever. Alternatively, count can be set to achieve a specific number of payments.
interval
Number of interval_units between customer charge dates. Must result in at least one charge date per year. Defaults to 1.
interval_unit
required The unit of time between customer charge dates. One of weekly, monthly or yearly.
metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
month
Name of the month on which to charge a customer. Must be lowercase.
name
Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
payment_reference
An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details. Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
start_date
The date on which the first payment should be charged. Must be within one year of creation and on or after the mandate’s next_possible_charge_date. When blank, this will be set as the mandate’s next_possible_charge_date.
links[mandate]
required ID of the associated mandate which the subscription will create payments against.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->subscriptions()->create([
  "params" => ["amount" => 2500,
               "currency" => "GBP",
               "name" => "Monthly Magazine",
               "interval_unit" => "monthly",
               "day_of_month" => 1,
               "metadata" => ["order_no" => "ABCD1234"],
               "links" => ["mandate" => "MA123"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.subscriptions.create(params={
  "amount": "2500",
  "currency": "GBP",
  "name": "Monthly Magazine",
  "interval_unit": "monthly",
  "day_of_month":  "1",
  "metadata": {
    "order_no": "ABCD1234"
  },
  "links": {
    "mandate": "MA123"
  }
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.subscriptions.create(
  params: {
    amount: 2500,
    currency: "GBP",
    name: "Monthly magazine",
    interval_unit: "monthly",
    day_of_month: 1,
    links: {
      mandate: "MD123"
    }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Subscription subscription = client.subscriptions().create()
  .withAmount(2500)
  .withCurrency("GBP")
  .withName("Monthly Magazine")
  .withIntervalUnit("monthly")
  .withDayOfMonth(1)
  .withMetadata("order_no", "ABCD1234")
  .withLinksMandate("MD123")
  .execute();


POST https://api.gocardless.com/subscriptions HTTP/1.1

{
  "subscriptions": {
    "amount": "2500",
    "currency": "GBP",
    "name": "Monthly Magazine",
    "interval_unit": "monthly",
    "day_of_month":  "1",
    "metadata": {
      "order_no": "ABCD1234"
    },
    "links": {
      "mandate": "MA123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /subscriptions/SB123
{
  "subscriptions": {
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "active",
    "name": "Monthly Magazine",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "upcoming_payments": [
      { "charge_date": "2014-11-03", "amount": 2500 },
      { "charge_date": "2014-12-01", "amount": 2500 },
      { "charge_date": "2015-01-02", "amount": 2500 },
      { "charge_date": "2015-02-02", "amount": 2500 },
      { "charge_date": "2015-03-02", "amount": 2500 },
      { "charge_date": "2015-04-01", "amount": 2500 },
      { "charge_date": "2015-05-01", "amount": 2500 },
      { "charge_date": "2015-06-01", "amount": 2500 },
      { "charge_date": "2015-07-01", "amount": 2500 },
      { "charge_date": "2015-08-03", "amount": 2500 }
    ],
    "metadata": {
      "order_no": "ABCD1234"
    },
    "links": {
      "mandate": "MA123"
    }
  }
}

List subscriptions

Returns a cursor-paginated list of your subscriptions.

Relative endpoint: GET /subscriptions

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at[gt]
Limit to records created after the specified date-time.
created_at[gte]
Limit to records created on or after the specified date-time.
created_at[lt]
Limit to records created before the specified date-time.
created_at[lte]
Limit to records created on or before the specified date-time.
customer
Unique identifier, beginning with “CU”.
limit
Number of records to return.
mandate
Unique identifier, beginning with “MD”.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->subscriptions()->list();

$client->subscriptions()->list([
  "params" => ["customer" => "CU123"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.subscriptions.list().records

client.subscriptions.list(params={"customer": "CU123"}).records



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.subscriptions.list

@client.subscriptions.list(params: { customer: "CU123" })

@client.subscriptions.list.records.each { |subscription| puts subscription.inspect }



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

for (Subscription subscription : client.subscriptions().all().withCustomer("CU123").execute()) {
  System.out.println(subscription.getId());
}


GET https://api.gocardless.com/subscriptions HTTP/1.1

HTTP/1.1 200 (OK)
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "subscriptions": [{
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "active",
    "name": "Monthly Magazine",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "upcoming_payments": [
      { "charge_date": "2014-11-03", "amount": 2500 },
      { "charge_date": "2014-12-01", "amount": 2500 },
      { "charge_date": "2015-01-02", "amount": 2500 },
      { "charge_date": "2015-02-02", "amount": 2500 },
      { "charge_date": "2015-03-02", "amount": 2500 },
      { "charge_date": "2015-04-01", "amount": 2500 },
      { "charge_date": "2015-05-01", "amount": 2500 },
      { "charge_date": "2015-06-01", "amount": 2500 },
      { "charge_date": "2015-07-01", "amount": 2500 },
      { "charge_date": "2015-08-03", "amount": 2500 }
    ],
    "metadata": {
      "order_no": "ABCD1234"
    },
    "links": {
      "mandate": "MA123"
    }
  }]
}

Get a single subscription

Retrieves the details of a single subscription.

Relative endpoint: GET /subscriptions/SB123


$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->subscriptions()->get("SB123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.subscriptions.get("SB123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.subscriptions.get("SB123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

Subscription subscription = client.subscriptions().get("SB123").execute();


GET https://api.gocardless.com/subscriptions/SB123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "subscriptions": {
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "active",
    "name": "Monthly Magazine",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "upcoming_payments": [
      { "charge_date": "2014-11-03", "amount": 2500 },
      { "charge_date": "2014-12-01", "amount": 2500 },
      { "charge_date": "2015-01-02", "amount": 2500 },
      { "charge_date": "2015-02-02", "amount": 2500 },
      { "charge_date": "2015-03-02", "amount": 2500 },
      { "charge_date": "2015-04-01", "amount": 2500 },
      { "charge_date": "2015-05-01", "amount": 2500 },
      { "charge_date": "2015-06-01", "amount": 2500 },
      { "charge_date": "2015-07-01", "amount": 2500 },
      { "charge_date": "2015-08-03", "amount": 2500 }
    ],
    "metadata": {
      "order_no": "ABCD1234"
    },
    "links": {
      "mandate": "MA123"
    }
  }
}

Update a subscription

Updates a subscription object.

Relative endpoint: PUT /subscriptions/SB123

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
name
Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
payment_reference
An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details. Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->subscriptions()->update("SB123", [
  "params" => ["name" => "New name",
               "metadata" => ["order_no" => "ABCD4321"]]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.subscriptions.update("SB123", params={
  "name": "New name"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.subscriptions.update(
  "SB123",
  params: {
    metadata: { order_no: "ABCD4321" }
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.subscriptions().update("SB123")
  .withName("New name")
  .execute();


PUT https://api.gocardless.com/subscriptions/SU123 HTTP/1.1

{
  "subscriptions": {
    "name": "New name",
    "metadata": {
      "order_no": "ABCD4321"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "subscriptions": {
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "active",
    "name": "New name",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "upcoming_payments": [
      { "charge_date": "2014-11-03", "amount": 2500 },
      { "charge_date": "2014-12-01", "amount": 2500 },
      { "charge_date": "2015-01-02", "amount": 2500 },
      { "charge_date": "2015-02-02", "amount": 2500 },
      { "charge_date": "2015-03-02", "amount": 2500 },
      { "charge_date": "2015-04-01", "amount": 2500 },
      { "charge_date": "2015-05-01", "amount": 2500 },
      { "charge_date": "2015-06-01", "amount": 2500 },
      { "charge_date": "2015-07-01", "amount": 2500 },
      { "charge_date": "2015-08-03", "amount": 2500 }
    ],
    "metadata": {
      "order_no": "ABCD4321"
    },
    "links": {
      "mandate": "MA123"
    }
  }
}

Cancel a subscription

Immediately cancels a subscription; no more payments will be created under it. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.

This will fail with a cancellation_failed error if the subscription is already cancelled or finished.

Relative endpoint: POST /subscriptions/SB123/actions/cancel

Parameters

metadata
Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->subscriptions()->cancel("SB123");



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.subscriptions.cancel("SB123")



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.subscriptions.cancel("SB123")



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

client.subscriptions().cancel("SB123").execute();


POST https://api.gocardless.com/subscriptions/SU123/actions/cancel HTTP/1.1

HTTP/1.1 200 (OK)
{
  "subscriptions": {
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "cancelled",
    "name": "Monthly Magazine",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "upcoming_payments": [],
    "metadata": {
      "order_no": "ABCD1234"
    },
    "links": {
      "mandate": "MA123"
    }
  }
}

Helper Endpoints

Bank Details Lookups

Look up the name and reachability of a bank.

Properties

available_debit_schemes
Array of schemes supported for this bank account. This will be an empty array if the bank account is not reachable by any schemes.

Each instance will contain these properties:

bank_name
The name of the bank with which the account is held (if available).
bic
ISO 9362 SWIFT BIC of the bank with which the account is held.

Perform a bank details lookup

Performs a bank details lookup.

As part of the lookup a modulus check and reachability check are performed.

Bank account details may be supplied using local details or an IBAN.

Note: Usage of this endpoint is monitored. If your organisation relies on GoCardless for modulus or reachability checking but not for payment collection, please get in touch.

Relative endpoint: POST /bank_details_lookups

Parameters

account_number
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_code
Bank code - see local details for more information. Alternatively you can provide an iban.
branch_code
Branch code - see local details for more information. Alternatively you can provide an iban.
country_code
ISO 3166-1 alpha-2 code. Must be provided if specifying local details.
iban
International Bank Account Number. Alternatively you can provide local details.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->bankDetailsLookups()->create([
  "params" => ["account_number" => "55779911",
               "branch_code" => "200000",
               "country_code" => "GB"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.bank_details_lookups.create(params={
  "account_number": "55779911",
  "branch_code": "200000",
  "country_code": "GB"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.bank_details_lookups.create(
  params: {
    country_code: "GB",
    account_number: "55779911",
    branch_code: "200000"
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

BankDetailsLookup bankDetailsLookup = client.bankDetailsLookups().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .execute();


POST https://api.gocardless.com/bank_details_lookups HTTP/1.1
{
  "bank_details_lookups": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB"
  }
}

HTTP/1.1 200 (OK)
{
  "bank_details_lookups": {
    "available_debit_schemes": ["bacs"],
    "bank_name": "BARCLAYS BANK PLC",
    "bic": "BARCGB22XXX"
  }
}


Mandate PDFs

Mandate PDFs allow you to easily display scheme-rules compliant Direct Debit mandates to your customers.

Properties

expires_at
The date and time at which the url will expire (10 minutes after the original request).
url
The URL at which this mandate PDF can be viewed until it expires at the date and time specified by expires_at. You should not store this URL or rely on its structure remaining the same.

Create a mandate PDF

Generates a PDF mandate and returns its temporary URL.

Customer and bank account details can be left blank (for a blank mandate), provided manually, or inferred from the ID of an existing mandate.

To generate a PDF mandate in a foreign language, set your Accept-Language header to the relevant ISO 639-1 language code. Supported languages are Dutch, English, French, German, Italian, Portuguese, Spanish and Swedish.

Relative endpoint: POST /mandate_pdfs

Parameters

account_holder_name
Name of the account holder, as known by the bank. Usually this matches the name of the customer. This field cannot exceed 18 characters.
account_number
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_code
Bank code - see local details for more information. Alternatively you can provide an iban.
bic
SWIFT BIC. Will be derived automatically if a valid iban or local details are provided.
branch_code
Branch code - see local details for more information. Alternatively you can provide an iban.
country_code
ISO 3166-1 alpha-2 code. Required if providing local details.
iban
International Bank Account Number. Alternatively you can provide local details. IBANs cannot be provided for Autogiro mandates.
mandate_reference
Unique 6 to 18 character reference. This may be left blank at the point of signing.
scheme
Direct Debit scheme. Can be supplied or automatically detected from the bank account details provided. If you do not provide a scheme, you must provide either a mandate, an iban, or local details including a country_code.
signature_date
If provided, a form will be generated with this date and no signature field.
swedish_identity_number
For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Can only be supplied for Autogiro mandates.
links[mandate]
ID of an existing mandate to build the PDF from. The customer’s bank details will be censored in the generated PDF. No other parameters may be provided alongside this.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandatePdfs()->create([
  "params" => ["links" => ["mandate" => "MD123"]]
]);

$client->mandate_pdfs()->create([
  "params" => ["account_number" => "44779911",
               "branch_code" => "200000",
               "country_code" => "GB"]
]);



import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandate_pdfs.create(params={
  "links": {"mandate": "MD123"}
})

client.mandate_pdfs.create(params={
  "account_number": "44779911",
  "branch_code": "200000",
  "country_code": "GB"
})



@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandate_pdfs.create(
  params: {
    links: { mandate: "MD123" }
  }
)

@client.mandate_pdfs.create(
  params: {
    account_number: "55779911",
    branch_code: "200000",
    country_code: "GB"
  }
)



import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient.create(accessToken, SANDBOX);

MandatePdf mandatePdfForMandate = client.mandatePdfs().create()
  .withLinksMandate("MD123")
  .execute();

MandatePdf mandatePdfForBankDetails = client.mandatePdfs.create()
  .withAccountNumber("44779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .execute();


POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
{
  "mandate_pdfs": {
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 200 (OK)
{
  "mandate_pdfs": {
    "url": "http://mandate-previews.gocardless.com/?token=lhulxcPEbT9v3W0QUpBOxhlGUSYEayQQ4VVrpO7YnUKRYynP5",
    "expires_at": "2014-05-08T17:01:06.000Z"
  }
}

POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
{
  "mandate_pdfs": {
    "account_number": "44779911",
    "branch_code": "200000",
    "country_code": "GB"
  }
}

HTTP/1.1 200 (OK)
{
  "mandate_pdfs": {
    "url": "http://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5",
    "expires_at": "2014-05-08T17:01:06.000Z"
  }
}

POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
{
  "mandate_pdfs": {
    "account_number": "44779911",
    "branch_code": "200000",
    "country_code": "GB",
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 400 (Bad Request)
{
  "error": {
    "message": "Cannot provide both a mandate and other details",
    "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
    "type": "validation_failed",
    "request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
    "code": 422,
    "errors": [
      {
        "reason": "validation_failed",
        "message": "Cannot provide both a mandate and other details"
      }
    ]
  }
}

Appendix

Webhooks

Check out our getting started guide for a step-by-step introduction to handling webhooks, with PHP, Ruby, Python and Java code samples

Overview

Webhooks notify you of new events in your GoCardless account (e.g., when the bank informs us that one of your payments has failed).

You can enable webhooks by creating a Webhook Endpoint in your GoCardless dashboard.

When an event occurs to a mandate or payment in your GoCardless account, a webhook will be sent to every enabled webhook endpoint as a POST request, which contains a list of events.

There are a few other things to note when using webhooks:

  • Webhooks may arrive out of order.

  • Webhooks may contain multiple events. These events need not have anything in common (i.e., they may be for different actions and resources).

  • Webhooks with an invalid signature must return a 498 Token Invalid error.

  • Webhooks about unknown events should be ignored, and return 204 No Content. GoCardless may add new events to the API without considering this a backwards incompatible change.

  • You must use SSL/TLS for webhook URLs. Unsecured webhook URLs are only allowed in the sandbox environment.

  • All the webhooks you’ve ever been sent are viewable in your GoCardless dashboard in the “Developers” area.

Status codes

Your webhook handler should return a response with a 2xx status code, e.g. 200 OK, or 204 No Content. If the webhook signature is invalid, you should return a 498 Invalid Token

Errors & Retries

In the event we fail to deliver the webhook, or you respond with a non 2xx status code, we will attempt to resend the webhook up to 10 times at increasing time intervals.

You can view webhooks we’ve sent you in your GoCardless dashboard, and can retry them if required.

IP whitelisting

We send webhooks from the following IP addresses which you may wish to whitelist in your firewall:

  • 37.58.102.70
  • 37.58.102.71

We will provide advance notification by email at least two weeks before we make any changes to these addresses.

You can set the email we will contact you at from your Dashboard - simply click “Settings” in the top-right hand corner, then “Contact preferences”, and then edit your developer contact.

Signing webhooks

We sign the body of the POST request with an HMAC SHA256 hex digest, using the secret of the webhook endpoint for which this webhook is being sent. This is done using two additional headers:

Webhook-Signature
The HMAC SHA256 hex digest of the request body.

You must check that the webhook has a valid signature before processing it. Here’s how you could do that in Ruby:

# request_signature - the signature sent in Webhook-Signature
#      request_body - the JSON body of the webhook request
#            secret - the secret for the webhook endpoint

require "openssl"

digest = OpenSSL::Digest.new("sha256")
calculated_signature = OpenSSL::HMAC.hexdigest(digest, secret, request_body)

if calculated_signature == request_signature
  # Signature ok!
else
  # Invalid signature. Ignore the webhook and return 498 Token Invalid
end

Examples

Payments

In this example, you have set up two customers, and each has a mandate. You created a payment for each customer, called “Test Payment” and “Test Payment 2” respectively. A few days later, these have been collected, and this has generated a payment update event for those payments. You have created a webhook endpoint, with id WE123, secret 123ABC456DEF, and url “https://example.com/webhooks”.

We will send a POST request, like the one on the right, to https://example.com/webhooks. To process it, you should:

  1. Check the signature
  2. Check that you have not already processed this event when receiving the same webhook for a different webhook endpoint
  3. Fetch the updated resource, using the ID supplied, and check that it has not changed further since the webhook was sent (since webhooks may arrive out of order)
  4. Act on the event, e.g. shipping goods, extending subscription
  5. Return 204 No Content
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 86f8bb84a4de63cff4af48f22b64b20970b415b066e3d21459ea515052860514
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-03T12:00:00.000Z",
      "action": "confirmed",
      "resource_type": "payments",
      "links": {
        "payment": "PM123"
      },
      "details": {
        "origin": "gocardless",
        "cause": "payment_confirmed",
        "description": "Payment was confirmed as collected"
      }
    },
    {
      "id": "EV456",
      "created_at": "2014-08-03T12:00:00.000Z",
      "action": "failed",
      "resource_type": "payments",
      "links": {
        "payment": "PM456"
      },
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "Customer cancelled the mandate at their bank branch.",
        "scheme": "bacs",
        "reason_code": "ARUDD-1"
      }
    }
  ]
}

Mandates

In this example a customer has two mandates, and has just closed their bank account. Both mandates were cancelled by their bank, and this is being passed on through GoCardless via a webhook, using the same webhook endpoint as in the previous example. Once again, you should:

  1. Check the signature
  2. Check that you have not already processed this event
  3. Fetch the resource, using the ID in the webhook, to check that it has not further changed (since webhooks may arrive out of order)
  4. Act on the event
  5. Return 204 No Content
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 78e3507f61f141046969c73653402cb50b714f04322da04d766ee0f6d2afe65f
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-04T12:00:00.000Z",
      "action": "cancelled",
      "resource_type": "mandates",
      "links": {
        "mandate": "MD123"
      },
      "details": {
        "origin": "bank",
        "cause": "bank_account_disabled",
        "description": "Your customer closed their bank account.",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      }
    },
    {
      "id": "EV456",
      "created_at": "2014-08-04T12:00:00.000Z",
      "action": "expired",
      "resource_type": "mandates",
      "links": {
        "mandate": "MD456"
      },
      "details": {
        "origin": "gocardless",
        "cause": "mandate_expired",
        "description": "The mandate expired due to inactivity."
      }
    }
  ]
}

Payouts

In this example, your payments have been collected by GoCardless, and are now ready to be paid out into the associated creditor bank account. This payout has just been generated, which triggers a webhook using the same webhook endpoint as in the previous examples. Once again you should:

  1. Check the signature
  2. Check that you have not already processed this event
  3. Fetch the resource, using the ID in the webhook, to check that it has not further changed (since webhooks may arrive out of order)
  4. Act on the event
  5. Return 204 No Content
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: b2e7e901d0cd0792ac070b933591030543cfd2eae7c57103709eadcff10d99fb
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-04T12:00:00.000Z",
      "action": "paid",
      "resource_type": "payouts",
      "links": {
        "payout": "PO123"
      }
    }
  ]
}

Subscriptions

In this example a subscription has just raised a payment, which triggers a webhook using the same webhook endpoint as in the previous examples. Once again you should:

  1. Check the signature
  2. Check that you have not already processed this event
  3. Fetch the resource, using the ID in the webhook, to check that it has not further changed (since webhooks may arrive out of order)
  4. Act on the event
  5. Return 204 No Content
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 68cfef92b143649f4ce9b9e4b3d182b879be77625bcd0b3ff1f37849d01f76e6
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-04T12:00:00.000Z",
      "action": "payment_created",
      "resource_type": "subscriptions",
      "links": {
        "subscription": "SB123",
        "payment": "PM123"
      }
    }
  ]
}

JavaScript Flow

You can use our JavaScript flow to create custom payment pages. Our JavaScript library will send sensitive bank details to our servers directly and return a token that can be used to create a customer bank account.

The API allows you to create and show your customer bank account tokens.

Restricted: the JavaScript Flow is restricted to GoCardless Pro accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.

Customer Bank Account Tokens

Customer bank account tokens can only be used once. Attempting to create a second customer bank account from the same customer bank account token will result in a customer_bank_account_token_used error.

Properties

id
Unique identifier, beginning with “AT”.
created_at
Fixed timestamp of when the customer bank account token was originally created.
links[customer_bank_account]
ID of customer bank account that was created from this token.
Note: this property will only be present if this token has been used to create a customer bank account.

Create a customer bank account token

Creates a new customer bank account token object.

Relative endpoint: /customer_bank_account_tokens

Note: The customer bank account token API is currently in beta and will change.
We may not honour the usual backwards compatibility practice, however we will do our best to inform you of upcoming changes.

JSONP only: it is currently only possible to create customer bank account tokens using JSONP.

GoCardless performs modulus checks on all bank details. For testing purposes, you can use: - Sort code: 200000 - Account number: 55779911

The overall flow is:

  1. You render a payment form with a publishable access token embedded on the page.

  2. Your customer supplies their bank account details and submits the form. The form submission needs to be intercepted in JavaScript and submitted using our JavaScript library; on success you should inject the created token into the form and complete the submission to your server.

  3. You create a customer bank account passing in the token in place of bank account details.

Intercepting form submission with pay.gocardless/js

Parameters

Bank account details may either be supplied using the IBAN (international bank account number), or local details. For more information on the different fields required in each country, please see the local bank details section.

publishable_access_token
required can only be sent as a top level parameter in a JSONP GET request.
account_number
Bank account number.
bank_code
Bank identifying code.
branch_code
Branch identifying code.
iban
Valid international bank account number.
country_code
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
currency
ISO 4217 currency code, defaults to national currency of country_code.
account_holder_name
required Name of the account holder, as it appears with the bank. This may not be more than 18 characters.
<!DOCTYPE html>
<html>
  <body>
  <script src="https://pay.gocardless.com/js/beta"></script>
  <form id="form"
    action="/complete"
    method="post"
    onsubmit="onSubmit(event)">
    <input name="publishable_access_token" id="publishable_access_token" type="hidden"
       value="JF00001078YEW7VHAH0RA4Z73J7PYBYN">
    <input name="given_name" id="given_name" type="text">
    <input name="family_name" id="family_name" type="text">
    <input name="address_line1" id="address_line1" type="text">
    <input name="city" id="city" type="text">
    <input name="postal_code" id="postal_code" type="text">
    <input name="country_code" id="country_code" type="text">
    <input id="account_number" type="text">
    <input id="bank_code" type="text">
    <input id="branch_code" type="text">
    <input id="iban" type="text">
    <input id="account_holder_name" type="text">
    <input id="bank_accounts_country_code" type="text">
    <input type="submit" value="Continue">
    <h1 id="error"></h1>
  </form>

  <script>
  function onSubmit(event) {
    var form = event.target;
    var publishableAccessToken = document.getElementById('publishable_access_token').value;

    GoCardless.customerBankAccountTokens.create({
      publishable_access_token: publishableAccessToken,
      customer_bank_account_tokens: {
        account_number: document.getElementById('account_number').value,
        bank_code: document.getElementById('bank_code').value,
        branch_code: document.getElementById('branch_code').value,
        iban: document.getElementById('iban').value,
        account_holder_name: document.getElementById('account_holder_name').value,
        country_code: document.getElementById('bank_accounts_country_code').value
      }
    }, function(response) {
      if (response.error) {
        document.getElementById('error')
          .textContent = 'Error: ' + response.error.message;
      } else {
        var input = document.createElement('input');
        input.type = 'hidden';
        input.value = response.customer_bank_account_tokens.id;
        input.name = 'customer_bank_account_token';
        form.appendChild(input);

        form.submit();
      }
    });

    // Prevent form submission
    event.preventDefault();
  }
  </script>
  </body>
</html>

Creating a customer bank account after the form is submitted.

require "gocardless_pro"
require "sinatra"

post "/complete" do

  client = GoCardlessPro::Client.new(access_token: "access_token")

  customer_params = {
    email: params[:email],
    given_name: params[:given_name],
    family_name: params[:family_name],
    address_line1: params[:address_line1],
    city: params[:city],
    postal_code: params[:postal_code],
    country_code: params[:country_code],
  }

  customer = client.customers.create(params: customer_params)

  customer_bank_account_params = {
    links: {
      customer: customer.id,
      customer_bank_account_token: params[:customer_bank_account_token]
    }
  }

  customer_bank_account = client.customer_bank_accounts.create(
    params: customer_bank_account_params
  )

  new_mandate = client.mandates.create(params: {
    links: {
      customer_bank_account: customer_bank_account.id
    }
  })

  puts new_mandate.inspect

  "Thanks!"
end

Get a single customer bank account token

Retrieves the details of an existing customer bank account token.

Relative endpoint: GET /customer_bank_account_tokens/AT123

GET https://api.gocardless.com/customer_bank_account_tokens/AT123 HTTP/1.1

HTTP/1.1 200 (OK)
{
  "customer_bank_account_tokens": {
    "id": "AT123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "links": {
      "customer_bank_account": "BA123"
    }
  }
}

OAuth

Check out our getting started guide for a step-by-step introduction to building an OAuth integration, with PHP, Ruby, Python and Java code samples

OAuth 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.

The GoCardless OAuth API conforms to the OAuth spec, and can be used with OAuth client libraries available in most languages.

The base URLs for the GoCardless OAuth API are:

  • https://connect.gocardless.com for live
  • https://connect-sandbox.gocardless.com for sandbox

The OAuth flow

The flow to link a GoCardless account to your app is as follows:

  1. The user clicks a link on your site to the GoCardless OAuth flow. The link includes details of your app as well as a scope which defines the level of access you want the user to authorise.
  2. On the GoCardless OAuth page, the user logs in to their GoCardless account, or creates a new one, and agrees to connect their account to your app.

OAuth flow

  1. The user, having agreed that they’d like to connect to your app, is redirected back to your site with a code.
  2. Your site exchanges the code for a permanent access_token which can be stored and used to make requests to the API on the user’s behalf.
  3. You can then make API requests using the user’s access token and receive webhooks relating to their account.

You can try the process for yourself by connecting your sandbox account to our example app. The source code, written in Ruby, is available here - it provides a good introduction to creating your own OAuth app.

Creating an OAuth app

To get started, you’ll need a GoCardless account. If you haven’t already, you can sign up here to get one. Once you’re logged into your account, you can create apps from the developer section of your dashboard

When you do this, you’ll be issued a client_id and client_secret, each 64 characters long, which you’ll use to identify your integration when requesting access to other users’ GoCardless accounts.

An authorisation link takes your user to the GoCardless OAuth flow, where they may agree to connect their GoCardless account to your app. It includes details of your app and the level of access requested.

To construct an authorisation link, take the relevant OAuth base URL plus the relative endpoint /oauth/authorize with the following querystring parameters. You should redirect your user to this link using a GET request.

Parameters

response_type
required The kind of OAuth request you’re making - only code is supported.
client_id
required The client_id of your app.
scope
required The level of access you want to your users’ GoCardless accounts - this may either be read_write or read_only.
redirect_uri
required The URL to send your users to once they’ve agreed to connect their account to GoCardless (as well if they deny authorisation or something goes wrong, in which case we’ll pass you details of the error). This must exactly match the one stored on your app.
state
An optional random string. If provided, this will be passed back to your redirect_uri. We recommend using this parameter for a CSRF token.
prefill[email]
Your user’s email address. We will pre-fill this on the authorisation page to make it quicker and easier for them to complete the flow.
initial_view
An optional parameter, set to either signup or login to specify which view we should show when your user enters the OAuth flow. By default, they will see the login view if you’re requesting read_only access and the signup view if requesting read_write.
GET https://connect.gocardless.com/oauth/authorize HTTP/1.1
  response_type=code&
  client_id=sx6WHUAVMUrinkJNJn8DotVFm&
  scope=read_write&
  redirect_uri=http%3A%2F%2Flocalhost%2Fcallback&
  state=q8wEr9yMohTP&
  prefill[email]=tim%40gocardless.com

Handling the redirect back to you

Once the user has connected their GoCardless account to your app, they’ll be redirected to your redirect_uri.

In the querystring, you will be passed a code, which you must exchange for a long-lived access token within 5 minutes. If you provided a state in the original redirect to GoCardless, this will be passed back to you.

Errors

If the user denies your request to connect, or some other kind of error occurs (for example you specify an invalid scope or response_type is missing), the user will be redirected back to you with an error and error_description, per the OAuth spec.

error will be set to one of the following, and there will be a human-readable error_description which you may wish to store to refer to in case of errors:

invalid_request
You failed to provide either a scope or a response_type.
invalid_scope
You provided a scope other than read_only or read_write.
unsupported_response_type
You provided a response_type other than code.
access_denied
The user chose not to connect their account to your app.
GET https://localhost/callback HTTP/1.1
  code=6NJiqXzT7HcgEGsAZXUmaBfB&
  state=q8wEr9yMohTP

GET https://localhost/callback HTTP/1.1
  error=access_denied&
  error_description=The%20user%20cancelled%20the%20authorisation%20process.

Exchanging an authorisation code for an access token

Exchanges the authorisation code passed to you in the redirect for an access token which you may store and use to make future requests on the user’s behalf.

Relative endpoint: POST /oauth/access_token

Parameters

grant_type
required The kind of OAuth grant you’ve received - this will be authorization_code.
code
required The authorisation code that resulted from the user agreeing to connect their account to your app, passed to you in the querystring as code. This will expire after 5 minutes, so you should exchange it for an access token immediately.
redirect_uri
required The redirect_uri set on your app, and which you provided when sending your user to the OAuth flow.
client_id
required The client_id for your registered app.
client_secret
required The client_secret for your registered app.

Response

Following the OAuth spec, this endpoint responds with JSON including an access_token if successful.

access_token
Your permanent access token for authenticating on behalf of the user. You should store this for future use.
scope
The scope of the access token, as originally requested (either read_write or read_only).
token_type
The type of token you’ve been issued - this will be bearer.
organisation_id
The ID of the GoCardless account to which you have been connected. You should store this for future use, as you will need it to identify to which of your users a webhook relates.

Errors

In case of an error, the endpoint responds with JSON including an error and human-readable error_description. error may contain one of the following:

invalid_request
You have not provided at least one of the required parameters (grant_type, code, redirect_uri, client_id and client_secret).
unsupported_grant_type
You provided a grant_type other than authorization_code.
invalid_client
The client_id and client_secret you provided to authenticate as your app were invalid or refer to a disabled app.
invalid_grant
The code you provided has already been used, has expired, or the redirect_uri you provided does not match the one originally provided when passing the user to GoCardless.
POST https://connect.gocardless.com/oauth/access_token HTTP/1.1
  grant_type=authorization_code&
  code=6NJiqXzT7HcgEGsAZXUmaBfB&
  redirect_uri=http%3A%2F%2Flocalhost%2Fcallback&
  client_id=sx6WHUAVMUrinkJNJn8DotVFm&
  client_secret=exaxerfrWrPdxADDUBWVqGbPbF

HTTP/1.1 200 (OK)
{
  "access_token": "e72e16c7e42f292c6912e7710c123347ae178b4a",
  "scope": "read_write",
  "token_type": "bearer",
  "organisation_id": "OR123"
}

POST https://connect.gocardless.com/oauth/access_token HTTP/1.1
  grant_type=authorization_code&
  code=goQcmyY8MebbAuKy8L&
  redirect_uri=http%3A%2F%2Flocalhost%2Fcallback&
  client_id=sx6WHUAVMUrinkJNJn8DotVFm&
  client_secret=exaxerfrWrPdxADDUBWVqGbPbF

HTTP/1.1 400 (Bad Request)
{
  "error": "invalid_grant",
  "error_description": "code has already been used"
}

Making requests

You can now make standard API requests using the access token you received in exchange for the authorisation code. This will allow you to view and manipulate (depending on the scope you requested) the user’s data.

As with elsewhere in the API, the access token must be provided in an Authorization request header, using the bearer authentication scheme.

Authorization: Bearer e72e16c7e42f292c6912e7710c123347ae178b4a

Any errors generated by requests using your users’ access tokens will follow the usual structure of errors in the GoCardless API, as opposed to the OAuth-specific errors above.

If you receive an unexpected 401 Unauthorized response, this usually means that your user has revoked authorisation (unless you have disabled the app yourself from your dashboard). Users will need to go through the authorisation flow again in order for you to obtain a new access token.

If you receive an unexpected 403 Forbidden response for an endpoint your app is authorised to access (see below), this may indicate that your user’s account is under review. The user will have been informed by GoCardless that they need to provide additional information to re-enable their account.

Restricted: In the current version of the OAuth flow, you will not be able to access the following API endpoints on behalf of organisations connected to your app:

  • Creditor (all endpoints)
  • Creditor Bank Account (all endpoints)

Further, unless your app’s payment pages that have been approved as scheme rules compliant by our sponsor bank you must use GoCardless’s hosted payment pages (via the Redirect Flow API). As such, the following endpoints will also be restricted:

  • Mandate (create and reinstate)
  • Customer (create)
  • Customer bank account (create)
POST https://api.gocardless.com/customers/ HTTP/1.1
Authorization: Bearer e72e16c7e42f292c6912e7710c123347ae178b4a
HTTP/1.1 200 (OK)

GET https://api.gocardless.com/payments/ HTTP/1.1
Authorization: Bearer access_token_which_has_been_revoked
HTTP/1.1 401 (Unauthorized)

Receiving webhooks

If you’ve provided a webhook URL for your app, we’ll notify you of new events relating to the GoCardless accounts of your users. For details on how webhooks work and how to process them, see the guide.

The events we send you will be identical to those described, but with an additional links[organisation] attribute allowing you to identify which of your users a webhook relates to.

The organisation ID is provided when exchanging an authorisation code for an access token and if you expect to interact with webhooks, you should store it then for future reference.

POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 86f8bb84a4de63cff4af48f22b64b20970b415b066e3d21459ea515052860514
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-03T12:00:00.000Z",
      "action": "confirmed",
      "resource_type": "payments",
      "links": {
        "payment": "PM123",
        "organisation": "OR123"
      },
      "details": {
        "origin": "gocardless",
        "cause": "payment_confirmed",
        "description": "Payment was confirmed as collected"
      }
    },
    {
      "id": "EV456",
      "created_at": "2014-08-03T12:00:00.000Z",
      "action": "failed",
      "resource_type": "payments",
      "links": {
        "payment": "PM456",
        "organisation": "OR456"
      },
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "Customer cancelled the mandate at their bank branch.",
        "scheme": "bacs",
        "reason_code": "ARUDD-1"
      }
    }
  ]
}

App Fees

If your OAuth app is creating payments on behalf of your users you may wish to add on a fee in addition to the fee that GoCardless charges.

When an OAuth app creates a payment, it can specify an app_fee. This is an amount in pence or cents that will be deducted from the amount that the user receives. A fee charged by an app must be no more than 50% of the total payment amount.

App fees will be collated in a payout and paid out. App fee payouts are created and paid out daily, as with other payouts.

POST https://api.gocardless.com/payments HTTP/1.1
{
  "payments": {
    "app_fee": 10,
    "amount": 100,
    "currency": "GBP",
    "links": {
      "mandate": "MD123"
    }
  }
}

Compliance requirements

When building a Direct Debit integration your payment pages and notifications need to comply with scheme-level rules. To help you design compliant pages quickly we have a series of guides:

Payment pages
Bacs requirements, SEPA requirements, Autogiro requirements
Customer notifications
Bacs requirements, SEPA requirements, Autogiro requirements

Before your account can be set to “live” our sponsor bank will need to sign off your compliance in the above areas.

Alternatively, you may wish to use the Redirect Flow API, which enables you to use payment pages hosted by GoCardless, and / or to have GoCardless send compliant, generic notification emails on your behalf.

You can see our hosted payment pages and an example of the emails we send by testing out the payment flow here.

IBAN

When supplying an IBAN (international bank account number), the country_code field is optional, but must match the country code of the IBAN (its first two characters) if supplied.

Note: bank details for accounts denominated in Swedish krona (SEK) cannot be supplied as an IBAN.

{
  "customer_bank_accounts": {
    "iban": "GB60 BARC 2000 0055 7799 11",
    ...
  }
}

UK

For the UK, a 6-8 digit account_number and a 6 digit branch_code (sort code) should be supplied.

{
  "customer_bank_accounts": {
    "country_code": "GB",
    "account_number": "55779911",
    "branch_code": "200000",
    ...
  }
}

Austria

For Austria, an account_number (Kontonummer, Kto.) and bank_code (Bankleitzahl, BLZ) should be supplied. The Kontonummer is 4-11 digits, and the Bankleitzahl is 5 digits.

{
  "customer_bank_accounts": {
    "country_code": "AT",
    "account_number": "234573201",
    "bank_code": "19043",
    ...
  }
}

Belgium

For Belgium, only an account_number (Rekeningnummer/Numéro de compte) should be supplied. The first three digits of this are a bank identifier, but are usually considered part of the account number.

{
  "customer_bank_accounts": {
    "country_code": "BE",
    "account_number": "539-0075470-34",
    ...
  }
}

Cyprus

For Cyprus, a 3 digit bank_code (Kodikos Trapezas) and 7-16 digit account_number (Arithmos Logariasmou) must be supplied, and a 5 digit branch_code (Kodikos Katastimatos) can also be supplied.

The bank and branch code (Kodikos Trapezas and Kodikos Katastimatos) are frequently supplied together as a single number, so it is also allowed to supply just an 8-digit bank_code containing both the Kodikos Trapezas and the Kodikos Katastimatos.

{
  "customer_bank_accounts": {
    "country_code": "CY",
    "account_number": "1200527600",
    "bank_code": "002",
    "branch_code": "00128",
    ...
  }
}

Estonia

All local account numbers were replaced with IBANs in February 2014, however some payers may prefer using the old account numbers. These are up to 14 digits, and can be supplied as the account_number.

{
  "customer_bank_accounts": {
    "country_code": "EE",
    "account_number": "221020145685",
    ...
  }
}

Finland

As of August 2014, Finnish banks are required to use IBANs rather than the old “tilinumeron rakenne”, however GoCardless still supports the older format. This is a 6 digit bank_code, and up to 8 digit account_number.

The Åland Islands use the same banking details as Finland, and can be submitted using their ISO 3166-1 country code AX.

{
  "customer_bank_accounts": {
    "country_code": "FI",
    "account_number": "456",
    "bank_code": "500015",
    ...
  }
}

France

There are four parts to French bank details: - Code banque: 5 digit bank_code - Code guichet: 5 digit branch_code - Numéro de compte: up to 11 digit account number - Clé RIB: 2 check digits

The check digits are frequently written at the end of the account number, and this is how they should be included in the account_number field.

French DOMs and TOMs use the same details as above, and can be submitted using their ISO 3166-1 country codes: - French Guiana: GF - Guadeloupe: GP - Martinique: MQ - Mayotte: YT - Réunion: RE - Saint Barthélemy: BL - Saint Martin (French part): MF - Saint Pierre and Miquelon: PM

{
  "customer_bank_accounts": {
    "country_code": "FR",
    "account_number": "0500013M026 06",
    "bank_code": "20041",
    "branch_code": "01005",
    ...
  }
}

Germany

For Germany, a 1-10 digit account_number (Kontonummer) and 8 digit bank_code (Bankleitzahl) are required.

{
  "customer_bank_accounts": {
    "country_code": "DE",
    "account_number": "532013000",
    "bank_code": "37040044",
    ...
  }
}

Greece

In Greece most customers know their IBANs, but GoCardless also supports passing full local bank details. If local bank details are provided, a 3 digit bank_code (Kodikos Trapezas), a 5 digit branch_code (Kodikos Katastimatos), and a 16 digit account_number (Arithmos Logariasmou) must be supplied.

{
  "customer_bank_accounts": {
    "country_code": "GR",
    "account_number": "0000000012300695",
    "bank_code": "011",
    "branch_code": "0125",
    ...
  }
}

Ireland

Ireland uses a 6-digit branch_code (sort code), and 6-8 digit account_number.

{
  "customer_bank_accounts": {
    "country_code": "IE",
    "account_number": "12345678",
    "branch_code": "93-11-52",
    ...
  }
}

Italy

Most Italian payers will be familiar with the IBAN format in addition to the local format, and more correctness checks can be applied to the IBAN, so it is recommended to ask users to input their IBAN rather than local details. However, it is possible to use:

  • Codice ABI: 5 digit bank_code
  • CAB: 5 digit branch_code
  • Numero di conto: up to 12 digit account_number
{
  "customer_bank_accounts": {
    "country_code": "IT",
    "account_number": "123456",
    "bank_code": "05428",
    "branch_code": "11101",
    ...
  }
}

Latvia

Latvia replaced bank details with IBANs in 2005, so most Latvian payers are unlikely to know their bank code and account number, however GoCardless continues to accept them. The bank_code should be 4 characters, and the account_number should be 13 digits.

{
  "customer_bank_accounts": {
    "country_code": "LV",
    "account_number": "0000435195001",
    "bank_code": "LACB",
    ...
  }
}

Lithuania

Lithuania replaced bank details with IBANs in 2004, so most Lithuanian payers are unlikely to know their bank code and account number, however GoCardless continues to accept them. The bank_code should be 5 digits, and the account_number should be 11 digits.

{
  "customer_bank_accounts": {
    "country_code": "LT",
    "account_number": "11101001000",
    "bank_code": "10000",
    ...
  }
}

Luxembourg

Luxembourg replaced bank details with IBANs in 2002, so most Luxembourgian payers are unlikely to know their bank code and account number, however GoCardless continues to accept them. The bank_code should be 3 digits, and the account_number should be 13 digits.

{
  "customer_bank_accounts": {
    "country_code": "LU",
    "account_number": "9400644750000",
    "bank_code": "001",
    ...
  }
}

Malta

Malta uses a 5-digit branch_code (sort code) and an up to 18-digit account_number (numru tal‑kont bankarju).

{
  "customer_bank_accounts": {
    "country_code": "MT",
    "account_number": "9027293051",
    "branch_code": "44093",
    ...
  }
}

Monaco

Monaco uses the same local bank details as France. That is: - Code banque: 5 digit bank_code - Code guichet: 5 digit branch_code - Numéro de compte: up to 11 digit account number - Clé RIB: 2 check digits

The check digits are frequently written at the end of the account number, and this is how they should be included in the account_number field.

{
  "customer_bank_accounts": {
    "country_code": "MC",
    "account_number": "0500013M026 06",
    "bank_code": "20041",
    "branch_code": "01005",
    ...
  }
}

Netherlands

The Netherlands have replaced local bank details with IBANs, so most Dutch payers are unlikely to know their bank code and Rekeningnummer, however GoCardless continues to accept them. The bank_code should be 4 characters, and the account_number (Rekeningnummer) up to 10 digits.

{
  "customer_bank_accounts": {
    "country_code": "NL",
    "account_number": "0417164300",
    "bank_code": "ABNA",
    ...
  }
}

Portugal

Portuguese bank details have 4 components: - Código de Banco: 4 digit bank_code - Código de Balcão: 4 digit branch_code - Número de conta: 11 digit account number - Dígitos de controlo: 2 check digits

The account number and check digits should be concatenated for the account_number field.

{
  "customer_bank_accounts": {
    "country_code": "PT",
    "account_number": "1234567890154",
    "bank_code": "0002",
    "branch_code": "0123",
    ...
  }
}

San Marino

San Marino uses the same bank details formats as Italy. As with Italy, payers will be familiar with the IBAN format in addition to the local format, and more correctness checks can be applied to the IBAN, so it is recommended to ask users to input their IBAN rather than local details. However, it is possible to use:

  • Codice ABI: 5 digit bank_code
  • CAB: 5 digit branch_code
  • Numero di conto: up to 12 digit account_number
{
  "customer_bank_accounts": {
    "country_code": "SM",
    "account_number": "123456",
    "bank_code": "05428",
    "branch_code": "11101",
    ...
  }
}

Slovak Republic

There are three parts to Slovak bank details: - Předčíslí: up to 6 digit account number prefix - Číslo účtu: up to 8 digit account number - Kód banky: 4 digit bank code

These are often written as pppppp-aaaaaaaaaa/bbbb. When creating a bank account using Slovak bank details, the předčíslí and číslo účtu should be concatenated for the account_number field, and the kód banky should be used for the bank_code field.

{
  "customer_bank_accounts": {
    "country_code": "SK",
    "account_number": "198742637541",
    "bank_code": "1200",
    ...
  }
}

Slovenia

Slovenia uses a 5 digit bank_code and up to 10 digit account_number.

{
  "customer_bank_accounts": {
    "country_code": "SI",
    "account_number": "123438",
    "bank_code": "19100",
    ...
  }
}

Spain

There are four parts to Spanish bank details, the 4 digit código de entidad (bank code), 4 digit código de oficina (branch code), 2 dígitos de control (check digits), and 10 digit número de cuenta.

These can either be supplied as separate bank_code, branch_code, and account_number (with the check digits at the start of the account number), or all in the account_number field. In the latter case, this is known locally as the Código Cuenta Cliente.

{
  "customer_bank_accounts": {
    "country_code": "ES",
    "account_number": "45 0200051332",
    "bank_code": "2100",
    "branch_code": "0418",
    ...
  }
}

Sweden

Sweden uses a 4- or 5-digit branch_code (clearingnummer), and up to 10-digit account_number (kontonummer).

{
  "customer_bank_accounts": {
    "country_code": "SE",
    "account_number": "1234512",
    "branch_code": "5527"
    ...
  }
}

Character sets

Different schemes allow different sets of characters to be used in payment and mandate references. All schemes allow all alphanumeric characters (A-Z, 0-9), and some special characters, as follows:

Bacs

  • ” ” (space)
  • “&” (ampersand)
  • ”-“ (hyphen)
  • ”.” (full stop)
  • ”/” (solidus)

SEPA Core

  • ” ” (space)
  • ”.” (full stop)
  • ”-“ (hyphen)
  • ”/” (solidus)
  • ”?’ (question mark)
  • ”:” (colon)
  • ”(“ (left parenthesis)
  • ”)” (right parenthesis)
  • ”,” (comma)
  • ”+” (plus)
  • ”’” (single quote)

Autogiro

Autogiro mandate references must be numeric, but payment references support the full set of alphanumeric characters (A-Z, a-z, 0-9), and also:

  • ” ” (space)
  • ”!” (exclamation mark)
  • ’”’ (double quote)
  • ”#” (hash sign)
  • ”$” (dollar sign)
  • ”%” (percent symbol)
  • “&” (ampersand)
  • ”’” (single quote)
  • ”(“, and “)” (parentheses)
  • “*” (asterisk)
  • ”+” (plus)
  • ”,” (comma)
  • ”-“ (hyphen)
  • ”.” (full stop)
  • ”/” (solidus)
  • ”:” (colon)
  • ”;” (semi-colon)
  • ”<”, and “>” (less than and greater than symbols)
  • ”=” (equals)
  • ”?” (question mark)