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, .NET, Java, Ruby and Python code samples

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 UK & Channel Islands (inc. Jersey & Guernsey) + Isle of Man + Gibraltar (The customer needs to select UK as the country)
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
ACH United States
Autogiro
Sweden
Betalingsservice
Denmark
BECS
Australia
BECS NZ
New Zealand
PAD
Canada

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.

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 previously 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

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 ACH:

  • New mandates take up to 2 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 2 working days in advance of the payment being collected.

For more information on ACH 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 detailed guide.

For BECS:

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

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

For BECS NZ:

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

For more information on BECS NZ timings, see our detailed guide.

For Betalingsservice:

  • New mandates must be created at least one working day before payments can be created.
  • For all payment collections, you must submit the collection 8 working days before the end of the month preceding the month in which you wish to take the payment

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

For PAD:

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

For more information on PAD 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 3 working days in advance of the payment being collected.

For more information on SEPA timings, see our detailed 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
  • The number of and duration between retries for failed webhooks
  • The behaviour of Scenario Simulators
  • Sending webhooks for new event types

Changelog

30th March 2021
Added Scenario Simulators endpoint. These allow manual testing of certain flows in the Sandbox environment
28th January 2021
Added webhook endpoints. These allow you to view and retry webhooks that we have sent to you. As part of this we began including webhook_id inside the meta key in the webhooks we send.
30th October 2020
Added a new resource called payer_authorisatons. This is our new API dedicated to building custom payment pages. It encapsulates the creation of customer, bank account and mandate under this single resource.
12th August 2020
Added a new event called payer_authorisation_completed for an upcoming resource type called payer_authorisation.
14th July 2020
Added support for applying tax to transaction and surcharge fees.
9th July 2020
Allow changing retry_if_possible when updating a subscription.
27th May 2020
Added a not_retried_reason field to the event details for failed payment event.
7th May 2020
Updated the type of bank_account_type from string to enum. bank_account_type is referenced in creditor_bank_accounts, customer_bank_acount_tokens, customer_bank_accounts and mandate_pdfs endpoint.
20th April 2020
Added prefilled_bank_account attribute in the redirect flow create endpoint to allow the integrator to prefill the account_type field.
20th April 2020
Added metadata to payouts, and added new update payouts route so that integrators can use it.
6th April 2020
We are updating the wording of the documentation for prefilled_customer[region] attribute in redirect flow create endpoint.
26th March 2020
We have added the ability to capture metadata attribute as part of redirect flow create endpoint.
17th March 2020
We’ve added the ability to pause and resume subscriptions.
19th February 2020
We’ve optimised our webhook batching to become slightly more effective. This means each webhook will have on–average–slightly more events per request than we have sent previously.
18th Februrary 2020
Added new events for creditors:
  • updated
  • new_payout_currency_added
6th February 2020
Added support for Success+ intelligent retries
6th February 2020
Added new disconnected webhook for partners
29th January 2020
Added 3 fields to the Creditors endpoint: mandate_imports_enabled, merchant_responsible_for_notifications and custom_payment_pages_enabled.
28th January 2020
Added support for instalment schedules.
27th January 2020
Marked the phone_number field in Customers as optional.
19th November 2019
Added support for international payments.
23rd July 2019
Added new customer removal API.
21st February 2019
Added new payment_autoretried event cause for the payment_resubmission_requested action.
19th December 2018
Added the ability to handle subscription_created emails.
5th December 2018
Added support for PAD, the Direct Debit scheme in Canada, in beta.
16th October 2018
Added new event for refund failed (refund_failed).
11th September 2018
Added support for BECS NZ, the Direct Debit scheme in New Zealand, in beta.
30th August 2018
Add links[default_aud_payout_account] as an updatable field to the creditors API
22nd August 2018
Removed can_create_refunds as an updatable field from the creditors API
17th August 2018
Added the ability to handle payment_created and mandate_created emails.
12th July 2018
Added customer address fields to the mandate PDFs API.
27th June 2018
Added support for Betalingsservice, the Direct Debit scheme in Denmark, in beta.
22nd May 2018
Added app_fee field to responses from the subscriptions API.
17th May 2018
Took the payout items API out of beta.
Improved the documentation of the mandate PDFs API, clarifying what languages are supported for each scheme and documenting that the default language is English.
15th May 2018
Added the maximum payment and refund reference lengths for Becs.
26th April 2018
Added the mandate imports API, allowing partners to more easily migrate mandates to GoCardless.
20th April 2018
Added information on our public certificate policy.
11th April 2018
Added support for BECS, the Direct Debit scheme in Australia, in beta.
6th March 2018
Added contact email address to responses from the OAuth introspect API and access token API.
13th February 2018
Added support for multiple redirect URIs per partner app.
26th January 2018
Added the new OAuth introspect API, allowing partners to check if access tokens are valid and find out more about them
Added the new OAuth revoke API, allowing partners to disconnect users from their app, invaliding their access token
15th January 2018
Added additional characters to the list of allowed characters for SEPA mandate and payment references
1st December 2017
Added read-only can_create_refunds field to responses from the creditors API.
30th November 2017
Renamed exceeded_max_amendments error on subscriptions to number_of_subscription_amendments_exceeded when updating a subscription.
16th November 2017
Added filtering by reference to the payouts API.
14th November 2017
Added filtering by status to the subscriptions API.
13th November 2017
Added the new payout items API, allowing you to view, on a per-payout basis, the credit and debit items that make up that payout’s amount.
25th October 2017
Allow changing amount when updating a subscription.
23rd October 2017
Added new event for subscription amended action.
18th September 2017
Added confirmation_url to the redirect flows API.
19th June 2017
Added the Origin header to webhooks, specifying the GoCardless environment that a webhook was sent from (https://api.gocardless.com for live, https://api-sandbox.gocardless.com for sandbox).
19th May 2017
Added verification_status to the creditors API.
11th May 2017
Deprecated end_date in the subscriptions API.
17th March 2017
Added new mandate_expired cause for the payment cancelled action(#payment-cancelled).
13th March 2017
Added app_fee to the subscriptions API.
2nd March 2017
Added prefilled_customer to the redirect flows API.
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

If you’re using our JavaScript Flow, you must use a publishable access token instead.

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.

An Accept header is required for all requests, for example:

Accept: application/json

A Content-Type and Content-Length header must be given when sending data to the API (using POST and PUT endpoints), for example:

Content-Type: application/json
Content-Length: 3495

For the Accept and Content-Type headers, you may give 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.

In the case of a missing Content-Length header, you will receive an Error 411 (Length Required) error message. Although, the majority of HTTP clients should send the header by default.

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

We apply a rate limit to all API requests, to prevent excessive numbers of simultaneous requests from an individual integrator degrading the API experience for others.

Currently, this limit stands at 1000 requests per minute. If you are making requests from a partner integration (on behalf of a merchant), the rate limit is 1000 requests per minute per merchant. The limit can always be found in the response header ratelimit-limit.

If your API call returns a 429 status code with a rate_limit_exceeded error, you have exceeded this limit. These requests can be safely retried. We supply information in the ratelimit-remaining and ratelimit-reset headers, which indicate how many requests are allowed in the current time window, and the time after which the rate limit will reset, respectively.

For example, reading response headers like these, your integration is permitted to make a further 163 requests until Thu, 03 May 2018 16:00:00 GMT, after which the limit will reset back to 1000 for the next time window:

ratelimit-limit: 1000
ratelimit-remaining: 163
ratelimit-reset: Thu, 03 May 2018 16:00:00 GMT

If you are planning to make a large number of requests to our API, our rate limit should be regarded as a performance target: if you can successfully hit 1000 requests/minute, your task will be completed in the shortest possible time.

Idempotency Keys

Some requests are dangerous to make twice. In a situation like submitting payments, retrying a request that appeared to fail (for example due to a network timeout) could lead to a payment being taken twice. This is clearly undesirable.

When creating resources, our API supports idempotent creation. If you make a request with an Idempotency-Key header, we only allow that key to be used for a single successful request. 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, with the error including a links.conflicting_resource_id attribute pointing to the already-existing resource.

Our API libraries will automatically generate idempotency keys when you try to create a resource. However, you might want to generate and supply your own - for example, using an ID from your database to identify a record (for example a payment you’re going to collect) will protect against not only network errors, but also accidentally doing the same thing twice from your side.

Idempotency keys may be no longer than 128 characters.

Idempotency keys are intended to prevent conflicts over short periods of time, and will not be persisted indefinitely. We guarantee that we will honour idempotency keys for at least 30 days. After this point we reserve the right to respect the keys for any further length of time and this behaviour must not be relied upon. We strongly encourage generating idempotency keys using UUIDv4 but any non-repeating unique identifier is sufficient.

Optional properties

When making requests, optional properties should be completely omitted from the JSON when not being used. This is automatically handled in our API libraries and is only relevant if you create your own.

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.

In the sandbox environment, we provide scenario simulators which allow you to manually trigger certain cases (like a customer cancelling their mandate or a payment failing due to lack of funds) from the Dashboard so you can test how your integration responds.

To find out more, see our scenario simulators 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

invalid_type
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.

access_token_revoked
The access token you are using has been revoked by the user.

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.

request_body_not_allowed
Sending a request body is not supported for the HTTP method you have used. Use query string parameters in the URL instead.

customer_data_removed
The customer has been removed and they can no longer be returned by our API. You should remove any GoCardless references to these objects in your systems.

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_is_unreachable
The refund could not be created, because it would not reach the target bank account.

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.

available_refund_amount_insufficient
The refund requested by the creditor could not be created for the given currency, because the creditor does not have a sufficient balance available to cover the cost of the refund.

The amount available for refunds will fluctuate over time, as it is calculated in real time using several indicators. Examples of such indicators are in-flight payments, pending refunds, and any applicable ‘buffer allowance’ provided by GoCardless for the creditor in the given currency. The amount available for refunds will be returned in the metadata of the error response, under the available_refund_amount key, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.

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.
can_create_refunds
Boolean indicating whether the creditor is permitted to create refunds
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.
custom_payment_pages_enabled
Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.
fx_payout_currency
ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
logo_url
URL for the creditor’s logo, which may be shown on their payment pages.
mandate_imports_enabled
Boolean value indicating whether creditor has the Mandate Imports functionality enabled.
merchant_responsible_for_notifications
Boolean value indicating whether the organisation is responsible for sending all customer notifications (note this is separate from the functionality described here). If you are a partner app, and this value is true, you should not send notifications on behalf of this organisation.
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: ISO 3166-1 alpha-2 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.

verification_status
The creditor’s verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our “Helping your users get verified” guide. One of:
  • successful: The creditor’s account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again.

  • in_review: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts.

  • action_required: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.

links[default_aud_payout_account]
ID of the bank account which is set up to receive payouts in AUD.
links[default_cad_payout_account]
ID of the bank account which is set up to receive payouts in CAD.
links[default_dkk_payout_account]
ID of the bank account which is set up to receive payouts in DKK.
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_nzd_payout_account]
ID of the bank account which is set up to receive payouts in NZD.
links[default_sek_payout_account]
ID of the bank account which is set up to receive payouts in SEK.
links[default_usd_payout_account]
ID of the bank account which is set up to receive payouts in USD.

Create a creditor

Creates a new creditor.

Relative endpoint: POST /creditors

Restricted: this endpoint is restricted to integrators who already use it, and we will not enable it for any new accounts. You can still manage multiple merchant accounts by building a partner integration.

Parameters

name
required The creditor’s name.
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.
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"
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Creditor creditor = client.creditors().create()
  .withName("The Wine Club")
  .withAddressLine1("9 Acer Gardens")
  .withCity("Birmingham")
  .withPostalCode("B4 7NJ")
  .withCountryCode("GB")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditor = await client.creditors.create({
  name: "The Breakfast Club",
  address_line1: "338 Goswell Road",
  city: "London",
  postal_code: "EC1V 7LQ",
  country_code: "GB"
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorRequest = new GoCardless.Services.CreditorCreateRequest()
{
    Name = "Example Ltd",
    AddressLine1 = "22-25 Finsbury Square",
    City = "London",
    PostalCode = "EC2A 1DX",
    CountryCode = "GB"
};

var creditorResponse = await gocardless.Creditors.CreateAsync(creditorRequest);
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;
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,
    "verification_status": "action_required",
    "can_create_refunds": false,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": false,
    "fx_payout_currency": 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": "help@gocardless.com",
        "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Creditor creditor : client.creditors().all().execute()) {
  System.out.println(creditor.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditors = await client.creditors.list();

// List the first three creditors.
const creditors = await client.creditors.list({ limit: 3 });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorListResponse = gocardless.Creditors.All();
foreach (GoCardless.Resources.Creditor creditor in creditorListResponse)
{
    Console.WriteLine(creditor.Name);
}
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,
    "verification_status": "successful",
    "can_create_refunds": false,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": false,
    "fx_payout_currency": "GBP",
    "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": "help@gocardless.com",
        "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Creditor creditor = client.creditors().get("CR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditor = await client.creditor.find("CR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorResponse = await gocardless.Creditors.GetAsync("CR0123");
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;
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,
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": "GBP",
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": false,
    "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": "help@gocardless.com",
        "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_aud_payout_account]
ID of the bank account which is set up to receive payouts in AUD.
links[default_cad_payout_account]
ID of the bank account which is set up to receive payouts in CAD.
links[default_dkk_payout_account]
ID of the bank account which is set up to receive payouts in DKK.
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_nzd_payout_account]
ID of the bank account which is set up to receive payouts in NZD.
links[default_sek_payout_account]
ID of the bank account which is set up to receive payouts in SEK.
links[default_usd_payout_account]
ID of the bank account which is set up to receive payouts in USD.
$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.creditors().update("CR123")
  .withName("Nude Wines")
  .withLinksDefaultGbpPayoutAccount("BA789")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditor = await client.creditors.update(
  "CR123",
  {
    name: "The Brunch Club",
    links: {
      default_gbp_payout_account: "BA123"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorRequest = new GoCardless.Services.CreditorUpdateRequest()
{
    Links = new GoCardless.Services.CreditorUpdateRequest.CreditorLinks()
    {
        DefaultGbpPayoutAccount = "BA0123"
    }
};

var creditorResponse = await gocardless.Creditors.UpdateAsync("CR0123", creditorRequest);
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,
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": "GBP",
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": false,
    "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": "help@gocardless.com",
        "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.

Restricted: This API is not available for partner integrations.

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
The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
account_type
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
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. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
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.
account_type
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
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. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
iban
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .withSetAsDefaultPayoutAccount(true)
  .withAccountHolderName("Nude Wines")
  .withLinksCreditor("CR123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditorBankAccount = await client.creditorBankAccounts.create({
  account_number: "55779911",
  branch_code: "200000",
  country_code: "GB",
  set_as_default_payout_account: true,
  account_holder_name: "Nude Wines",
  links: {
    creditor: "CR123"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorBankAccountRequest = new GoCardless.Services.CreditorBankAccountCreateRequest()
{
    AccountHolderName = "Example Ltd",
    AccountNumber = "55779911",
    BranchCode = "200000",
    CountryCode = "GB",
    SetAsDefaultPayoutAccount = true,
    Links = new GoCardless.Services.CreditorBankAccountCreateRequest.CreditorBankAccountLinks()
    {
        Creditor = "CR0123"
    }
};

var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.CreateAsync(creditorBankAccountRequest);
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;
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",
    "account_type": null,
    "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
Boolean value showing whether the bank account is enabled or disabled
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (CreditorBankAccount creditorBankAccount : client.creditorBankAccounts().all().withCreditor("CR123").execute()) {
  System.out.println(creditorBankAccount.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditorBankAccounts = await client.creditorBankAccounts.list();

// List all 'enabled' creditor bank accounts.
const creditorBankAccounts = await client.creditorBankAccounts.list({ enabled: true });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorBankAccountRequest = new GoCardless.Services.CreditorBankAccountListRequest()
{
    Creditor = "CR000123"
};

var creditorBankAccountListResponse = gocardless.CreditorBankAccounts.All(creditorBankAccountRequest);
foreach (GoCardless.Resources.CreditorBankAccount creditorBankAccount in creditorBankAccountListResponse)
{
    Console.WriteLine(creditorBank.Id);
}
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",
    "account_type": null,
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().get("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditorBankAccount = await client.creditorBankAccounts.find('BA123');
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.GetAsync("BA0123");
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;
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",
    "account_type": null,
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.creditorBankAccounts().disable("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const creditorBankAccountResponse = await client.creditorBankAccounts.disable("BA123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.DisableAsync("BA0123");
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",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": false,
    "links": {
      "creditor": "CR123"
    }
  }
}

Currency Exchange Rates

Currency exchange rates from our foreign exchange provider.

Properties

rate
The exchange rate from the source to target currencies provided with up to 10 decimal places.
source
Source currency
target
Target currency
time
Time at which the rate was retrieved from the provider.

List exchange rates

Returns a cursor-paginated list of all exchange rates.

Relative endpoint: GET /currency_exchange_rates

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.
source
Source currency
target
Target currency
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->currencyExchangeRates()->list([
  "params" => ["source" => "EUR", "target" => "GBP"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.currency_exchange_rates.list(params={"source": "EUR", "target": "GBP"}).records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.currency_exchange_rates.list(params: { source: "EUR", target: "GBP" })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.currencyExchangeRates().all().withSource("EUR").withTarget("GBP").execute()
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const currencyExchangeRates = await client.currencyExchangeRates.list();

// List the currency exchange rate for a source and target currency.
const currencyExchangeRates = await client.currencyExchangeRates.list({ source: 'EUR', target: 'GBP' });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var request = new GoCardless.Services.CurrencyExchangeRateListRequest()
{
    Source = "EUR",
    Target = "GBP"
};

var response = gocardless.CurrencyExchangeRates.All(request);
foreach (GoCardless.Resources.CurrencyExchangeRate rate in response)
{
    Console.WriteLine(rate.Rate);
}
GET https://api.gocardless.com/currency_exchange_rates?source=GBP&target=EUR HTTP/1.1

HTTP/1.1 200 OK
{
    "currency_exchange_rates": [
        {
            "rate": "1.19111",
            "source": "GBP",
            "target": "EUR",
            "time": "2020-02-24T23:50:04.000Z"
        }
    ],
    "meta": {
        "cursors": {
            "after": null,
            "before": null
        },
        "limit": 50
    }
}

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.

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. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
country_code
ISO 3166-1 alpha-2 code.
created_at
Fixed timestamp, recording when this resource was created.
danish_identity_number
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
email
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
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”, “da”, “nb”, “sl”, “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.
phone_number
ITU E.123 formatted phone number, including country code.
postal_code
The customer’s postal code.
region
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
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.

Create a customer

Creates a new customer object.

Relative endpoint: POST /customers

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise 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. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
country_code
ISO 3166-1 alpha-2 code.
danish_identity_number
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
email
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
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”, “da”, “nb”, “sl”, “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.
phone_number
ITU E.123 formatted phone number, including country code.
postal_code
The customer’s postal code.
region
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
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.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customers()->create([
  "params" => ["email" => "tim@gocardless.com",
               "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": "user@example.com",
  "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: "user@example.com",
    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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Customer customer = client.customers().create()
  .withEmail("user@example.com")
  .withGivenName("Frank")
  .withFamilyName("Osborne")
  .withAddressLine1("27 Acer Road")
  .withAddressLine2("Apt 2")
  .withCity("London")
  .withPostalCode("E8 3GX")
  .withCountryCode("GB")
  .withMetadata("salesforce_id", "ABCD1234")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customer = await client.customers.create({
  email: "user@example.com",
  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"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerRequest = new GoCardless.Services.CustomerCreateRequest()
{
    Email = "user@example.com",
    GivenName = "Frank",
    FamilyName = "Osborne",
    AddressLine1 = "27 Acer Road",
    AddressLine2 = "Apt 2",
    City = "London",
    PostalCode = "E8 3GX",
    CountryCode = "GB",
    Metadata = new Dictionary<string, string>()
    {
      {"salesforce_id", "ABCD1234"}
    }
};

var customerResponse = await gocardless.Customers.CreateAsync(customerRequest);
GoCardless.Resources.Customer customer = customerResponse.Customer;
POST https://api.gocardless.com/customers HTTP/1.1
{
  "customers": {
    "email": "user@example.com",
    "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": "user@example.com",
    "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",
    "phone_number": null,
    "swedish_identity_number": null,
    "danish_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.
currency
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
limit
Number of records to return.
sort_direction
The direction to sort in.
sort_field
Field by which to sort records.
$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Customer customer : client.customers().all().execute()) {
  System.out.println(customer.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customer = await client.customers.list();

// List customers with a given currency.
await client.customers.list({ currency: "GBP" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerListResponse = gocardless.Customers.All();
foreach (GoCardless.Resources.Customer customer in customerListResponse)
{
    Console.WriteLine(customer.GivenName);
}
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": "user@example.com",
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Customer customer = client.customers().get("CU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customer = await client.customers.find("CU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerResponse = await gocardless.Customers.GetAsync("CU0123");
GoCardless.Resources.Customer customer = customerResponse.Customer;
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": "user@example.com",
    "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",
    "phone_number": null,
    "swedish_identity_number": null,
    "danish_identity_number": null,
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}

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

HTTP/1.1 410 Gone
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}

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. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
country_code
ISO 3166-1 alpha-2 code.
danish_identity_number
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
email
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
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”, “da”, “nb”, “sl”, “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.
phone_number
ITU E.123 formatted phone number, including country code.
postal_code
The customer’s postal code.
region
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
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.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->customers()->update("CU123", [
  "params" => ["email" => "tim@gocardless.com"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.customers.update("CU123", params={
  "email": "updated_user@example.com"
})
@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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.customers().update("CU123")
  .withEmail("updated_user@example.com")
  .withGivenName("Jenny")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customer = await client.customers.update(
  "CU123",
  {
    email: "updated_user@example.com",
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"custom_reference", "NEWREFERENCE001"}
    }
};
var customerResponse = await gocardless.Customers.UpdateAsync("CU0123", customerRequest);
PUT https://api.gocardless.com/customers/CU123 HTTP/1.1
{
  "customers": {
    "email": "updated_user@example.com",
    "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": "updated_user@example.com",
    "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",
    "phone_number": null,
    "swedish_identity_number": null,
    "danish_identity_number": null,
    "metadata": {
      "salesforce_id": "EFGH5678"
    }
  }
}

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

HTTP/1.1 410 Gone
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}

Remove a customer

Removed customers will not appear in search results or lists of customers (in our API or exports), and it will not be possible to load an individually removed customer by ID.

The action of removing a customer cannot be reversed, so please use with care.

Relative endpoint: DELETE /customers/CU123

Parameters

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

$client->customers()->remove("CU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.customers.remove("CU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.customers().remove("CU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customer = await client.customers.remove("CU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

await gocardless.Customers.RemoveAsync("CU0123");
DELETE https://api.gocardless.com/customers/CU123 HTTP/1.1

HTTP/1.1 204 No Content

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

HTTP/1.1 410 Gone

{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}

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 is the same as the name stored with the linked creditor. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
account_number_ending
The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
account_type
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
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. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
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 and GoCardless Enterprise accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.

Parameters

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. This field is required unless the request includes a customer bank account token.
account_number
Bank account number - see local details for more information. Alternatively you can provide an iban.
account_type
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
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. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
iban
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

CustomerBankAccount customerBankAccount = client.customerBankAccounts().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withAccountHolderName("Frank Osborne")
  .withCountryCode("GB")
  .withLinksCustomer("CU123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customerBankAccount = await client.customerBankAccounts.create({
  account_number: "55779911",
  branch_code: "200000",
  account_holder_name: "Frank Osborne",
  country_code: "GB",
  links: {
    customer: "CU123"
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountCreateRequest()
{
    AccountHolderName = "Example Ltd",
    AccountNumber = "55779911",
    BranchCode = "200000",
    CountryCode = "GB",
    Links = new GoCardless.Services.CustomerBankAccountCreateRequest.CustomerBankAccountLinks()
    {
        Customer = "CU0123"
    }
};

var customerBankAccountResponse = await gocardless.CustomerBankAccounts.CreateAsync(customerBankAccountRequest);
GoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (CustomerBankAccount customerBankAccount : client.customerBankAccounts().all().withCustomer("CU123").withEnabled(true).execute()) {
  System.out.println(customerBankAccount.getAccountHolderName());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customerBankAccount = await client.customerBankAccounts.list();

// List all 'enabled' customer bank accounts.
await client.customerBankAccounts.list({ enabled: true });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountListRequest()
{
    Customer = "CU000123"
};

var customerBankAccountListResponse = gocardless.CustomerBankAccounts.All(customerBankAccountRequest);
foreach (GoCardless.Resources.CustomerBankAccount customerBankAccount in customerBankAccountListResponse)
{
    Console.WriteLine(customerBank.Id);
}
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",
    "account_type": null,
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

CustomerBankAccount customerBankAccount = client.customerBankAccounts.get("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customerBankAccount = await client.customerBankAccounts.find("BA123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerBankAccountResponse = await gocardless.CustomerBankAccounts.GetAsync("BA0123");
GoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;
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",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {},
    "enabled": true,
    "links": {
      "customer": "CU123"
    }
  }
}

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

HTTP/1.1 410 Gone
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.customerBankAccounts().update("BA123")
  .withMetadata("description", "Business account")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customerBankAccount = await client.customerBankAccounts.update(
  "BA123",
  {
    metadata: {
      key: "value"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"description", "Business account"}
    }
};

var customerBankAccountResponse = await gocardless.CustomerBankAccounts.UpdateAsync("BA0123", customerBankAccountRequest);
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",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {
      "key": "value"
    },
    "enabled": true,
    "links": {
      "customer": "CU123"
    }
  }
}

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

HTTP/1.1 410 Gone
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.customerBankAccounts.disable("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customerBankAccount = await client.customerBankAccounts.disable("BA123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerBankAccountResponse = await gocardless.CustomerBankAccounts.DisableAsync("BA0123");
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",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "metadata": {},
    "enabled": false,
    "links": {
      "customer": "CU123"
    }
  }
}

Customer Notifications

Customer Notifications represent the notification which is due to be sent to a customer after an event has happened. The event, the resource and the customer to be notified are all identified in the links property.

Note that these are ephemeral records - once the notification has been actioned in some way, it is no longer visible using this API.

Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.

Properties

id
The id of the notification.
action_taken
The action that was taken on the notification. Currently this can only be handled, which means the integrator sent the notification themselves.
action_taken_at
Fixed timestamp, recording when this action was taken.
action_taken_by
A string identifying the integrator who was able to handle this notification.
type
The type of notification the customer shall receive.
links[customer]
The customer who should be contacted with this notification.
links[event]
The event that triggered the notification to be scheduled.
links[mandate]
The identifier of the related mandate.
links[payment]
The identifier of the related payment.
links[refund]
The identifier of the related refund.
links[subscription]
The identifier of the related subscription.

Handle a notification

“Handling” a notification means that you have sent the notification yourself (and don’t want GoCardless to send it). If the notification has already been actioned, or the deadline to notify has passed, this endpoint will return an already_actioned error and you should not take further action. This endpoint takes no additional parameters.

Relative endpoint: POST /customer_notifications/PCN123/actions/handle

Parameters

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

$client->customerNotifications()->handle("PCN123")
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.customer_notifications.handle("PCN123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

CustomerNotification customerNotification = client.customerNotifications().handle("PCN123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const customerNotification = await client.customerNotifications.handle("PCN123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customerNotificationResponse = await gocardless.CustomerNotifications.HandleAsync("PCN123");
GoCardless.Resources.CustomerNotification customerNotification = customerNotificationResponse.CustomerNotification;
POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1

HTTP/1.1 201 Created
{
  "customer_notifications": {
    "id": "PCN123",
    "type": "payment_created",
    "action_taken": "handled",
    "action_taken_at": "2018-08-01T13:42:56.000Z",
    "action_taken_by": "Partner name",
    "links": {
      "customer": "CU123",
      "event": "EV123",
      "payment": "PM123"
    }
  }
}


POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1

HTTP/1.1 403 Forbidden
{
  "error": {
    "message": "You are not authorised to handle notifications of this type.",
    "documentation_url": "https://developer.gocardless.com/api-reference#notification_type_forbidden",
    "type": "gocardless",
    "code": 403,
    "request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
    "errors": [
      {
         "reason": "notification_type_forbidden",
         "message": "You are not authorised to handle notifications of this type."
      }
    ]
  }
}


POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1

HTTP/1.1 403 Forbidden
{
  "error": {
    "message": "You are not the notification owner for this resource.",
    "documentation_url": "https://developer.gocardless.com/api-reference#not_notification_owner",
    "type": "gocardless",
    "code": 403,
    "request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
    "errors": [
      {
         "reason": "not_notification_owner",
         "message": "You are not the notification owner for this resource."
      }
    ]
  }
}


POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1

HTTP/1.1 410 Gone
{
  "error": {
    "message": "This notification can no longer be handled.",
    "documentation_url": "https://developer.gocardless.com/api-reference#already_actioned",
    "type": "gocardless",
    "code": 410,
    "request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
    "errors": [
      {
         "reason": "already_actioned",
         "message":  "This notification can no longer be handled."
      }
    ]
  }
}

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. See here for a complete list of event types.

Properties

id
Unique identifier, beginning with “EV”.
action
What has happened to the resource.
created_at
Fixed timestamp, recording when this resource was created.
customer_notifications
Present only in webhooks when an integrator is authorised to send their own notifications. See here for further information.

Each instance will contain these properties:

  • deadline: Time after which GoCardless will send the notification by email.

  • id: The id of the notification.

  • mandatory: Whether or not the notification must be sent.

  • type: The type of notification the customer shall receive.

details[bank_account_id]
When we send a creditor new_payout_currency_added webhook, we also send the bank account id of the new account
details[cause]
What triggered the event. Note: cause is our simplified and predictable key indicating what triggered the event.
details[currency]
When we send a creditor new_payout_currency_added webhook, we also send the currency of the new account
details[description]
Human readable description of the cause. Note: Changes to event descriptions are not considered breaking.
details[not_retried_reason]
When will_attempt_retry is set to false, this field will contain the reason the payment was not retried. This can be one of:
  • failure_filter_applied: The payment won’t be intelligently retried as there is a high likelihood of failure on retry.

  • other: The payment won’t be intelligently retried due to any other reason.

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

  • customer: this event was triggered by a Customer

details[property]
When we send a creditor creditor_updated webhook, this tells you which property on the creditor has been updated
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. Note: reason_code is payment scheme-specific and can be inconsistent between banks.
details[scheme]
A Direct Debit scheme. Set when a bank is the origin of the event.
details[will_attempt_retry]
Whether the payment will be retried automatically. Set on a payment failed 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

  • payer_authorisations

  • payouts

  • refunds

  • subscriptions

  • instalment_schedules

  • creditors

links[creditor]
If resource_type is creditor, this is the ID of the creditor which has been updated.
links[customer]
ID of a customer.
links[customer_bank_account]
ID of a customer bank account.
links[instalment_schedule]
If resource_type is instalment_schedule, this is the ID of the instalment schedule which has been updated.
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[payer_authorisation]
ID of a payer authorisation.
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

  • payer_authorisation

  • payout

  • refund

  • subscription

  • instalment_schedule

  • creditor

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 endpoint will return all events whose parent_event is the given event ID.
payer_authorisation
ID of a payer authorisation.
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, payer_authorisation, mandate, subscription, instalment_schedule, creditor, refund or payout parameter. The type can be one of:
  • payments

  • mandates

  • payer_authorisations

  • payouts

  • subscriptions

  • instalment_schedules

  • creditors

  • 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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Event event : client.events().all().withResourceType("payments").execute()) {
  System.out.println(event.getAction());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const events = await client.events.list();

// List all events of a given resource type.
const events = await client.events.list({ resource_type: "payments" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var eventRequest = new GoCardless.Services.EventListRequest()
{
    ResourceType = GoCardless.Services.EventListRequest.EventResourceType.Payments
};

var eventListResponse = gocardless.Events.All(eventRequest);
foreach (GoCardless.Resources.Event eventResource in eventListResponse)
{
    Console.WriteLine(eventResource.Action);
}
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Event event = client.events().get("EV123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const event = await client.events.find("EV123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var eventResponse = await gocardless.Events.GetAsync("EV0123");
GoCardless.Resources.Event eventResource = eventResponse.Event;
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"
    }
  }
}

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"
      }
    }
  ]
}

Instalment Schedules

Instalment schedules are objects which represent a collection of related payments, with the intention to collect the total_amount specified. The API supports both schedule-based creation (similar to subscriptions) as well as explicit selection of differing payment amounts and charge dates.

Unlike subscriptions, the payments are created immediately, so the instalment schedule cannot be modified once submitted and instead can only be cancelled (which will cancel any of the payments which have not yet been submitted).

Customers will receive a single notification about the complete schedule of collection.

Properties

id
Unique identifier, beginning with “IS”.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
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
Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
payment_errors
If the status is creation_failed, this property will be populated with validation failures from the individual payments, arranged by the index of the payment that failed.
status
One of:
  • pending: we’re waiting for GC to create the payments

  • active: the payments have been created, and the schedule is active

  • creation_failed: payment creation failed

  • completed: we have passed the date of the final payment and all payments have been collected

  • cancelled: the schedule has been cancelled

  • errored: one or more payments have failed

total_amount
The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
links[customer]
ID of the associated customer.
links[mandate]
ID of the associated mandate which the instalment schedule will create payments against.
payments
Array of IDs of the associated payments

Create (with dates)

Creates a new instalment schedule object, along with the associated payments. This API is recommended if you know the specific dates you wish to charge. Otherwise, please check out the scheduling version.

The instalments property is an array of payment properties (amount and charge_date).

It can take quite a while to create the associated payments, so the API will return the status as pending initially. When processing has completed, a subsequent GET request for the instalment schedule will either have the status success and link to the created payments, or the status error and detailed information about the failures.

Relative endpoint: POST /instalment_schedules

Parameters

currency
required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
instalments
required An explicit array of instalment payments, each specifying at least an amount and charge_date.
name
required Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
total_amount
required The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
app_fee
The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.
payment_reference
An optional reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
PAD - 12 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus, Pro or Enterprise packages.
retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false.
links[mandate]
required ID of the associated mandate which the instalment schedule will create payments against.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$instalment_schedule = $client->instalmentSchedules()->createWithDates([
    "params" => [
        "name" => "ACME Invoice 103",
        "amount" => 10000, // 100 GBP in pence, collected from the customer
        "app_fee" => 10, // Your 10 pence fee, applied to each instalment,
                         // to be paid out to you
        "currency" => 'GBP',
        "instalments" => [
            [
                "charge_date" => '2019-08-20',
                "amount" => 3400
            ],
            [
                "charge_date" => '2019-09-03',
                "amount" => 3400
            ],
            [
                "charge_date" => '2019-09-17',
                "amount" => 3200
            ],
          ],
          "links" => [
              "mandate" => 'MD0000XH9A3T4C'
          ],
          "metadata" => []
      ],
      "headers" => [
          'Idempotency-Key' => 'random_instalment_schedule_specific_string'
    ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

instalment_schedule = client.instalment_schedules.create_with_dates(
    params={
        "name": "ACME Invoice 103",
        "total_amount": 10000, # 100 GBP in pence, collected from the customer
        "app_fee": 10, # Your 10 pence fee, applied to each instalment,
                       # to be paid out to you
        "currency": 'GBP',
        "instalments": [
            {
                "charge_date": '2019-08-20',
                "amount": 3400
            },
            {
                "charge_date": '2019-09-03',
                "amount": 3400
            },
            {
                "charge_date": '2019-09-17',
                "amount": 3200
            },
        ],
        "links": {
            "mandate": 'MD0000XH9A3T4C'
        },
        "metadata": {}
    }, headers={
        'Idempotency-Key': 'random_instalment_schedule_specific_string'
    }
)
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

instalment_schedule = @client.instalment_schedules.create_with_dates(
  params: {
    name: "ACME Invoice 103",
    total_amount: 10_000, # 100 GBP in pence, collected from the customer
    app_fee: 10, # Your 10 pence fee, applied to each instalment,
                 # to be paid out to you
    currency: 'GBP',
    instalments: [
      {
        charge_date: '2019-08-20',
        amount: 3_400
      },
      {
        charge_date: '2019-09-03',
        amount: 3_400
      },
      {
        charge_date: '2019-09-17',
        amount: 3_200
      },
    ],
    links: {
      mandate: 'MD0000XH9A3T4C'
    },
    metadata: {}
  },
  headers: {
    'Idempotency-Key': 'random_instalment_schedule_specific_string'
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

int[] amountsArray = {3400, 3400, 3200};
String[] datesArray = {"2019-08-20", "2019-09-03", "2019-09-17"};

InstalmentSchedule instalmentSchedule = client.instalmentSchedules().createWithDates()
    .withTotalAmount(10000) // 100 GBP in Pence, collected from the end customer.
    .withAppFee(10)  // Your 10 pence fee, applied to each instalment, to be
                     // paid out to you
    .withCurrency("GBP")
    .withAmounts(amountsArray)
    .withDates(datesArray)
    .withLinksMandate("MD0000YTKZKY4J")
    .withMetadata("invoiceId", "001")
    .withIdempotencyKey("random_instalment_schedule_specific_string")
    .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const instalmentSchedule = await client.instalmentSchedules.createWithDates(
  {
    name: "ACME Invoice 103",
    total_amount: 10000, // 100 GBP in pence, collected from the customer
    app_fee: 10, // Your 10 pence fee, applied to each instalment,
                 // to be paid out to you
    currency: 'GBP',
    instalments: [
        {
            charge_date: '2019-08-20',
            amount: 3400
        },
        {
            charge_date: '2019-09-03',
            amount: 3400
        },
        {
            charge_date: '2019-09-17',
            amount: 3200
        }
    ],
    links: {
        mandate: 'MD0000XH9A3T4C'
    },
    metadata: {}
  },
  "instalment_schedule_idempotency_key"
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

int[] amountsArray = new int[]{ 3400, 3400, 3200 };
String[] datesArray = new String[]{ "2019-08-20", "2019-09-03", "2019-09-17" };

var createResponse = await gocardless.InstalmentSchedules.CreateWithDatesAsync(
    new InstalmentScheduleCreateWithDatesRequest
    {
        TotalAmount = 10000, // 100 GBP in pence, collected from the customer
        AppFee = 10, // Your 10 pence fee, applied to each instalment,
                     // to be paid out to you
        Currency = "GBP",
        Name = "ACME Invoice 103",
        Schedule = new GoCardless
            .Services
            .InstalmentScheduleCreateWithDatesRequest
            .InstalmentScheduleSchedule
            {
                ChargeDates = datesArray,
                Amounts = amountsArray
            },
        Links = new GoCardless
            .Services
            .InstalmentScheduleCreateWithDatesRequest
            .InstalmentScheduleLinks
            {
                Mandate = "MD0000XH9A3T4C"
            },
        Metadata = new Dictionary<string, string>
        {
            {"Invoice ID", "001"}
        },
        IdempotencyKey = "random_instalment_schedule_specific_string"
    }
);
POST https://api.gocardless.com/instalment_schedules HTTP/1.1

{
  "instalment_schedules": {
    "name": "Bike Invoice 271",
    "currency": "GBP",
    "total_amount": "2500",
    "instalments": [
      {
        "amount": "1500",
        "charge_date": "2019-12-14"
      },
      {
        "amount": "1000",
        "charge_date": "2020-05-01"
      }
    ],
    "metadata": {},
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 201 (Created)
Location: /instalment_schedules/IS123
{
 "instalment_schedules": {
   "id": "IS123",
   "status": "pending",
   "total_amount": "2500",
   "metadata": {},
   "payment_errors": {},
   "links": {
     "mandate": "MD123",
     "customer": "CU123"
   }
 }
}

Create (with schedule)

Creates a new instalment schedule object, along with the associated payments. This API is recommended if you wish to use the GoCardless scheduling logic. For finer control over the individual dates, please check out the alternative version.

It can take quite a while to create the associated payments, so the API will return the status as pending initially. When processing has completed, a subsequent GET request for the instalment schedule will either have the status success and link to the created payments, or the status error and detailed information about the failures.

Relative endpoint: POST /instalment_schedules

Parameters

currency
required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
instalments[amounts]
required List of amounts of each instalment, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
instalments[interval]
required Number of interval_units between charge dates. Must be greater than or equal to 1.
instalments[interval_unit]
required The unit of time between customer charge dates. One of weekly, monthly or yearly.
instalments[start_date]
The date on which the first payment should be charged. Must be on or after the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate’s next_possible_charge_date
name
required Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
total_amount
required The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
app_fee
The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.
payment_reference
An optional reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
PAD - 12 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus, Pro or Enterprise packages.
retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false.
links[mandate]
required ID of the associated mandate which the instalment schedule will create payments against.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$instalment_schedule = $client->instalmentSchedules()->createWithSchedule([
    "params" => [
        "name" => "ACME Invoice 103",
        "amount" => 10000, // 100 GBP in pence, collected from the customer
        "app_fee" => 10, // Your 10 pence fee, applied to each instalment,
                         // to be paid out to you
        "currency" => "GBP",
        "instalments" => [
            "start_date" => "2019-08-20",
            "interval_unit" => "weekly",
            "interval" => 2,
            "amounts" => [
                3400,
                3400,
                3200
            ]
        ],
        "links" => [
            "mandate" => "MD0000XH9A3T4C"
        ],
        "metadata" => []
    ],
    "headers" => [
        "Idempotency-Key" => "random_instalment_schedule_specific_string"
    ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

instalment_schedule = client.instalment_schedules.create_with_schedule(
    params={
        "name": "ACME Invoice 103",
        "total_amount": 10000, # 100 GBP in pence, collected from the customer
        "app_fee": 10, # Your 10 pence fee, applied to each instalment,
                       # to be paid out to you
        "currency": "GBP",
        "instalments": {
            "start_date": "2019-08-20",
            "interval_unit": "weekly",
            "interval": 2,
            "amounts": [
                3400,
                3400,
                3200
            ]
        }
        "links": {
            "mandate": "MD0000XH9A3T4C"
        },
        "metadata": {}
    }, headers={
        "Idempotency-Key": "random_instalment_schedule_specific_string"
    }
)
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

instalment_schedule = @client.instalment_schedules.create_with_schedule(
  params: {
    name: 'ACME Invoice 103',
    total_amount: 10_000, # 100 GBP in pence, collected from the customer
    app_fee: 10, # Your 10 pence fee, applied to each instalment,
                 # to be paid out to you
    currency: 'GBP',
    instalments: {
      start_date: '2019-08-20',
      interval_unit: 'weekly',
      interval: 2,
      amounts: [
        3_400,
        3_400,
        3_200
      ]
    }
    links: {
      mandate: 'MD0000XH9A3T4C'
    },
    metadata: {}
  },
  headers: {
    'Idempotency-Key': 'random_instalment_schedule_specific_string'
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

int[] amountsArray = {3400, 3400, 3200};
InstalmentSchedule instalmentSchedule = client.instalmentSchedules().createWithSchedule()
    .withTotalAmount(10000) // 100 GBP in Pence, collected from the customer.
    .withAppFee(10)  // Your 10 pence fee, applied to each instalment, to be
                     // paid out to you
    .withCurrency("GBP")
    .withIntervalUnit(IntervalUnit.WEEKLY)
    .withInterval(2)
    .withAmounts(amountsArray)
    .withLinksMandate("MD0000YTKZKY4J")
    .withMetadata("invoiceId", "001")
    .withIdempotencyKey("random_instalment_schedule_specific_string")
    .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const instalmentSchedule = await client.instalmentSchedules.createWithSchedule(
  {
    name: "ACME Invoice 103",
    total_amount: 10000, // 100 GBP in pence, collected from the customer
    app_fee: 10, // Your 10 pence fee, applied to each instalment,
                 // to be paid out to you
    currency: "GBP",
    instalments: {
      start_date: "2019-08-20",
      interval_unit: "weekly",
      interval: 2,
      amounts: [
        3400,
        3400,
        3200
      ]
    }
    links: {
      mandate: "MD0000XH9A3T4C"
    },
    metadata: {}
  },
  "instalment_schedule_idempotency_key"
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

int[] amountsArray = new int[]{ 3400, 3400, 3200 };
var createResponse = await gocardless.InstalmentSchedules.CreateWithScheduleAsync(
    new InstalmentScheduleCreateWithScheduleRequest
    {
        TotalAmount = 10000, // 100 GBP in pence, collected from the customer
        AppFee = 10, // Your 10 pence fee, applied to each instalment,
                     // to be paid out to you
        Currency = "GBP",
        Name = "ACME Invoice 103",
        Instalments = new GoCardless
            .Services
            .InstalmentScheduleCreateWithScheduleRequest
            .InstalmentScheduleInstalments
            {
                StartDate = "2019-08-20",
                IntervalUnit = "weekly",
                Interval = 2,
                Amounts = amountsArray
            },
        Metadata = new Dictionary<string, string>
        {
            {"Invoice ID", "001"}
        },
        Links = new GoCardless
            .Services
            .InstalmentScheduleCreateWithScheduleRequest
            .InstalmentScheduleLinks
            {
                Mandate = "MD0000XH9A3T4C"
            },
        IdempotencyKey = "random_instalment_schedule_specific_string"
    }
);
POST https://api.gocardless.com/instalment_schedules HTTP/1.1

{
  "instalment_schedules": {
    "name": "Bike Invoice 271",
    "currency": "GBP",
    "total_amount": "2500",
    "instalments": {
      "start_date": "2019-12-14",
      "interval_unit": "monthly",
      "interval": 1,
      "amounts": [
        "1500",
        "1000"
      ]
    },
    "metadata": {},
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 201 Created
Location: /instalment_schedules/IS123
{
 "instalment_schedules": {
   "id": "IS123",
   "status": "pending",
   "total_amount": "2500",
   "metadata": {},
   "payment_errors": {},
   "links": {
     "mandate": "MD123",
     "customer": "CU123"
   }
 }
}

List instalment schedules

Returns a cursor-paginated list of your instalment schedules.

Relative endpoint: GET /instalment_schedules

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
ID of the associated customer.
limit
Number of records to return.
mandate
ID of the associated mandate which the instalment schedule will create payments against.
status
At most five valid status values
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

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

$client->instalmentSchedules()->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.instalment_schedules.list().records

client.instalment_schedules.list(params={"after": "IS123"}).records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.instalment_schedules.list

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

@client.instalment_schedules.list.records.each do |instalment_schedule|
  puts instalment_schedule.inspect
end
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (InstalmentSchedule instalmentSchedule : client.instalmentSchedules().all().execute()) {
  System.out.println(instalmentSchedule.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const instalmentSchedules = await client.instalmentSchedules.list();

// List all instalment schedules associated with a given customer.
const instalmentSchedules = await client.instalmentSchedules.list({ customer: "CU123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var instalmentScheduleListResponse = gocardless.InstalmentSchedules.All();
foreach (GoCardless.Resources.InstalmentSchedule instalmentSchedule in instalmentScheduleListResponse)
{
    Console.WriteLine(instalmentSchedule.Name);
}
GET https://api.gocardless.com/instalment_schedules?after=IS123 HTTP/1.1

HTTP/1.1 200 OK
{
  "meta": {
    "cursors": {
      "before": "IS000",
      "after": "IS456",
    },
    "limit": 50
  },
  "instalment_schedules": [{
    "id": "IS123",
    "name": "Bike Invoice 271",
    "currency": "GBP",
    "status": "active",
    "total_amount": "2500",
    "metadata": {},
    "payment_errors": {},
    "links": {
      "mandate": "MD123",
      "payments": ["PM123", "PM345"],
      "customer": "CU123"
    }
  }, {
    "id": "IS456",
    "name": "INV-7465",
    "currency": "GBP",
    "status": "cancelled",
    "total_amount": "3600",
    "metadata": {},
    "payment_errors": {},
    "links": {
      "mandate": "MD456",
      "payments": ["PM567", "PM789"],
      "customer": "CU456"
    }
  }]
}

Get a single instalment schedule

Retrieves the details of an existing instalment schedule.

Relative endpoint: GET /instalment_schedules/IS123

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

$client->instalmentSchedules()->get("IS123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.instalment_schedules.get("IS123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

InstalmentSchedule instalmentSchedule = client.instalmentSchedules().get("IS123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const instalmentSchedule = await client.instalmentSchedules.find("IS123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var instalmentScheduleResponse = await gocardless.InstalmentSchedules.GetAsync("IS123");
GoCardless.Resources.Customer instalmentSchedule = instalmentScheduleResponse.InstalmentSchedule;
GET https://api.gocardless.com/instalment_schedules/IS123 HTTP/1.1

HTTP/1.1 200 OK

{
 "instalment_schedules": {
   "id": "IS123",
   "name": "INV-4142",
   "currency": "GBP",
   "status": "active",
   "total_amount": "2500",
   "metadata": {},
   "payment_errors": {},
   "links": {
     "mandate": "MD456",
     "payments": ["PM123", "PM345"],
     "customer": "CU456"
   }
 }
}

{
 "instalment_schedules": {
   "id": "IS123",
   "name": "INV-4142",
   "currency": "GBP",
   "status": "creation_failed",
   "total_amount": "2500",
   "metadata": {},
   "payment_errors": {
     "0": { "field": "description", "message": "was too long" },
     "1": {}
   }
  }
}

Update an instalment schedule

Updates an instalment schedule. This accepts only the metadata parameter.

Relative endpoint: PUT /instalment_schedules/IS123

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->instalmentSchedules()->update("IS123", [
  "params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.instalment_schedules.update("IS123", params={
  "metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.instalment_schedules.update(
  "IS123",
  params: {
    metadata: { key: "value" }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.instalmentSchedules().update("IS123")
  .withMetadata("key", "value")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const instalmentSchedule = await client.instalmentSchedules.update(
  "IS123",
  {
    metadata: {
      key: "value"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var instalmentScheduleRequest = new GoCardless.Services.InstalmentScheduleUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"key", "value"}
    }
};

var instalmentScheduleResponse = await gocardless.InstalmentSchedules.UpdateAsync("IS123", instalmentScheduleRequest);
PUT https://api.gocardless.com/instalment_schedules/IS123 HTTP/1.1
{
  "instalment_schedules": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 OK
{
 "instalment_schedules": {
   "id": "IS123",
   "name": "INV-4142",
   "currency": "GBP",
   "status": "active",
   "total_amount": "2500",
   "metadata": {
     "key": "value"
   },
   "payment_errors": {},
   "links": {
     "mandate": "MD456",
     "payments": ["PM123", "PM345"],
     "customer": "CU456"
   }
  }
}

Cancel an instalment schedule

Immediately cancels an instalment schedule; no further payments will be collected for it.

This will fail with a cancellation_failed error if the instalment schedule is already cancelled or has completed.

Relative endpoint: POST /instalment_schedules/IS123/actions/cancel

Parameters

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

$client->instalmentSchedules()->cancel("IS123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.instalment_schedules.cancel("IS123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.instalmentSchedules().cancel("IS123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const instalmentScheduleResponse = await client.instalmentSchedules.cancel("IS123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var response = await gocardless.InstalmentSchedules.CancelAsync("IS123");
POST https://api.gocardless.com/instalment_schedules/IS123/actions/cancel HTTP/1.1

HTTP/1.1 200 OK
{
  "instalment_schedules": {
    "id": "IS123",
    "name": "Bike Invoice 271",
    "currency": "GBP",
    "status": "cancelled",
    "total_amount": "2500",
    "metadata": {},
    "payment_errors": {},
    "links": {
      "mandate": "MD123",
      "payments": ["PM123", "PM345"],
      "customer": "CU123"
    }
  }
}

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”. Note that this prefix may not apply to mandates created before 2016.
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 that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.
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.
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

  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)

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 and GoCardless Enterprise 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.
payer_ip_address
For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
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.
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"],
               "links" => ["customer_bank_account" => "BA123"]]
]);
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Mandate mandate = client.mandates().create()
  .withScheme("bacs")
  .withLinksCustomerBankAccount("BA123")
  .withMetadata("contract", "ABCD1234")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandate = await client.mandates.create({
  scheme: "bacs",
  metadata: {
    contract: "ABCD1234"
   },
  links: {
    customer_bank_account: "BA123",
    creditor: "CR123"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateRequest = new GoCardless.Services.MandateCreateRequest()
{
    Links = new GoCardless.Services.MandateCreateRequest.MandateLinks()
    {
        CustomerBankAccount = "BA0123"
    },
    Metadata = new Dictionary<string, string>()
    {
        {"internal_reference", "ref_09011991"}
    },
    Scheme = "bacs"
};

var mandateResponse = await gocardless.Mandates.CreateAsync(mandateRequest);
GoCardless.Resources.Mandate mandate = mandateResponse.Mandate;
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",
      "customer": "CU123"
    }
  }
}

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.
scheme
Scheme you’d like to retrieve mandates for
status
At most four 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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Mandate mandate : client.mandates().all().withCustomer("CU123").execute()) {
  System.out.println(mandate.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandates = await client.mandates.list();

// List all mandates associated with a given customer.
const mandates = await client.mandates.list({ customer: "CU123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateRequest = new GoCardless.Services.MandateListRequest()
{
    Customer = "CU000123"
};

var mandateListResponse = gocardless.Mandates.All(mandateRequest);
foreach (GoCardless.Resources.Mandate mandate in mandateListResponse)
{
    Console.WriteLine(mandate.Id);
}
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",
      "customer": "CU123"
    }
  }]
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Mandate mandate = client.mandates().get("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandate = await client.mandates.find("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateResponse = await gocardless.Mandates.GetAsync("MD0123");
GoCardless.Resources.Mandate mandate = mandateResponse.Mandate;
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",
      "customer": "CU123"
    }
  }
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.mandates().update("MD123").withMetadata("contract_id", "ref_09011991").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandate = await client.mandates.update(
  "MD123",
  {
    metadata: {"key": "value"}
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateRequest = new GoCardless.Services.MandateUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"internal_reference", "ref_09011991"}
    }
};

var mandateResponse = await gocardless.Mandates.UpdateAsync("MD0123", mandateRequest);
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",
      "customer": "CU123"
    }
  }
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.mandates().cancel("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateResponse = await client.mandates.cancel("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateResponse = await gocardless.Mandates.CancelAsync("MD0123");
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",
      "customer": "CU123"
    }
  }
}

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 10 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.

Warning: A mandate can only be reinstated if it has been cancelled through the dashboard or the API. Any mandate that has been cancelled by the bank cannot be reinstated.

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.mandates().reinstate("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateResponse = await client.mandates.reinstate("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateResponse = await gocardless.Mandates.ReinstateAsync("MD0123");
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",
      "customer": "CU123"
    }
  }
}

Mandate Imports

Mandate Imports allow you to migrate existing mandates from other providers into the GoCardless platform.

The process is as follows:

  1. Create a mandate import
  2. Add entries to the import
  3. Submit the import
  4. Wait until a member of the GoCardless team approves the import, at which point the mandates will be created
  5. Link up the mandates in your system

When you add entries to your mandate import, they are not turned into actual mandates until the mandate import is submitted by you via the API, and then processed by a member of the GoCardless team. When that happens, a mandate will be created for each entry in the import.

We will issue a mandate_created webhook for each entry, which will be the same as the webhooks triggered when creating a mandate using the mandates API. Once these webhooks start arriving, any reconciliation can now be accomplished by checking the current status of the mandate import and linking up the mandates to your system.

Note that all Mandate Imports have an upper limit of 30,000 entries, so we recommend you split your import into several smaller imports if you’re planning to exceed this threshold.

Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.

Properties

id
Unique identifier, beginning with “IM”.
created_at
Fixed timestamp, recording when this resource was created.
scheme
The scheme of the mandates to be imported.
All mandates in a single mandate import must be for the same scheme.
status
The status of the mandate import.
  • New mandate imports report the created status.

  • When the integrator has finished adding mandates and submitted the import, the status will report as submitted.

  • If the integrator decided to cancel the mandate import, the status will report cancelled.

  • Once a mandate import has been approved by a GoCardless team member, the status will initially report as processing (whilst the mandates are being imported).

  • When the mandates have all been imported successfully, the status will report as processed.

Create a new mandate import

Mandate imports are first created, before mandates are added one-at-a-time, so this endpoint merely signals the start of the import process. Once you’ve finished adding entries to an import, you should submit it.

Relative endpoint: POST /mandate_imports

Parameters

scheme
required A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandateImports()->create([
  "params" => ["scheme" => "bacs"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandate_imports.create(params={
  "scheme": "bacs"
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandate_imports.create(params: {
  scheme: "bacs"
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

MandateImport import = client.mandateImports().create()
  .withScheme(com.gocardless.services.MandateImportService.MandateImportCreateRequest.Scheme.BACS)
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateImport = await client.mandateImports.create({
  scheme: "bacs"
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var importRequest = new GoCardless.Services.MandateImportCreateRequest()
{
    Scheme = MandateImportCreateRequest.MandateImportScheme.Bacs
};

var importResponse = await gocardless.MandateImports.CreateAsync(importRequest);
GoCardless.Resources.MandateImport import = importResponse.MandateImport;
POST https://api.gocardless.com/mandate_imports HTTP/1.1
{
  "mandate_imports": {
    "scheme": "bacs"
  }
}

HTTP/1.1 201 Created
Location: /mandate_imports/IM000010790WX1
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "created",
    "created_at": "2018-03-12T14:03:04.000Z"
  }
}

Get a mandate import

Returns a single mandate import.

Relative endpoint: GET /mandate_imports/IM000010790WX1

Parameters

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

$client->mandateImports()->get("IM000010790WX1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.mandate_imports.get("IM000010790WX1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

MandateImport import = client.mandateImports().get("IM000010790WX1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateImport = await client.mandateImports.find("IM000010790WX1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var response = await gocardless.MandateImports.GetAsync("IM000010790WX1");
GoCardless.Resources.MandateImport import = response.MandateImport;
GET https://api.gocardless.com/mandate_imports/IM000010790WX1 HTTP/1.1

HTTP/1.1 200 OK
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "created",
    "created_at": "2018-03-12T14:03:04.000Z"
  }
}

Submit a mandate import

Submits the mandate import, which allows it to be processed by a member of the GoCardless team. Once the import has been submitted, it can no longer have entries added to it.

In our sandbox environment, to aid development, we automatically process mandate imports approximately 10 seconds after they are submitted. This will allow you to test both the “submitted” response and wait for the webhook to confirm the processing has begun.

Relative endpoint: POST /mandate_imports/IM000010790WX1/actions/submit

Parameters

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

$client->mandateImports()->submit("IM000010790WX1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.mandate_imports.submit("IM000010790WX1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.mandateImports().submit("IM000010790WX1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateImport = await client.mandateImports.submit("IM000010790WX1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var response = await gocardless.MandateImports.SubmitAsync("IM000010790WX1");
GoCardless.Resources.MandateImport import = response.MandateImport;
POST https://api.gocardless.com/mandate_imports/IM000010790WX1/actions/submit HTTP/1.1

HTTP/1.1 200 OK
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "submitted",
    "created_at": "2018-03-12T14:03:04.000Z"
  }
}

POST https://api-sandbox.gocardless.com/mandate_imports/IM000010790WX1/actions/submit HTTP/1.1

HTTP/1.1 200 OK
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "processing",
    "created_at": "2018-03-12T14:03:04.000Z"
  }
}

Cancel a mandate import

Cancels the mandate import, which aborts the import process and stops the mandates being set up in GoCardless. Once the import has been cancelled, it can no longer have entries added to it. Mandate imports which have already been submitted or processed cannot be cancelled.

Relative endpoint: POST /mandate_imports/IM000010790WX1/actions/cancel

Parameters

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

$client->mandateImports()->cancel("IM000010790WX1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.mandate_imports.cancel("IM000010790WX1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.mandateImports().cancel("IM000010790WX1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateImportResponse = await client.mandateImports.cancel("IM000010790WX1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var response = await gocardless.MandateImports.CancelAsync("IM000010790WX1");
GoCardless.Resources.MandateImport import = response.MandateImport;
POST https://api.gocardless.com/mandate_imports/IM000010790WX1/actions/cancel HTTP/1.1

HTTP/1.1 200 OK
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "cancelled",
    "created_at": "2018-03-12T14:03:04.000Z"
  }
}

Mandate Import Entries

Mandate Import Entries are added to a Mandate Import. Each entry corresponds to one mandate to be imported into GoCardless.

To import a mandate you will need:

  1. Identifying information about the customer (name/company and address)
  2. Bank account details, consisting of an account holder name and either an IBAN or local bank details
  3. Amendment details (SEPA only)

We suggest you provide a record_identifier (which is unique within the context of a single mandate import) to help you to identify mandates that have been created once the import has been processed by GoCardless. You can list the mandate import entries, match them up in your system using the record_identifier, and look at the links fields to find the mandate, customer and customer bank account that have been imported.

Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.

Properties

created_at
Fixed timestamp, recording when this resource was created.
record_identifier
A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.
links[customer]
The ID of the customer which was created when the mandate import was processed.
links[customer_bank_account]
The ID of the customer bank account which was created when the mandate import was processed.
links[mandate]
The ID of the mandate which was created when the mandate import was processed.
links[mandate_import]
The ID of the mandate import. This is returned when you create a Mandate Import.

Add a mandate import entry

For an existing mandate import, this endpoint can be used to add individual mandates to be imported into GoCardless.

You can add no more than 30,000 rows to a single mandate import. If you attempt to go over this limit, the API will return a record_limit_exceeded error.

Relative endpoint: POST /mandate_import_entries

Parameters

bank_account[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. This field is required unless the request includes a customer bank account token.
bank_account[account_number]
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_account[bank_code]
Bank code - see local details for more information. Alternatively you can provide an iban.
bank_account[branch_code]
Branch code - see local details for more information. Alternatively you can provide an iban.
bank_account[country_code]
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
bank_account[iban]
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
customer[address_line1]
The first line of the customer’s address. Required if mandate import scheme is either bacs or sepa.
customer[address_line2]
The second line of the customer’s address.
customer[address_line3]
The third line of the customer’s address.
customer[city]
The city of the customer’s address.
customer[company_name]
Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
customer[country_code]
ISO 3166-1 alpha-2 code.
customer[danish_identity_number]
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer[email]
required Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer[family_name]
Customer’s surname. Required unless a company_name is provided.
customer[given_name]
Customer’s first name. Required unless a company_name is provided.
customer[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”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.
customer[phone_number]
ITU E.123 formatted phone number, including country code.
customer[postal_code]
The customer’s postal code. Required if mandate import scheme is either bacs or sepa.
customer[region]
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
customer[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.
amendment[original_creditor_id]
The creditor identifier of the direct debit originator. Required if mandate import scheme is sepa.
amendment[original_creditor_name]
Data about the original mandate to be moved or modified.
amendment[original_mandate_reference]
The unique SEPA reference for the mandate being amended. Required if mandate import scheme is sepa.
record_identifier
A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.
links[mandate_import]
required Unique identifier, beginning with “IM”.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandateImportEntries()->create([
  "params" => [
    "links" => [
      "mandate_import" => "IM000010790WX1"
    ],
    "record_identifier" => "bank-file.xml/line-1",
    "customer" => [
      "company_name" => "Jane's widgets",
      "email" => "jane@janeswidgets.fr"
    ],
    "bank_account" => [
      "account_holder_name" => "Jane Doe",
      "iban" => "FR14BARC20000055779911"
    ],
    "amendment" => [
      "original_mandate_reference" => "REFNMANDATE",
      "original_creditor_id" => "FR123OTHERBANK",
      "original_creditor_name" => "Existing DD Provider"
    ]
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandate_import_entries.create(params={
  "links": {
    "mandate_import": "IM000010790WX1"
  },
  "record_identifier": "bank-file.xml/line-1",
  "customer": {
    "company_name": "Jane's widgets",
    "email": "jane@janeswidgets.fr"
  },
  "bank_account": {
    "account_holder_name": "Jane Doe",
    "iban": "FR14BARC20000055779911"
  },
  "amendment": {
    "original_mandate_reference": "REFNMANDATE",
    "original_creditor_id": "FR123OTHERBANK",
    "original_creditor_name": "Existing DD Provider"
  }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandate_import_entries.create(params: {
  links: {
    mandate_import: "IM000010790WX1"
  },
  record_identifier: "bank-file.xml/line-1",
  customer: {
    company_name: "Jane's widgets",
    email: "jane@janeswidgets.fr"
  },
  bank_account: {
    account_holder_name: "Jane Doe",
    iban: "FR14BARC20000055779911"
  },
  amendment: {
    original_mandate_reference: "REFNMANDATE",
    original_creditor_id: "FR123OTHERBANK",
    original_creditor_name: "Existing DD Provider"
  }
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

MandateImport import = client.mandateImportEntries().create()
  .withCustomerCompanyName("Jane's widgets")
  .withCustomerEmail("jane@janeswidgets.fr")
  .withBankAccountAccountHolderName("Jane Doe")
  .withBankAccountIban("FR14BARC20000055779911")
  .withAmendmentOriginalMandateReference("REFNMANDATE")
  .withAmendmentOriginalCreditorId("FR123OTHERBANK")
  .withAmendmentOriginalCreditorName("Existing DD Provider")
  .withLinksMandateImport("IM000010790WX1")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateImportEntry = await client.mandateImportEntries.create({
  links: {
    mandate_import: "IM000010790WX1"
  },
  record_identifier: "bank-file.xml/line-1",
  customer: {
    company_name: "Jane's widgets",
    email: "jane@janeswidgets.fr"
  },
  bank_account: {
    account_holder_name: "Jane Doe",
    iban: "FR14BARC20000055779911"
  },
  amendment: {
    original_mandate_reference: "REFNMANDATE",
    original_creditor_id: "FR123OTHERBANK",
    original_creditor_name: "Existing DD Provider"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var request = new GoCardless.Services.MandateImportEntryCreateRequest()
{
  Customer = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryCustomer()
  {
    CompanyName = "Jane's widgets"
    Email = "jane@janeswidgets.fr"
  }
  BankAccount = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryBankAccount()
  {
    AccountHolderName = "Jane Doe"
    Iban = "FR14BARC20000055779911"
  }
  Amendment = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryAmendment()
  {
    OriginalMandateReference = "REFNMANDATE"
    OriginalCreditorId = "FR123OTHERBANK"
    OriginalCreditorName = "Existing DD Provider"
  }
  Links = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryLinks()
  {
    MandateImport = "IM000010790WX1"
  }
};

var importResponse = await gocardless.MandateImportEntries.CreateAsync(request);
GoCardless.Resources.MandateImportEntry entry = importResponse.MandateImportEntry;
POST https://api.gocardless.com/mandate_import_entries HTTP/1.1
{
  "mandate_import_entries": {
    "links": {
      "mandate_import": "IM000010790WX1"
    },
    "record_identifier": "bank-file.xml/line-1",
    "customer": {
      "company_name": "Jane's widgets",
      "email": "jane@janeswidgets.fr"
    },
    "bank_account": {
      "account_holder_name": "Jane Doe",
      "iban": "FR14BARC20000055779911"
    },
    "amendment": {
      "original_mandate_reference": "REFNMANDATE",
      "original_creditor_id": "FR123OTHERBANK",
      "original_creditor_name": "Existing DD Provider"
    }
  }
}

HTTP/1.1 201 Created
{
  "mandate_import_entries": {
    "record_identifier": "bank-file.xml/line-1",
    "created_at": "2018-03-03T00:00:00Z",
    "links": {
      "mandate_import": "IM000010790WX1"
    }
  }
}

List all mandate import entries

For an existing mandate import, this endpoint lists all of the entries attached.

After a mandate import has been submitted, you can use this endpoint to associate records in your system (using the record_identifier that you provided when creating the mandate import).

Relative endpoint: GET /mandate_import_entries

Parameters

mandate_import
required Unique identifier, beginning with “IM”.
after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
limit
Number of records to return.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->mandateImportEntries()->all([
  "params" => ["mandate_import" => "IM000010790WX1"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.mandate_import_entries.all(
  params= { "mandate_import": "IM000010790WX1" }
).records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.mandate_import_entries.all(
  params: {
    "mandate_import" => "IM000010790WX1"
  }
).each { |entry| puts entry.record_identifier }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (MandateImportEntry entry : client.mandateImportEntries().all().withMandateImport("IM000010790WX1").execute()) {
  System.out.println(entry.getRecordIdentifier());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const mandateImportEntries = await client.mandateImportEntries.list();
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var request = new GoCardless.Services.MandateImportEntryListRequest()
{
    MandateImport = "IM000010790WX1"
};

var response = gocardless.MandateImportEntries.All(request);
foreach (GoCardless.Resources.MandateImportEntry entry in response)
{
    Console.WriteLine(entry.RecordIdentifier);
}
GET https://api.gocardless.com/mandate_import_entries?mandate_import=IM000010790WX1 HTTP/1.1

HTTP/1.1 200 OK
{
  "mandate_import_entries": [
    {
      "record_identifier": "bank-file.xml/line-2",
      "created_at": "2018-03-03T00:00:01Z",
      "links": {
        "mandate_import": "IM000010790WX1"
      }
    },
    {
      "record_identifier": "bank-file.xml/line-1",
      "created_at": "2018-03-03T00:00:00Z",
      "links": {
        "mandate_import": "IM000010790WX1"
      }
    }
  ],
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  }
}

Payer Authorisations

Payer Authorisation resource acts as a wrapper for creating customer, bank account and mandate details in a single request. PayerAuthorisation API enables the integrators to build their own custom payment pages.

The process to use the Payer Authorisation API is as follows:

  1. Create a Payer Authorisation, either empty or with already available information
  2. Update the authorisation with additional information or fix any mistakes
  3. Submit the authorisation, after the payer has reviewed their information
  4. [coming soon] Redirect the payer to the verification mechanisms from the response of the Submit request (this will be introduced as a non-breaking change)
  5. Confirm the authorisation to indicate that the resources can be created

After the Payer Authorisation is confirmed, resources will eventually be created as it’s an asynchronous process.

To retrieve the status and ID of the linked resources you can do one of the following:

  1. Listen to payer_authorisation_completed webhook (recommended)
  2. Poll the GET endpoint
  3. Poll the GET events API https://api.gocardless.com/events?payer_authorisation={id}&action=completed

Note that the create and update endpoints behave differently than other existing create and update endpoints. The Payer Authorisation is still saved if incomplete data is provided. We return the list of incomplete data in the incomplete_fields along with the resources in the body of the response. The bank account details(account_number, bank_code & branch_code) must be sent together rather than splitting across different request for both create and update endpoints.

The API is designed to be flexible and allows you to collect information in multiple steps without storing any sensitive data in the browser or in your servers.

Properties

id
Unique identifier, beginning with “PA”.
bank_account[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. This field is required unless the request includes a customer bank account token.
bank_account[account_number]
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_account[account_number_ending]
The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
bank_account[account_number_suffix]
Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
bank_account[account_type]
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_account[bank_code]
Bank code - see local details for more information. Alternatively you can provide an iban.
bank_account[branch_code]
Branch code - see local details for more information. Alternatively you can provide an iban.
bank_account[country_code]
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
bank_account[currency]
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
bank_account[iban]
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_account[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.
created_at
Timestamp, recording when this Payer Authorisation was created.
customer[address_line1]
The first line of the customer’s address.
customer[address_line2]
The second line of the customer’s address.
customer[address_line3]
The third line of the customer’s address.
customer[city]
The city of the customer’s address.
customer[company_name]
Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
customer[country_code]
ISO 3166-1 alpha-2 code.
customer[danish_identity_number]
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer[email]
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer[family_name]
Customer’s surname. Required unless a company_name is provided.
customer[given_name]
Customer’s first name. Required unless a company_name is provided.
customer[locale]
An IETF Language Tag, used for both language and regional variations of our product.
customer[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.
customer[postal_code]
The customer’s postal code.
customer[region]
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
customer[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.
incomplete_fields
An array of fields which are missing and is required to set up the mandate.

Each instance will contain these properties:

  • field: The root resource.

  • message: A localised error message

  • request_pointer: The path to the field e.g. “/payer_authorisations/customer/city”

mandate[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.
mandate[payer_ip_address]
For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
mandate[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.
mandate[scheme]
A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
status
One of:
  • created: The PayerAuthorisation has been created, and not been confirmed yet

  • submitted: The payer information has been submitted

  • confirmed: PayerAuthorisation is confirmed and resources are ready to be created

  • completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created

  • failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created

links[bank_account]
Unique identifier, beginning with “BA”.
links[customer]
Unique identifier, beginning with “CU”.
links[mandate]
Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.

Get a single Payer Authorisation

Retrieves the details of a single existing Payer Authorisation. It can be used for polling the status of a Payer Authorisation.

Relative endpoint: GET /payer_authorisations/PA123

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

$client->payerAuthorisations()->get("PAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.payer_authorisations.get("PAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

PayerAuthorisation payerAuthorisation = client.payerAuthorisations.get("PAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payerAuthorisation = await client.payerAuthorisations.find("PAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var payerAuthorisationResponse = await gocardless.payerAuthorisations.GetAsync("PAU123");
GoCardless.Resources.PayerAuthorisation payerAuthorisation = payerAuthorisationResponse.PayerAuthorisation;
GET https://api.gocardless.com/payer_authorisations/PAU123 HTTP/1.1

HTTP/1.1 200 OK
{
"payer_authorisations": {
    "id": "PAU123",
    "created_at": "2020-09-11T14:04:50.579Z",
    "customer": {
        "address_line1": "Unit 12, 2 Somerset Road",
        "address_line2": "terertertre",
        "city": "London",
        "company_name": "",
        "country_code": "US",
        "email": "mail@example.com",
        "family_name": "test",
        "given_name": "lastname",
        "postal_code": "1234",
        "region": "AR",
        "metadata": {}
    },
    "bank_account": {
        "account_holder_name": "test lastname",
        "account_number_ending": "11",
        "account_type": "savings",
        "country_code": "US",
        "bank_name": "COMMUNITY FEDERAL SAVINGS BANK",
        "metadata": {}
    },
    "mandate": {
        "scheme": "ach",
        "metadata": {}
    },
    "status": "completed",
    "incomplete_fields": [],
    "links": {
      "customer": "CU00123",
      "bank_account": "BA00123",
      "mandate": "MD000123"
    }
  }
}

Create a Payer Authorisation

Creates a Payer Authorisation. The resource is saved to the database even if incomplete. An empty array of incomplete_fields means that the resource is valid. The ID of the resource is used for the other actions. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such as a multi-step form.

Relative endpoint: POST /payer_authorisations

Parameters

bank_account[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. This field is required unless the request includes a customer bank account token.
bank_account[account_number]
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_account[account_number_ending]
The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
bank_account[account_number_suffix]
Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
bank_account[account_type]
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_account[bank_code]
Bank code - see local details for more information. Alternatively you can provide an iban.
bank_account[branch_code]
Branch code - see local details for more information. Alternatively you can provide an iban.
bank_account[country_code]
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
bank_account[currency]
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
bank_account[iban]
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_account[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.
customer[address_line1]
The first line of the customer’s address.
customer[address_line2]
The second line of the customer’s address.
customer[address_line3]
The third line of the customer’s address.
customer[city]
The city of the customer’s address.
customer[company_name]
Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
customer[country_code]
ISO 3166-1 alpha-2 code.
customer[danish_identity_number]
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer[email]
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer[family_name]
Customer’s surname. Required unless a company_name is provided.
customer[given_name]
Customer’s first name. Required unless a company_name is provided.
customer[locale]
An IETF Language Tag, used for both language and regional variations of our product.
customer[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.
customer[postal_code]
The customer’s postal code.
customer[region]
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
customer[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.
mandate[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.
mandate[payer_ip_address]
For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
mandate[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.
mandate[scheme]
A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payerAuthorisations()->create([
  "params" => ["customer" => [
      "email" => "mail@example.com",
      "given_name" => "Name",
      "family_name" => "Surname",
      "metadata" => [
        "salesforce_id" => "EFGH5678"
      ]
    ],
    "bank_account" => [
      "account_holder_name" => "Name Surname",
      "branch_code" => "200000",
      "account_number" => "55779911",
      "metadata" => []
    ],
    "mandate" => [
      "reference" => "XYZ789",
      "metadata" => []
    ]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payer_authorisations.create(params={
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {}
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payer_authorisations.create(
  params: {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

PayerAuthorisation payerAuthorisation = client.payerAuthorisations().create()
  .withCustomerEmail("mail@example.com")
  .withCustomerGivenName("Name")
  .withCustomerFamilyName("Surname")
  .withCustomerMetadata()
  .withBankAccountAccountHolderName("Name Surname")
  .withBankAccountBranchCode("200000")
  .withBankAccountAccountNumber("55779911")
  .withBankAccountMetadata()
  .withMandateReference("XYZ789")
  .withMandateMetadata()
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payerAuthorisation = await client.payerAuthorisations.create({
  "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customer = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationCustomer()
{
  "email" = "mail@example.com",
  "given_name" = "Name",
  "family_name" = "Surname",
  "metadata" = {}
};
var bankAccount = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationBankAccount()
{
  "account_holder_name" = "Name Surname",
  "branch_code" = "200000",
  "account_number" = "55779911",
  "metadata" = {}
};
var mandate = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationMandate()
{
  "reference" = "XYZ789",
  "metadata" = {}
};
var PayerAuthorisationRequest = new GoCardless.Services.PayerAuthorisationCreateRequest()
{
    Customer = customer,
    BankAccount = bankAccount,
    Mandate = mandate
};
var PayerAuthorisationResponse = await gocardless.PayerAuthorisations.CreateAsync(PayerAuthorisationRequest);
GoCardless.Resources.PayerAuthorisation payerAuthorisation = PayerAuthorisationResponse.PayerAuthorisation;
POST https://api.gocardless.com/payer_authorisations HTTP/1.1
{
  "payer_authorisations": {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
  }
}

Example response with incomplete_fields

HTTP/1.1 201 Created
Location: /payer_authorisations/PA123
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "created",
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "bank_name": "BARCLAYS BANK",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields":[
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/address_line1"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/city"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/postal_code"
      }
    ]
  }
}

Example response with all properties

HTTP/1.1 201 Created
{
  "payer_authorisations": {
      "id": "PA123",
      "created_at": "2020-04-15T15:00:00.000Z",
      "status": "created",
      "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "bank_name": "BARCLAYS BANK",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
      "links": {},
      "incomplete_fields": []
  }
}

Example response with errors

 HTTP/1.1 422 Unprocessable entity
{
  "error": {
      "message": "Validation failed",
      "errors": [
          {
              "field": "bank_account",
              "message": "is the wrong length (should be 8 characters)",
              "request_pointer": "/payer_authorisations/bank_account/account_number"
          },
          {
              "field": "bank_account",
              "message": "is required",
              "request_pointer": "/payer_authorisations/bank_account/branch_code"
          },
          {
              "field": "bank_account",
              "message": "is required",
              "request_pointer": "/payer_authorisations/bank_account/branch_code"
          }
      ],
      "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
      "type": "validation_failed",
      "request_id": "5a83ff47-cfb0-4bb8-8bcd-a3bddf0118e1",
      "code": 422
  }
}

Update a Payer Authorisation

Updates a Payer Authorisation. Updates the Payer Authorisation with the request data. Can be invoked as many times as needed. Only fields present in the request will be modified. An empty array of incomplete_fields means that the resource is valid. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such a multi-step form. Note that in order to update the metadata attribute values it must be sent completely as it overrides the previously existing values.

Relative endpoint: PUT /payer_authorisations/PA123

Parameters

bank_account[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. This field is required unless the request includes a customer bank account token.
bank_account[account_number]
Bank account number - see local details for more information. Alternatively you can provide an iban.
bank_account[account_number_ending]
The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
bank_account[account_number_suffix]
Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
bank_account[account_type]
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_account[bank_code]
Bank code - see local details for more information. Alternatively you can provide an iban.
bank_account[branch_code]
Branch code - see local details for more information. Alternatively you can provide an iban.
bank_account[country_code]
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
bank_account[currency]
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
bank_account[iban]
International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_account[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.
customer[address_line1]
The first line of the customer’s address.
customer[address_line2]
The second line of the customer’s address.
customer[address_line3]
The third line of the customer’s address.
customer[city]
The city of the customer’s address.
customer[company_name]
Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
customer[country_code]
ISO 3166-1 alpha-2 code.
customer[danish_identity_number]
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer[email]
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer[family_name]
Customer’s surname. Required unless a company_name is provided.
customer[given_name]
Customer’s first name. Required unless a company_name is provided.
customer[locale]
An IETF Language Tag, used for both language and regional variations of our product.
customer[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.
customer[postal_code]
The customer’s postal code.
customer[region]
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
customer[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.
mandate[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.
mandate[payer_ip_address]
For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
mandate[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.
mandate[scheme]
A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payerAuthorisations()->update("PA123", [
  "params" => ["customer" => [
      "email" => "mail@example.com",
      "given_name" => "Name",
      "family_name" => "Surname",
      "metadata" => {
        "salesforce_id" => "EFGH5678"
      }
    ],
    "bank_account" => [
      "account_holder_name" => "Name Surname",
      "branch_code" => "200000",
      "account_number" => "55779911",
    ],
    "mandate" => [
      "reference" => "XYZ789",
    ]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payer_authorisations.update("PA123", params={
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
    },
    "mandate": {
      "reference": "XYZ789",
    }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payer_authorisations.update(
  "PA123",
  params: {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
    },
    "mandate": {
      "reference": "XYZ789",
    }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

PayerAuthorisation payerAuthorisation = client.payerAuthorisations().update("PA123")
  .withCustomerEmail("mail@example.com")
  .withCustomerGivenName("Name")
  .withCustomerFamilyName("Surname")
  .withCustomerMetadata("salesforce_id", "EFGH5678")
  .withBankAccountAccountHolderName("Name Surname")
  .withBankAccountBranchCode("200000")
  .withBankAccountAccountNumber("55779911")
  .withMandateReference("XYZ789")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payerAuthorisation = await client.payerAuthorisations.update(
  "PA123",
  {
    "customer": {
        "email": "mail@example.com",
        "given_name": "Name",
        "family_name": "Surname",
        "metadata": {
          "salesforce_id": "EFGH5678"
        }
      },
      "bank_account": {
        "account_holder_name": "Name Surname",
        "branch_code": "200000",
        "account_number": "55779911",
        "metadata": {}
      },
      "mandate": {
        "reference": "XYZ789",
        "metadata": {}
      }
  });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customer = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationCustomer()
{
  "email" = "mail@example.com",
  "given_name" = "Name",
  "family_name" = "Surname",
  "metadata" = {
    "salesforce_id" = "EFGH5678"
  }
};
var bankAccount = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationBankAccount()
{
  "account_holder_name" = "Name Surname",
  "branch_code" = "200000",
  "account_number" = "55779911",
};
var mandate = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationMandate()
{
  "reference" = "XYZ789",
};
var PayerAuthorisationRequest = new GoCardless.Services.PayerAuthorisationUpdateRequest()
{
    Customer = customer,
    BankAccount = bankAccount,
    Mandate = mandate
};
var PayerAuthorisationResponse = await gocardless.PayerAuthorisations.UpdateAsync("PA123", PayerAuthorisationRequest);
PUT https://api.gocardless.com/payer_authorisations/PA123 HTTP/1.1
{
  "payer_authorisations": {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911"
    },
    "mandate": {
      "reference": "XYZ789",
    }
  }
}

Example response with incomplete fields

HTTP/1.1 200 OK
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "created",
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "bank_name": "BARCLAYS BANK",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
    "links": {},
    "incomplete_fields":[
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/address_line1"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/city"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/postal_code"
      }
    ]
  }
}

Example response where Payer Authorisation is updated after submitting

HTTP/1.1 422 Bad Request
{
  "error": {
    "message": "The Payer Authorisation cannot be updated after submitted",
    "errors": [
        {
            "reason": "payer_authorisation_cannot_update_after_submit",
            "message": "The Payer Authorisation cannot be updated after submitting"
        }
    ],
    "documentation_url": "https://developer.gocardless.com/api-reference#payer_authorisation_cannot_update_after_submit",
    "type": "invalid_state",
    "request_id": "...",
    "code": 422
  }
}

 Example response with errors

 HTTP/1.1 422 Unprocessable entity
{

  "error": {
      "message": "Validation failed",
      "errors": [
          {
              "field": "customer",
              "message": "is not valid",
              "request_pointer": "/payer_authorisations/customer/email"
          }
      ],
      "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
      "type": "validation_failed",
      "request_id": "2f0db86c-251c-432a-a7af-b77f1a426a37",
      "code": 422
  }

}

Submit a Payer Authorisation

Submits all the data previously pushed to this PayerAuthorisation for verification. This time, a 200 HTTP status is returned if the resource is valid and a 422 error response in case of validation errors. After it is successfully submitted, the Payer Authorisation can no longer be edited.

Relative endpoint: POST /payer_authorisations/PA123/actions/submit

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

$client->payerAuthorisations()->submit("PAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.payer_authorisations.submit("PAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

PayerAuthorisation payerAuthorisation = client.payerAuthorisations.submit("PAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payerAuthorisation = await client.payerAuthorisations.submit("PAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var payerAuthorisationResponse = await gocardless.payerAuthorisations.SubmitAsync("PAU123");
POST https://api.gocardless.com/payer_authorisations/PA123/actions/submit HTTP/1.1

HTTP/1.1 200 OK
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "submitted",
    "customer": {
        "email": "mail@example.com",
        "given_name": "Name",
        "family_name": "Surname",
        "metadata": {
          "salesforce_id": "EFGH5678"
        }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "bank_name": "BARCLAYS BANK",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields": []
  }
}

or

Example response with errors

 HTTP/1.1 422 Unprocessable entity
{

  "error": {
      "message": "Validation failed",
      "errors": [
          {
              "field": "customer",
              "message": "is not valid",
              "request_pointer": "/payer_authorisations/customer/email"
          }
      ],
      "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
      "type": "validation_failed",
      "request_id": "2f0db86c-251c-432a-a7af-b77f1a426a37",
      "code": 422
  }

}

or

 Example response if the resource is already submitted

 HTTP/1.1 304 Not modified
 {}

Confirm a Payer Authorisation

Confirms the Payer Authorisation, indicating that the resources are ready to be created. A Payer Authorisation cannot be confirmed if it hasn’t been submitted yet.

The main use of the confirm endpoint is to enable integrators to acknowledge the end of the setup process. They might want to make the payers go through some other steps after they go through our flow or make them go through the necessary verification mechanism (upcoming feature).

Relative endpoint: POST /payer_authorisations/PA123/actions/confirm

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

$client->payerAuthorisations()->confirm("PAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.payer_authorisations.confirm("PAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

PayerAuthorisation payerAuthorisation = client.payerAuthorisations.confirm("PAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payerAuthorisation = await client.payerAuthorisations.confirm("PAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var payerAuthorisationResponse = await gocardless.payerAuthorisations.ConfirmAsync("PAU123");
POST https://api.gocardless.com/payer_authorisations/PA123/actions/confirm HTTP/1.1


HTTP/1.1 200 OK
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "confirmed",
    "customer": {
        "email": "mail@example.com",
        "given_name": "Name",
        "family_name": "Surname",
        "metadata": {
          "salesforce_id": "EFGH5678"
        }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "bank_name": "BARCLAYS BANK",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields": []
  }
}

or

HTTP/1.1 422 Bad Request
{
  "error": {
    "message": "The Payer Authorisation needs to be submitted before confirmation",
    "errors": [
      {
        "reason": "payer_authorisation_submit_before_confirm",
        "message": "The Payer Authorisation needs to be submitted before confirmation"
      }
    ],
    "documentation_url": "https://developer.gocardless.com/api-reference#payer_authorisation_submit_before_confirm",
    "type": "invalid_state",
    "request_id": "...",
    "code": 422
  }
}

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 the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
amount_refunded
Amount refunded, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
charge_date
A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate’s next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” 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).
fx[estimated_exchange_rate]
Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.
fx[exchange_rate]
Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.
fx[fx_amount]
Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.
fx[fx_currency]
ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
PAD - 12 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus, Pro or Enterprise packages.
retry_if_possible
On failure, automatically retry the payment using intelligent retries. Default is false.
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[instalment_schedule]
ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.
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. Payment references may be up to 140 characters for SEPA, 11 for Autogiro and 30 for Betalingsservice, irrespective of the mandate reference.

Parameters

amount
required Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
currency
required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
app_fee
The amount to be deducted from the payment as the OAuth app’s fee, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
charge_date
A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate’s next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
PAD - 12 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus, Pro or Enterprise packages.
retry_if_possible
On failure, automatically retry the payment using intelligent retries. Default is false.
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"
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

import com.gocardless.services.PaymentService.PaymentCreateRequest.Currency;

Payment payment = client.payments().create()
  .withAmount(100)
  .withCurrency(Currency.GBP)
  .withChargeDate("2014-05-19")
  .withReference("WINEBOX001")
  .withMetadata("order_dispatch_date", "2014-05-22")
  .withLinksMandate("MD123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payment = await client.payments.create({
  amount: 100,
  currency: "GBP",
  charge_date: "2014-05-19",
  reference: "WINEBOX001",
  metadata: {
    order_dispatch_date: "2014-05-22"
  },
  links: {
    mandate: "MD123"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentRequest = new GoCardless.Services.PaymentCreateRequest()
{
    Amount = 1000,
    Currency = GoCardless.Services.PaymentCreateRequest.PaymentCurrency.GBP,
    Description = "Membership fee",
    Links = new GoCardless.Services.PaymentCreateRequest.PaymentLinks()
    {
        Mandate = "MD0123"
    }
};

var paymentResponse = await gocardless.Payments.CreateAsync(paymentRequest);
GoCardless.Resources.Payment payment = paymentResponse.Payment;
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,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}

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.
charge_date[gt]
Limit to records where the payment was or will be collected from the customer’s bank account after the specified date.
charge_date[gte]
Limit to records where the payment was or will be collected from the customer’s bank account on or after the specified date.
charge_date[lt]
Limit to records where the payment was or will be collected from the customer’s bank account before the specified date.
charge_date[lte]
Limit to records where the payment was or will be collected from the customer’s bank account on or before the specified date.
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 “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” 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”. Note that this prefix may not apply to mandates created before 2016.
sort_direction
The direction to sort in.
sort_field
Field by which to sort records.
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Payment payment : client.payments().all().withCustomer("CU123").execute()) {
  System.out.println(payment.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payments = await client.payments.list();

// List all payments past a certain date.
const payments = await client.payments.list({
  created_at: {
    gt: "2020-01-01T17:01:06.000Z"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentRequest = new GoCardless.Services.PaymentListRequest()
{
    Customer = "CU000123"
};

var paymentListResponse = gocardless.Payments.All(paymentRequest);
foreach (GoCardless.Resources.Payment payment in paymentListResponse)
{
    Console.WriteLine(payment.Id);
}
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,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }]
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Payment payment = client.payments().get("PM123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payment = await client.payments.find("PM123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentResponse = await gocardless.Payments.GetAsync("PM0123");
GoCardless.Resources.Payment payment = paymentResponse.Payment;
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,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}

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.
retry_if_possible
On failure, automatically retry the payment using intelligent retries. Default is false.
$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.payments().update("PM123")
  .withMetadata("order_id", "transaction-0HE9WQ0WDE")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payment = await client.payments.update(
  "PM123",
  {
    metadata: {
      key: "value"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentRequest = new GoCardless.Services.PaymentUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"invoice_id", "INVOICE338"}
    }
};

var paymentResponse = await gocardless.Payments.UpdateAsync("PM0123", paymentRequest);
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,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.payments().cancel("PM123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const paymentResponse = await client.payments.cancel("PM123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentResponse = await gocardless.Payments.CancelAsync("PM0123");
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,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}

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

charge_date
A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate’s next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.
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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.payments().retry("PM123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const paymentResponse = await client.payments.retry("PM123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentResponse = await gocardless.Payments.RetryAsync("PM0123");
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,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}

Payouts

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

Properties

id
Unique identifier, beginning with “PO”.
amount
Amount in minor unit (e.g. pence in GBP, cents in EUR).
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 “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
deducted_fees
Fees that have already been deducted from the payout amount in minor unit (e.g. pence in GBP, cents in EUR), inclusive of tax if applicable.

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 value.

This field is calculated as (GoCardless fees + app fees + surcharge fees) - (refunded fees)

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

fx[estimated_exchange_rate]
Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.
fx[exchange_rate]
Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.
fx[fx_amount]
Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.
fx[fx_currency]
ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
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.
payout_type
Whether a payout contains merchant revenue or partner fees.
reference
Reference which appears on the creditor’s bank statement.
status
One of:
  • pending: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider.

  • paid: the payout has been sent to the your bank. FX payouts will become paid after we emit the fx_rate_confirmed webhook.

  • bounced: the payout bounced when sent, the payout can be retried.

tax_currency
ISO 4217 code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR”, “GBP”, for French or British merchants, this will be null if tax is not applicable beta
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 “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
limit
Number of records to return.
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.
payout_type
Whether a payout contains merchant revenue or partner fees.
reference
Reference which appears on the creditor’s bank statement.
status
One of:
  • pending: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider.

  • paid: the payout has been sent to the your bank. FX payouts will become paid after we emit the fx_rate_confirmed webhook.

  • bounced: the payout bounced when sent, the payout can be retried.

$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Payout payout : client.payouts().all().withStatus("pending").execute()) {
  System.out.println(payout.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payouts = await client.payouts.list();

// List all payouts with a given status.
await client.payouts.list({ status: "pending" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var payoutRequest = new GoCardless.Services.PayoutListRequest()
{
    Currency = GoCardless.Services.PayoutListRequest.PayoutCurrency.EUR,
};

var payoutListResponse = gocardless.Payouts.All(payoutRequest);
foreach (GoCardless.Resources.Payout payout in payoutListResponse)
{
    Console.WriteLine(payout.Amount);
}
GET https://api.gocardless.com/payouts HTTP/1.1

HTTP/1.1 200 OK
{
  "payouts": [{
    "id": "PO123",
    "amount": 1000,
    "arrival_date": "2014-06-27",
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "payout_type": "merchant",
    "reference": "ref-1",
    "status": "pending",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.11667"
    },
    "tax_currency": "GBP",
    "metadata":{ "key": "value" },
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.payouts().get("PO123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payout = await client.payouts.find("PO123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var payoutResponse = await gocardless.Payouts.GetAsync("PO0123");
GoCardless.Resources.Payout payout = payoutResponse.Payout;
GET https://api.gocardless.com/payouts/PO123 HTTP/1.1

HTTP/1.1 200 OK
{
  "payouts": {
    "id": "PO123",
    "amount": 1000,
    "arrival_date": "2014-06-27",
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "payout_type": "merchant",
    "reference": "ref-1",
    "status": "pending",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.11667"
    },
    "tax_currency": "GBP",
    "metadata":{ "key": "value" },
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Update a payout

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

Relative endpoint: PUT /payouts/PO123

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->payouts()->update("PO123", [
  "params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payouts.update("PO123", params={
  "metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payouts.update(
  "PO123",
  params: {
    metadata: { key: "value" }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.payouts().update("PO123")
  .withMetadata("key", "value")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payout = await client.payouts.update(
  "PO123",
  {
    metadata: {
      key: "value"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var payoutRequest = new GoCardless.Services.PayoutUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"key", "value"}
    }
};

var payoutResponse = await gocardless.Payouts.UpdateAsync("PO123", payoutRequest);
PUT https://api.gocardless.com/payouts/PO123 HTTP/1.1
{
  "payouts": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 OK
{
  "payouts": {
    "id": "PO123",
    "amount": 1000,
    "arrival_date": "2014-06-27",
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "payout_type": "merchant",
    "reference": "ref-1",
    "status": "pending",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.11667"
    },
    "tax_currency": "GBP",
    "metadata":{"key":"value"},
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Payout Items

When we collect a payment on your behalf, we add the money you’ve collected to your GoCardless balance, minus any fees paid. Periodically (usually every working day), we take any positive balance in your GoCardless account, and pay it out to your nominated bank account.

Other actions in your GoCardless account can also affect your balance. For example, if a customer charges back a payment, we’ll deduct the payment’s amount from your balance, but add any fees you paid for that payment back to your balance.

The Payout Items API allows you to view, on a per-payout basis, the credit and debit items that make up that payout’s amount.

Properties

amount
The positive (credit) or negative (debit) value of the item, in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place. For accuracy, we store some of our fees to greater precision than we can actually pay out (for example, a GoCardless fee we record might come to 0.5 pence, but it is not possible to send a payout via bank transfer including a half penny).

To calculate the final amount of the payout, we sum all of the items and then round to the nearest currency unit.
taxes
An array of tax items beta

Note: VAT applies to transaction and surcharge fees for merchants operating in the UK and France.

Each instance will contain these properties:

  • amount: The amount of tax applied to a fee in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.

  • currency: ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.

  • destination_amount: The amount of tax to be paid out to the tax authorities in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.

    When currency and destination_currency don’t match this will be null until the exchange_rate has been finalised.

  • destination_currency: ISO 4217 code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR” for French merchants and “GBP” for British merchants.

  • exchange_rate: The exchange rate for the tax from the currency into the destination currency.

    Present only if the currency and the destination currency don’t match and the exchange rate has been finalised.

    You can listen for the payout’s tax_exchange_rates_confirmed webhook to know when the exchange rate has been finalised for all fees in the payout.

  • tax_rate_id: The unique identifier created by the jurisdiction, tax type and version

type
The type of the credit (positive) or debit (negative) item in the payout (inclusive of VAT if applicable). One of:
  • payment_paid_out (credit)

  • payment_failed (debit): The payment failed to be processed.

  • payment_charged_back (debit): The payment has been charged back.

  • payment_refunded (debit): The payment has been refunded to the customer.

  • refund (debit): A refund sent to a customer, not linked to a payment.

  • refund_funds_returned (credit): The refund could not be sent to the customer, and the funds have been returned to you.

  • gocardless_fee (credit/debit): The fees that GoCardless charged for a payment. In the case of a payment failure or chargeback, these will appear as credits. Will include taxes if applicable for merchants.

  • app_fee (credit/debit): The optional fees that a partner may have taken for a payment. In the case of a payment failure or chargeback, these will appear as credits.

  • revenue_share (credit/debit): A share of the fees that GoCardless collected which some partner integrations receive when their users take payments. Only shown in partner payouts. In the case of a payment failure or chargeback, these will appear as credits.

  • surcharge_fee (credit/debit): GoCardless deducted a surcharge fee as the payment failed or was charged back, or refunded a surcharge fee as the bank or customer cancelled the chargeback. Will include taxes if applicable for merchants.

links[mandate]
Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
links[payment]
Unique identifier, beginning with “PM”.
links[refund]
Unique identifier, beginning with “RF”.

Get all payout items in a single payout

Returns a cursor-paginated list of items in the payout.

Relative endpoint: GET /payout_items

Parameters

payout
required Unique identifier, beginning with “PO”.
after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
include_2020_tax_cutover
Boolean value indicating whether the API should return tax data for the cutover period of April to August 2020. Defaults to false.
limit
Number of records to return.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->payoutItems()->list([
  'params' => ['payout' => 'PO123']
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.payout_items.list(params={'payout': 'PO123'})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.payout_items.list(params: {payout: "PO123"})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.payoutItems().all().withPayout("PO123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const payoutItems = await client.payoutItems.list({ payout: "P0123" });

// List the first three payout items for a payout
const payoutItems = await client.payoutItems.list({ payout: "P0123", limit: 3 });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var itemsRequest = new GoCardless.Services.PayoutItemsListRequest()
{
    Payout = "PO123"
};

var response = gocardless.PayoutItems.All(payoutRequest);
foreach (GoCardless.Resources.PayoutItem item in response)
{
    Console.WriteLine(item.Amount);
}
GET https://api.gocardless.com/payout_items?payout=PO123 HTTP/1.1

HTTP/1.1 200 OK
{
  "payout_items": [
    {
      "amount": "1000.0",
      "type": "payment_paid_out",
      "taxes": [],
      "links": {
        "payment": "PM123"
      }
    },
    {
      "amount": "30.0",
      "type": "payment_paid_out",
      "taxes": [],
      "links": {
        "payment": "PM456"
      }
    },
    {
      "amount": "-500.0",
      "type": "payment_refunded",
      "taxes": [],
      "links": {
        "payment": "PM789"
      }
    },
    {
      "amount": "-24.0",
      "type": "gocardless_fee",
      "taxes": [{
        "amount": "4.0",
        "currency": "EUR",
        "destination_amount": "4.0",
        "destination_currency": "EUR",
        "exchange_rate": null,
        "tax_rate_id": "FR_VAT_1",
      }],
      "links": {
        "payment": "PM123"
      }
    },
    {
      "amount": "4.0",
      "type": "gocardless_fee",
      "taxes": [{
        "amount": "1.0",
        "currency": "GBP",
        "destination_amount": "1.1",
        "destination_currency": "EUR",
        "exchange_rate": "1.11205",
        "tax_rate_id": "FR_VAT_1"
      }],
      "links": {
        "payment": "PM456"
      }
    },
    {
      "amount": "4.0",
      "type": "gocardless_fee",
      "taxes": [{
        "amount": "1.0",
        "currency": "GBP",
        "destination_amount": "1.1",
        "destination_currency": "EUR",
        "exchange_rate": "1.11205",
        "tax_rate_id": "FR_VAT_1"
      }],
      "links": {
        "payment": "PM456"
      }
    },
    {
      "amount": "-1.0",
      "type": "app_fee",
      "taxes": [],
      "links": {
        "payment": "PM456"
      }
    },
  ],
  "meta": {
    "cursors": { "before": null, "after": null },
    "limit": 50
  }
}

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 Danish, Dutch, French, German, Italian, Norwegian, Portuguese, Slovak, 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.

Once you have completed the redirect flow via the API, you should display a confirmation page to your customer, confirming that their Direct Debit has been set up. You can build your own page, or redirect to the one we provide in the confirmation_url attribute of the redirect flow.

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

Properties

id
Unique identifier, beginning with “RE”.
confirmation_url
The URL of a confirmation page, which you may optionally redirect the customer to rather than use your own page, that confirms in their chosen language that their Direct Debit has been set up successfully. Only returned once the customer has set up their mandate via the payment pages and the redirect flow has been completed, and only available for 15 minutes from when you complete the redirect flow. The structure of this URL may change at any time, so you should read it directly from the API response.
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.
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.
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

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.
description
A description of the item the customer is paying for. This will be shown on the hosted payment pages.
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.
prefilled_bank_account[account_type]
Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
prefilled_customer[address_line1]
The first line of the customer’s address.
prefilled_customer[address_line2]
The second line of the customer’s address.
prefilled_customer[address_line3]
The third line of the customer’s address.
prefilled_customer[city]
The city of the customer’s address.
prefilled_customer[company_name]
Customer’s company name. Company name should only be provided if given_name and family_name are null.
prefilled_customer[country_code]
ISO 3166-1 alpha-2 code.
prefilled_customer[danish_identity_number]
For Danish customers only. The civic/company number (CPR or CVR) of the customer.
prefilled_customer[email]
Customer’s email address.
prefilled_customer[family_name]
Customer’s surname.
prefilled_customer[given_name]
Customer’s first name.
prefilled_customer[language]
ISO 639-1 code.
prefilled_customer[phone_number]
For New Zealand customers only.
prefilled_customer[postal_code]
The customer’s postal code.
prefilled_customer[region]
The customer’s address region, county or department.
prefilled_customer[swedish_identity_number]
For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.
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.
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",
               "prefilled_customer" => [
                 "given_name" => "Frank",
                 "family_name" => "Osborne",
                 "email" => "frank.osborne@acmeplc.com"
               ]]
]);
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",
    "prefilled_customer": {
        "given_name": "Frank",
        "family_name": "Osborne",
        "email": "frank.osborne@acmeplc.com"
    }
})
@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",
    prefilled_customer: {
      given_name: "Frank",
      family_name: "Osborne",
      email: "frank.osborne@acmeplc.com"
    }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

RedirectFlow redirectFlow = client.redirectFlows().create()
  .withDescription("Wine boxes")
  .withSessionToken("SESS_wSs0uGYMISxzqOBq")
  .withSuccessRedirectUrl("https://example.com/pay/confirm")
  .withPrefilledCustomerGivenName("Frank")
  .withPrefilledCustomerFamilyName("Osborne")
  .withPrefilledCustomerEmail("frank.osborne@acmeplc.com")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const redirectFlow = await client.redirectFlows.create({
  description: "Wine boxes",
  session_token: "SESS_wSs0uGYMISxzqOBq",
  success_redirect_url: "https://example.com/pay/confirm",
  prefilled_customer: {
    given_name: "Frank",
    family_name: "Osborne",
    email: "frank.osborne@acmeplc.com"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var prefilledCustomer = new GoCardless.Services.RedirectFlowCreateRequest.RedirectFlowPrefilledCustomer()
{
    AddressLine1 = "338 Goswell Road",
    Email = "api@gocardless.com",
    GivenName = "Bobby",
    FamilyName = "Tables"
};

var redirectFlowRequest = new GoCardless.Services.RedirectFlowCreateRequest()
{
    Description = "Gold package",
    SessionToken = "SESS_wSs0uGYMISxzqOBq",
    SuccessRedirectUrl = "https://example.com/pay/confirm",
    PrefilledCustomer = prefilledCustomer
};

var redirectFlowResponse = await gocardless.RedirectFlows.CreateAsync(redirectFlowRequest);
GoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;

Console.WriteLine(redirectFlow.RedirectUrl);
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",
    "prefilled_customer": {
      "given_name": "Frank",
      "family_name": "Osborne",
      "email": "frank.osborne@acmeplc.com"
    },
    "links": {
         "creditor": "CR123"
     }
  }
}

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.com/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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

RedirectFlow redirectFlow = client.redirectFlows.get("RE123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const redirectFlow = await client.redirectFlows.find("RE123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var redirectFlowResponse = await gocardless.RedirectFlows.GetAsync("RE123");
GoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;
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.com/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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.redirectFlows().complete("RE123")
  .withSessionToken("SESS_wSs0uGYMISxzqOBq")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const redirectFlowResponse = await client.redirectFlows.complete(
  "RE123",
  {
    session_token: "SESS_wSs0uGYMISxzqOBq"
  }
)
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var redirectFlowRequest = new GoCardless.Services.RedirectFlowCompleteRequest()
{
    SessionToken = "SESS_wSs0uGYMISxzqOBq"
};

var redirectFlowResponse = await gocardless.RedirectFlows.CompleteAsync("RE123", redirectFlowRequest);
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",
    "confirmation_url": "https://pay.gocardless.com/flow/RE123/success"
    "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 minor unit (e.g. pence in GBP, cents in EUR).
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.
fx[estimated_exchange_rate]
Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.
fx[exchange_rate]
Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.
fx[fx_amount]
Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.
fx[fx_currency]
ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
PAD - 12 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus, Pro or Enterprise packages.
status
One of:
  • created: the refund has been created

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

  • submitted: the refund has been submitted to the banks

  • paid: the refund has been included in a payout

  • cancelled: the refund has been cancelled

  • bounced: the refund has failed to be paid

  • funds_returned: the refund has had its funds returned

links[mandate]
ID of the mandate against which the refund is being made.
links[payment]
ID of the payment against which the refund is being made.

Create a refund

Creates a new refund object.

This fails with:

  • 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.

  • available_refund_amount_insufficient if the creditor does not have sufficient balance for refunds available to cover the cost of the requested refund.

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.

A refund can only be created once it is outside the safer refund period (7 calendar days after the charge date) otherwise an error is returned. The safer refund period can be disabled by contacting GoCardless.

Parameters

amount
required Amount in minor unit (e.g. pence in GBP, cents in EUR).
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
PAD - 12 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus, Pro or Enterprise packages.
total_amount_confirmation
Total expected refunded amount in minor unit (e.g. 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.
Must be supplied if links[payment] is present.
links[mandate]
ID of the mandate against which the refund is being made.
Restricted: You must request access to Mandate Refunds by contacting our support team.
links[payment]
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(params={
  "amount": 100,
  "total_amount_confirmation": 150,
  "reference": "Nude Wines refund",
  "metadata": {
    "reason": "late delivery"
  },
  "links": {
    "payment": "PM123"
  }
})
@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"}
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.refunds().create()
  .withAmount(100)
  .withTotalAmountConfirmation(150)
  .withReference("Nude Wines refund")
  .withMetadata("reason", "late delivery")
  .withLinksPayment("PM123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const refund = await client.refunds.create({
  amount: 100,
  total_amount_confirmation: 150,
  reference: "Nude Wines refund",
  metadata: {
    reason: "late delivery"
  },
  links: {
    payment: "PM123"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var refundRequest = new GoCardless.Services.RefundCreateRequest()
{
    Amount = 100,
    TotalAmountConfirmation = 150,
    Reference = "Partial refund",
    Links = new GoCardless.Services.RefundCreateRequest.RefundLinks()
    {
        Payment = "PM0123"
    }
};
var refundResponse = await gocardless.Refunds.CreateAsync(refundRequest);
GoCardless.Resources.Refund refund = refundResponse.Refund;
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",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "metadata": {
      "reason": "late delivery"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

// Or, if the creditor does not have a sufficient balance to create the refund:
HTTP/1.1 422 Validation Failed
{
  "error": {
    "message": "It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP",
    "errors": [
        {
            "reason": "available_refund_amount_insufficient",
            "message": "It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP",
            "metadata": {
              "available_refund_amount": 90
            }
        }
    ],
    "documentation_url": "https://developer.gocardless.com/api-reference#available_refund_amount_insufficient",
    "type": "validation_failed",
    "request_id": "...",
    "code": 422
  }
}

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.
mandate
Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
payment
Unique identifier, beginning with “PM”.
refund_type
Whether a refund was issued against a mandate or a payment. One of:
  • payment: default returns refunds created against payments only

  • mandate: returns refunds created against mandates only

$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Refund refund : client.refunds().all().withPayment("PM123").execute()) {
  System.out.println(refund.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const refunds = await client.refunds.list();

// List all refunds associated with a given mandate.
const refunds = await client.refunds.list({ mandate: "MD0123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var refundRequest = new GoCardless.Services.RefundListRequest()
{
    Mandate = "MD0123"
};

var refundListResponse = gocardless.Refunds.All(refundRequest);
foreach (GoCardless.Resources.Refund refund in refundListResponse)
{
    Console.WriteLine(refund.Id);
}
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",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Refund refund = client.refunds().get("RF123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const refund = await client.refunds.find("RF123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var refundResponse = await gocardless.Refunds.GetAsync("RF0123");
GoCardless.Resources.Refund refund = refundResponse.Refund;
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",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.refunds().update("RF123")
  .withMetadata("internal_code", "refund_1A")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const refund = await client.refunds.update(
  "RF123",
  {
    metadata: {
      key: "value"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var refundRequest = new GoCardless.Services.RefundUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"reason", "Late delivery"}
    }
};

var refundResponse = await gocardless.Refunds.UpdateAsync("RF0123", refundRequest);
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",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "metadata": {
      "key": "value"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

Scenario Simulators

Scenario Simulators allow you to manually trigger and test certain paths that your integration will encounter in the real world. These endpoints are only active in the sandbox environment.

Properties

id
The unique identifier of the simulator, used to initiate simulations. One of:
  • creditor_verification_status_action_required: Sets a creditor’s verification status to action required, meaning that the creditor must provide further information to GoCardless in order to verify their account to receive payouts.

  • creditor_verification_status_in_review: Sets a creditor’s verification status to in review, meaning that the creditor has provided all of the information requested by GoCardless to verify their account, and is now awaiting review.

  • creditor_verification_status_successful: Sets a creditor’s verification status to successful, meaning that the creditor is fully verified and can receive payouts.

  • payment_paid_out: Transitions a payment through to paid_out, having been collected successfully and paid out to you. It must start in the pending_submission state, and its mandate must be in the activated state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may be pending_submission, since their mandates are submitted with their first payment).

  • payment_failed: Transitions a payment through to failed. It must start in the pending_submission state, and its mandate must be in the activated state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may be pending_submission, since their mandates are submitted with their first payment).

  • payment_charged_back: Behaves the same as the payout_paid_out simulator, except that the payment is transitioned to charged_back after it is paid out, having been charged back by the customer.

  • payment_chargeback_settled: Behaves the same as the payment_charged_back simulator, except that the charged back payment is additionally included as a debit item in a payout, thereby settling the charged back payment.

  • payment_late_failure: Transitions a payment through to late_failure, having been apparently collected successfully beforehand. It must start in the pending_submission state, and its mandate must be in the activated state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may be pending_submission, since their mandates are submitted with their first payment). Not compatible with Autogiro mandates.

  • payment_late_failure_settled: Behaves the same as the payment_late_failure simulator, except that the late failure is additionally included as a debit item in a payout, thereby settling the late failure.

  • payment_submitted: Transitions a payment to submitted, without proceeding any further. It must start in the pending_submission state.

  • mandate_activated: Transitions a mandate through to activated, having been submitted to the banks and set up successfully. It must start in the pending_submission state. Not compatible with ACH, BECS, BECS_NZ and SEPA mandates, which are submitted and activated with their first payment.

  • mandate_customer_approval_granted: Transitions a mandate through to pending_submission, as if the customer approved the mandate creation. It must start in the pending_customer_approval state. Compatible only with Bacs and SEPA mandates, which support customer signatures on the mandate. All payments associated with the mandate will be transitioned to pending_submission. All subscriptions associated with the mandate will become active.

  • mandate_customer_approval_skipped: Transitions a mandate through to pending_submission, as if the customer skipped the mandate approval during the mandate creation process. It must start in the pending_customer_approval state. Compatible only with Bacs and SEPA mandates, which support customer signatures on the mandate. All payments associated with the mandate will be transitioned to pending_submission. All subscriptions associated with the mandate will become active.

  • mandate_failed: Transitions a mandate through to failed, having been submitted to the banks but found to be invalid (for example due to invalid bank details). It must start in the pending_submission or submitted states. Not compatible with ACH, BECS, BECS_NZ and SEPA mandates, which are submitted with their first payment.

  • mandate_expired: Transitions a mandate through to expired, having been submitted to the banks, set up successfully and then expired because no collection attempts were made against it for longer than the scheme’s dormancy period (13 months for Bacs, 3 years for SEPA, 15 months for ACH, Betalingsservice, and BECS). It must start in the pending_submission state. Not compatible with Autogiro, BECS NZ, and PAD mandates, which do not expire.

  • mandate_transferred: Transitions a mandate through to transferred, having been submitted to the banks, set up successfully and then moved to a new bank account due to the customer using the UK’s Current Account Switching Service (CASS). It must start in the pending_submission state. Only compatible with Bacs mandates.

  • mandate_transferred_with_resubmission: Transitions a mandate through transferred and resubmits it to the banks, can be caused be the UK’s Current Account Switching Service (CASS) or when a customer contacts GoCardless to change their bank details. It must start in the pending_submission state. Only compatible with Bacs, SEPA and Autogiro mandates.

  • refund_paid: Transitions a refund to paid. It must start in either the pending_submission or submitted state.

  • refund_settled: Transitions a refund to paid, if it’s not already, then generates a payout that includes the refund, thereby settling the funds. It must start in one of pending_submission, submitted or paid states.

  • refund_bounced: Transitions a refund to bounced. It must start in either the pending_submission, submitted, or paid state.

  • payout_bounced: Transitions a payout to bounced. It must start in the paid state.

  • payout_create: Creates a payout containing payments in confirmed, failed & charged_back states; refunds in submitted & bounced; and all related fees. Can only be used with a positive total payout balance and when some eligible items exist.

  • billing_request_fulfilled: Authorises the billing request, fulfils it, and moves the associated payment to failed. The billing request must be in the pending state, with all actions completed except for bank_authorisation. Only billing requests with a payment_request are supported.

  • billing_request_fulfilled_and_payment_failed: Authorises the billing request, fulfils it, and moves the associated payment to failed. The billing request must be in the pending state, with all actions completed except for bank_authorisation. Only billing requests with a payment_request are supported.

  • billing_request_fulfilled_and_payment_paid_out: Authorises the billing request, fulfils it, and moves the associated payment to paid_out. The billing request must be in the pending state, with all actions completed except for bank_authorisation. Only billing requests with a payment_request are supported.

Simulate a scenario

Runs the specific scenario simulator against the specific resource

Relative endpoint: POST /scenario_simulators/payment_failed/actions/run

Parameters

currency
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Only required when simulating payout_create
links[resource]
ID of the resource to run the simulation against. Must be same type of resource as the simulator that is being run. eg. Payment ID for payment_failed, Mandate ID for mandate_activated etc
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->scenarioSimulators()->run("payment_failed", [
  "params" => ["links" => ["resource" => "PM123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.scenario_simulators.run("payment_failed", params={
  "links": { "resource": "PM123" }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.scenario_simulators.run(
  "payment_failed",
   params: { links: { resource: "PM123" } }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.scenario_simulators().run("payment_failed")
  .withLinks("resource", "PM123").
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const response = await client.scenarioSimulators.run(
  "payment_failed",
  {
    links: {
      resource: "PM123"
    }
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var simulateRequest = new GoCardless.Services.ScenarioSimulatorRunRequest()
{
    Links = new Dictionary<string, string>()
    {
        {"resource", "PM123"}
    }
};

var response = await gocardless.ScenarioSimulators.RunAsync(
    "payment_failed", simulateRequest
);
POST https://api.gocardless.com/scenario_simulators/payment_failed/actions/run HTTP/1.1

{
  "data": {
    "links": {
      "resource": "PM123"
    }
  }
}

HTTP/1.1 200 OK

{}

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.
  • If day_of_month and start_date are not provided start_date will be the mandate’s next_possible_charge_date and the subscription will then recur based on the interval & interval_unit
  • If month or day_of_month are present the following validations apply:
interval_unit month day_of_month
yearly optional (required if day_of_month provided) optional (invalid if month not provided)
monthly invalid optional
weekly invalid invalid

Examples:

interval_unit interval month day_of_month valid?
yearly 1 january -1 valid
monthly 6     valid
monthly 6   12 valid
weekly 2     valid
yearly 1 march   invalid - missing day_of_month
yearly 1   2 invalid - missing month
monthly 6 august 12 invalid - month must be blank
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 the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
app_fee
The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
count
The total number of payments that should be taken by this subscription.
created_at
Fixed timestamp, recording when this resource was created.
currency
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” 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.
earliest_charge_date_after_resume
The earliest date that will be used as a charge_date on payments created for this subscription if it is resumed. Only present for paused subscriptions. This value will change over time.
end_date
Date on or after which no further payments should be created.
If this field is blank and count is not specified, the subscription will continue forever.
Deprecated: This field will be removed in a future API version. Use count to specify a number of payments instead.
interval
Number of interval_units between customer charge dates. Must be greater than or equal to 1. 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. Only applies when the interval_unit is yearly.
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.

retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false.
start_date
The date on which the first payment should be charged. Must be on or after the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month 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

  • paused: the subscription has been paused and will not create payments

upcoming_payments
Up to 10 upcoming payments with their amounts and charge dates.

Each instance will contain these properties:

  • amount: The amount of this payment, in minor unit (e.g. pence in GBP, cents in EUR).

  • 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 the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
currency
required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
interval_unit
required The unit of time between customer charge dates. One of weekly, monthly or yearly.
app_fee
The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
count
The total number of payments that should be taken by this subscription.
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 this field is blank and count is not specified, the subscription will continue forever.
Deprecated: This field will be removed in a future API version. Use count to specify a number of payments instead.
interval
Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.
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. Only applies when the interval_unit is yearly.
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.

retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false.
start_date
The date on which the first payment should be charged. Must be on or after the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month 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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

import com.gocardless.services.SubscriptionService.SubscriptionCreateRequest.IntervalUnit;

Subscription subscription = client.subscriptions().create()
  .withAmount(2500)
  .withCurrency("GBP")
  .withName("Monthly Magazine")
  .withIntervalUnit(IntervalUnit.MONTHLY)
  .withDayOfMonth(1)
  .withMetadata("order_no", "ABCD1234")
  .withLinksMandate("MD123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscription = await client.subscriptions.create({
  amount: "2500",
  currency: "GBP",
  name: "Monthly Magazine",
  interval_unit: "monthly",
  day_of_month:  "1",
  metadata": {
    order_no: "ABCD1234"
  },
  links: {
    mandate: "MA123"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var subscriptionRequest = new GoCardless.Services.SubscriptionCreateRequest()
{
    Amount = 1000,
    Currency = "GBP",
    Name = "Monthly subscription",
    Interval = 1,
    IntervalUnit = GoCardless.Services.SubscriptionCreateRequest.SubscriptionIntervalUnit.Monthly,
    Links = new GoCardless.Services.SubscriptionCreateRequest.SubscriptionLinks()
    {
        Mandate = "MD0123"
    }
};

var subscriptionResponse = await gocardless.Subscriptions.CreateAsync(subscriptionRequest);
GoCardless.Resources.Subscription subscription = subscriptionResponse.Subscription;
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,
    "app_fee": null,
    "earliest_charge_date_after_resume": 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"
    },
    "retry_if_possible": false
  }
}

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”. Note that this prefix may not apply to mandates created before 2016.
status
Upto 5 of:
  • pending_customer_approval

  • customer_approval_denied

  • active

  • finished

  • cancelled

  • paused

Omit entirely to include subscriptions in all states.

$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Subscription subscription : client.subscriptions().all().withCustomer("CU123").execute()) {
  System.out.println(subscription.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscriptions = await client.subscriptions.list();

// List all subscriptions associated with a given customer.
const subscriptions = await client.subscriptions.list({ customer: "CU123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var subscriptionRequest = new GoCardless.Services.SubscriptionListRequest()
{
    Customer = "CU000123"
};

var subscriptionListResponse = gocardless.Subscriptions.All(subscriptionRequest);
foreach (GoCardless.Resources.Subscription subscription in subscriptionListResponse)
{
    Console.WriteLine(subscription.Id);
}
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,
    "earliest_charge_date_after_resume": 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"
    },
    "retry_if_possible": false
  }]
}

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Subscription subscription = client.subscriptions().get("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscription = await client.subscriptions.find("SB123");

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,
    "earliest_charge_date_after_resume": 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"
    },
    "retry_if_possible": false
  }
}

Update a subscription

Updates a subscription object.

This fails with:

  • validation_failed if invalid data is provided when attempting to update a subscription.

  • subscription_not_active if the subscription is no longer active.

  • subscription_already_ended if the subscription has taken all payments.

  • mandate_payments_require_approval if the amount is being changed and the mandate requires approval.

  • number_of_subscription_amendments_exceeded error if the subscription amount has already been changed 10 times.

  • forbidden if the amount is being changed, and the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app

  • resource_created_by_another_app if the app fee is being changed, and the subscription was created by an app other than the app you are authenticated as

Relative endpoint: PUT /subscriptions/SB123

Parameters

amount
Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
app_fee
The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.

retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false.
$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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.subscriptions().update("SB123")
  .withName("New name")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscription = await client.subscriptions.update(
  "SB123",
  {
    amount: "42",
    name: "New Name"
  }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var subscriptionRequest = new GoCardless.Services.SubscriptionUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {“custom_reference", "ref_09011991"}
    }
};

var subscriptionResponse = await gocardless.Subscriptions.UpdateAsync(“SB0123", subscriptionRequest);
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,
    "earliest_charge_date_after_resume": 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"
    },
    "retry_if_possible": false
  }
}

Pause a subscription

Pause a subscription object. No payments will be created until it is resumed.

This can only be used when a subscription collecting a fixed number of payments (created using count), when they continue forever (created without count or end_date) or the subscription is paused for a number of cycles.

When pause_cycles is omitted the subscription is paused until the resume endpoint is called. If the subscription is collecting a fixed number of payments, end_date will be set to null. When paused indefinitely, upcoming_payments will be empty.

When pause_cycles is provided the subscription will be paused for the number of cycles requested. If the subscription is collecting a fixed number of payments, end_date will be set to a new value. When paused for a number of cycles, upcoming_payments will still contain the upcoming charge dates.

This fails with:

  • forbidden if the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app

  • validation_failed if invalid data is provided when attempting to pause a subscription.

  • subscription_paused_cannot_update_cycles if the subscription is already paused for a number of cycles and the request provides a value for pause_cycle.

  • subscription_cannot_be_paused if the subscription cannot be paused.

  • subscription_already_ended if the subscription has taken all payments.

  • pause_cycles_must_be_greater_than_or_equal_to if the provided value for pause_cycles cannot be satisfied.

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

Warning: Please note that any payments that have already been created from this subscription will still be collected unless you manually cancel them.

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.
pause_cycles
The number of cycles to pause a subscription for. A cycle is one duration of interval and interval_unit.
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->subscriptions()->pause("SB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.subscriptions.pause("SB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.subscriptions().pause("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscriptionResponse = await client.subscriptions.pause("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var subscriptionResponse = await gocardless.Subscriptions.PauseAsync(“SB0123");
POST https://api.gocardless.com/subscriptions/SU123/actions/pause HTTP/1.1

{
  "data": {
    "metadata": {}
  }
}

HTTP/1.1 200 OK
{
  "subscriptions": {
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "paused",
    "name": "Subscription name",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "earliest_charge_date_after_resume": "2014-10-23",
    "upcoming_payments": [
    ],
    "metadata": {
      "order_no": "ABCD4321"
    },
    "links": {
      "mandate": "MA123"
    },
    "retry_if_possible": false
  }
}

Resume a subscription

Resume a subscription object. Payments will start to be created again based on the subscriptions recurrence rules. The charge_date on the next payment will be the same as the subscriptions earliest_charge_date_after_resume

This fails with:

  • forbidden if the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app

  • validation_failed if invalid data is provided when attempting to resume a subscription.

  • subscription_not_paused if the subscription is not paused.

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

Warning: There is a mandatory minimum 14 business day wait between resuming an AUD subscription and its next charge date. There is a mandatory minimum 10 calendar day wait between resuming an NZD subscription and its next charge date.

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()->resume("SB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.subscriptions.resume("SB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.subscriptions().resume("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscriptionResponse = await client.subscriptions.resume("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var subscriptionResponse = await gocardless.Subscriptions.ResumeAsync(“SB0123");
POST https://api.gocardless.com/subscriptions/SU123/actions/resume HTTP/1.1

{
  "data": {
    "metadata": {}
  }
}

HTTP/1.1 200 OK
{
  "subscriptions": {
    "id": "SB123",
    "created_at": "2014-10-20T17:01:06.000Z",
    "amount": 2500,
    "currency": "GBP",
    "status": "active",
    "name": "Subscription name",
    "start_date": "2014-11-03",
    "end_date": null,
    "interval": 1,
    "interval_unit": "monthly",
    "day_of_month": 1,
    "month": null,
    "payment_reference": null,
    "earliest_charge_date_after_resume": 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"
    },
    "retry_if_possible": false
  }
}

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

Warning: Please note that this will not cancel any payments that have already been created from this subscription — these payments will still be collected unless you also manually cancel them.

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
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.subscriptions().cancel("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const subscriptions = await client.subscriptions.cancel("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var subscriptionResponse = await gocardless.Subscriptions.CancelAsync("SB0123");
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,
    "earliest_charge_date_after_resume": null,
    "upcoming_payments": [],
    "metadata": {
      "order_no": "ABCD1234"
    },
    "links": {
      "mandate": "MA123"
    },
    "retry_if_possible": false
  }
}

Tax Rates

Tax rates from tax authority.

We also maintain a static list of the tax rates for each jurisdiction.

Properties

id
The unique identifier created by the jurisdiction, tax type and version
end_date
Date at which GoCardless stopped applying the tax rate for the jurisdiction.
jurisdiction
The jurisdiction this tax rate applies to
percentage
The percentage of tax that is applied onto of GoCardless fees
start_date
Date at which GoCardless started applying the tax rate in the jurisdiction.
type
The type of tax applied by this rate

List tax rates

Returns a cursor-paginated list of all tax rates.

Relative endpoint: GET /tax_rates

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
jurisdiction
The jurisdiction this tax rate applies to
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->taxRates()->list([
  "params" => ["jurisdiction" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.tax_rates.list(params={"jurisdiction": "GB" }).records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.tax_rates.list(params: { jurisdiction: "GB" })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.taxRates().all().withJurisdiction("GB").execute()
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const taxRates = await client.taxRates.list();

// List the Tax rate for a jurisdiction.
const taxRates = await client.taxRates.list({ jurisdiction: 'GB'});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var request = new GoCardless.Services.TaxRateListRequest()
{
    Jurisdiction = "GB",
};

var response = gocardless.TaxRates.All(request);
foreach (GoCardless.Resources.TaxRate rate in response)
{
    Console.WriteLine(rate.Rate);
}
GET https://api.gocardless.com/tax_rates?jurisdiction=GB HTTP/1.1

HTTP/1.1 200 OK
{
    "tax_rates": [
        {
            "id": "GB_VAT_1",
            "jurisdiction": "GB",
            "type": "VAT",
            "percentage": "20.0",
            "start_date": "2020-02-24",
            "end_date": null,
        }
    ],
    "meta": {
        "cursors": {
            "after": null,
            "before": null
        },
        "limit": 50
    }
}

Get a single tax rate

Retrieves the details of a tax rate.

Relative endpoint: GET /tax_rates/GB_VAT_1

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

$client->taxRates()->get("GB_VAT_1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.tax_rates.get("GB_VAT_1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

TaxRate taxRate = client.taxRates().get("GB_VAT_1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const taxRate = await client.taxRate.find("GB_VAT_1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var taxRateResponse = await gocardless.TaxRate.GetAsync("GB_VAT_1");
GoCardless.Resources.TaxRate taxRate = taxRateResponse.TaxRate;
GET https://api.gocardless.com/tax_rates/GB_VAT_1 HTTP/1.1

HTTP/1.1 200 OK
{
  "tax_rates": {
    "id": "GB_VAT_1",
    "jurisdiction": "GB",
    "type": "VAT",
    "percentage": "20.0",
    "start_date": "2020-02-24",
    "end_date": null
  }
}

Webhooks

Basic description of a webhook

Properties

id
Unique identifier, beginning with “WB”.
created_at
Fixed timestamp, recording when this resource was created.
is_test
Boolean value showing whether this was a demo webhook for testing
request_body
The body of the request sent to the webhook URL
request_headers
The request headers sent with the webhook
response_body
The body of the response from the webhook URL
response_body_truncated
Boolean value indicating the webhook response body was truncated
response_code
The response code from the webhook request
response_headers
The headers sent with the response from the webhook URL
response_headers_content_truncated
Boolean indicating the content of response headers was truncated
response_headers_count_truncated
Boolean indicating the number of response headers was truncated
successful
Boolean indicating whether the request was successful or failed
url
URL the webhook was POST-ed to

List webhooks

Returns a cursor-paginated list of your webhooks.

Relative endpoint: GET /webhooks

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.
is_test
Show only test/non test webhooks
limit
Number of records to return.
successful
Show only successful/failed webhooks
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

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

$client->webhooks()->list([
  "params" => ["successful" => True]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.webhooks.list().records

client.webhooks.list(params={"successful": True}).records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.webhooks.list

@client.webhooks.list(params: { successful: true })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

for (Webhook webhook : client.webhooks().all().withSuccessful(true).execute()) {
  System.out.println(webhook.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const webhooks = await client.webhooks.list();

// List all webhooks past a certain date.
const webhooks = await client.webhooks.list({
  created_at: {
    gt: "2020-01-01T17:01:06.000Z"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var webhookRequest = new GoCardless.Services.WebhookListRequest()
{
    Successful = true
};

var webhookListResponse = gocardless.Webhooks.All(webhookRequest);
foreach (GoCardless.Resources.Webhook webhook in webhookListResponse)
{
    Console.WriteLine(webhook.Id);
}
GET https://api.gocardless.com/webhooks/WB123?successful=true HTTP/1.1

HTTP/1.1 200 OK
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 5
  },
  "webhooks": [{
      "created_at": "2018-03-12T15:13:37.416Z",
      "id": "WB123",
      "is_test": true,
      "request_body": "{\"events\":[{\"id\":\"EV123\",\"created_at\":\"2018-03-12T15:13:37.158Z\",\"resource_type\":\"payments\",\"action\":\"created\",\"links\":{\"payment\":\"PM123\"},\"details\":{\"origin\":\"api\",\"cause\":\"payment_created\",\"description\":\"Payment created via the API.\"},\"metadata\":{}}]}",
      "request_headers": {
        "Content-Type": "application/json",
        "Origin": "https://api.gocardless.com",
        "User-Agent": "gocardless-webhook-service/1.1",
        "Webhook-Signature": "e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365"
      },
      "response_body": "ok",
      "response_body_truncated": false,
      "response_code": 200,
      "response_headers": {
        "content-type": "text/html; charset=utf-8",
        "date": "Mon, 12 Mar 2018 15:13:37 GMT",
      },
      "response_headers_content_truncated": false,
      "response_headers_count_truncated": false,
      "successful": true,
      "url": "https://example.com/webhook_handler"
  }]
}

Get a single webhook

Retrieves the details of an existing webhook.

Relative endpoint: GET /webhooks/WB123

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

$client->webhooks()->get("WB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.webhooks.get("WB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Webhook webhook = client.webhooks().get("WB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const webhook = await client.webhooks.find("WB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var webhookResponse = await gocardless.webhooks.GetAsync("WB123");
GoCardless.Resources.Webhook webhook = webhooksResponse.Webhook;
GET https://api.gocardless.com/webhooks/WB123 HTTP/1.1

HTTP/1.1 200 OK
{
  "webhooks": {
      "created_at": "2018-03-12T15:13:37.416Z",
      "id": "WB123",
      "is_test": true,
      "request_body": "{\"events\":[{\"id\":\"EV123\",\"created_at\":\"2018-03-12T15:13:37.158Z\",\"resource_type\":\"payments\",\"action\":\"created\",\"links\":{\"payment\":\"PM123\"},\"details\":{\"origin\":\"api\",\"cause\":\"payment_created\",\"description\":\"Payment created via the API.\"},\"metadata\":{}}]}",
      "request_headers": {
        "Content-Type": "application/json",
        "Origin": "https://api.gocardless.com",
        "User-Agent": "gocardless-webhook-service/1.1",
        "Webhook-Signature": "e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365"
      },
      "response_body": "ok",
      "response_body_truncated": false,
      "response_code": 200,
      "response_headers": {
        "content-type": "text/html; charset=utf-8",
        "date": "Mon, 12 Mar 2018 15:13:37 GMT",
      },
      "response_headers_content_truncated": false,
      "response_headers_count_truncated": false,
      "successful": true,
      "url": "https://example.com/webhook_handler"
  }
}

Retry a webhook

Requests for a previous webhook to be sent again

Relative endpoint: POST /webhooks/WB123/actions/retry

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

$client->webhooks()->retry("WB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.webhooks.retry("WB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.webhooks().retry("WB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const webhookResponse = await client.webhooks.retry("WB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var webhookResponse = await gocardless.webhooks.RetryAsync("WB123");
POST https://api.gocardless.com/webhooks/WB123/actions/retry HTTP/1.1

HTTP/1.1 200 OK
{
  "webhooks": {
      "created_at": "2018-03-12T15:13:37.416Z",
      "id": "WB123",
      "is_test": true,
      "request_body": "{\"events\":[{\"id\":\"EV123\",\"created_at\":\"2018-03-12T15:13:37.158Z\",\"resource_type\":\"payments\",\"action\":\"created\",\"links\":{\"payment\":\"PM123\"},\"details\":{\"origin\":\"api\",\"cause\":\"payment_created\",\"description\":\"Payment created via the API.\"},\"metadata\":{}}]}",
      "request_headers": {
        "Content-Type": "application/json",
        "Origin": "https://api.gocardless.com",
        "User-Agent": "gocardless-webhook-service/1.1",
        "Webhook-Signature": "e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365"
      },
      "response_body": "ok",
      "response_body_truncated": false,
      "response_code": 200,
      "response_headers": {
        "content-type": "text/html; charset=utf-8",
        "date": "Mon, 12 Mar 2018 15:13:37 GMT",
      },
      "response_headers_content_truncated": false,
      "response_headers_count_truncated": false,
      "successful": true,
      "url": "https://example.com/webhook_handler"
  }
}

Billing Requests

The product described here is in early-access. This means the endpoints are excluded from our normal SLA, will change as we develop them, and are only available on request.

Please get in touch (api@gocardless.com) if you’re interested in trying it out.

This section contains API endpoints that are used to power Billing Requests.

Billing Requests help create resources that require input or action from a customer. An example of required input might be additional customer billing details, while an action would be asking a customer to authorise a payment using their mobile banking app.

Billing Requests go through a simple lifecycle, with the state exposed as the status field:

  • pending, actions need completing before we can fulfil
  • ready_to_fulfil, all required actions are complete and the integrator may fulfil this request
  • fulfilled, the request is fulfilled and an resource has been created
  • cancelled, request was cancelled before it can be completed (no resource will ever be created)

Integrators have a choice between building their own user experience flows to complete the required actions, or creating a Billing Request Flow against the Billing Request. Billing Request Flows are a GoCardless managed flow that knows how to process outstanding actions on the Request, helping the customer provide their required details and fulfil the request.

We advise most integrators make use of Billing Request Flows to benefit from the efforts GoCardless put into optimising conversion, adapting to a changing regulatory environment, and to reduce integration effort.

Even for integrators who want a whitelabel experience, we might advise completing some actions through a customer integration and leveraging the Billing Request Flow to complete the more complex actions.

Bank Authorisations

Bank Authorisations can be used to authorise Billing Requests. Authorisations are created against a specific bank, usually the bank that provides the payer’s account.

Creation of Bank Authorisations is only permitted from GoCardless hosted UIs (see Billing Request Flows) to ensure we meet regulatory requirements for checkout flows. The exceptions are integrators with the custom payment pages upgrade, who have been audited to check their flows meet requirements.

Properties

id
Unique identifier, beginning with “BAU”.
authorisation_type
Type of authorisation, can be either ‘mandate’ or ‘payment’.
created_at
Timestamp when the flow was created
expires_at
Timestamp when the url will expire. Each authorisation url currently lasts for 15 minutes, but this can vary by bank.
last_visited_at
Fixed timestamp, recording when the authorisation URL has been visited.
redirect_uri
URL that the payer can be redirected to after authorising the payment.
short_url
Short URL that redirects via GoCardless to the original URL, more suitable for encoding in a QR code
url
URL for an oauth flow that will allow the user to authorise the payment
links[billing_request]
ID of the billing request against which this authorisation was created.
links[institution]
ID of the institution against which this authorisation was created.
links[payment_request]
ID of the payment request against which this authorisation was created.

Get a Bank Authorisation.

Fetches a bank authorisation

Relative endpoint: GET /bank_authorisations/BAU123

Warning: The product described here is considered early-access and only available on request. Please get in touch (api@gocardless.com) if you’re interested in trying it out.







GET https://api.gocardless.com/bank_authorisations/BRQ123 HTTP/1.1

HTTP/1.1 200
{
  "bank_authorisations": {
    "id": "BAU123",
    "url": "https://verify.monzo.com/open-banking/authorize?client_id=oauth2client_00000000ab123arIZM7Pr1",
    "short_url": "https://pay.gocardless.com/obauth/BAU123",
    "created_at": "2021-03-25T17:26:28.305Z",
    "authorisation_type": "payment",
    "last_visited_at": null,
    "expires_at": "2021-03-25T17:41:28.000Z",
    "redirect_uri": "https://pay.gocardless.com/open_banking/static/thankyou",
    "links": {
      "billing_request": "BRQ123",
      "institution": "monzo"
    }
  }
}

Create a Bank Authorisation

Create a Bank Authorisation.

Relative endpoint: POST /bank_authorisations

Restricted: this endpoint is restricted to integrators who have custom payment pages enabled, as the authorisation must be used within a checkout flow that meets regulatory requirements for each payment scheme.

Parameters

authorisation_type
Type of authorisation, can be either ‘mandate’ or ‘payment’.
redirect_uri
URL that the payer can be redirected to after authorising the payment.
links[billing_request]
ID of the billing request against which this authorisation was created.
links[institution]
required ID of the institution against which this authorisation was created.
links[payment_request]
ID of the payment request against which this authorisation was created.






POST https://api.gocardless.com/bank_authorisations HTTP/1.1
{
  "bank_authorisations": {
    "authorisation_type": "payment",
    "links": {
      "institution": "monzo",
      "billing_request": "BRQ123"
    }
  }
}

HTTP/1.1 201 Created
Location: /bank_authorisations/BAU123
{
  "bank_authorisations": {
    "id": "BAU123",
    "url": "https://verify.monzo.com/open-banking/authorize?client_id=oauth2client_00000000ab123arIZM7Pr1",
    "short_url": "https://pay-staging.gocardless.com/obauth/BAU123",
    "created_at": "2021-03-25T17:26:28.305Z",
    "authorisation_type": "payment",
    "last_visited_at": null,
    "expires_at": "2021-03-25T17:41:28.000Z",
    "redirect_uri": "https://pay.gocardless.com/open_banking/static/thankyou",
    "links": {
      "billing_request": "BRQ123",
      "institution": "monzo"
    }
  }
}

Billing Requests

Billing Requests

Properties

id
Unique identifier, beginning with “BRQ”.
actions
List of actions that can be performed before this billing request can be fulfilled.

Each instance will contain these properties:

  • completes_actions: Which other action types this action can complete.

  • required: Informs you whether the action is required to fulfil the billing request or not.

  • requires_actions: Requires completing these actions before this action can be completed.

  • type: Unique identifier for the action.

auto_fulfil
Should the billing request be fulfilled as soon as it’s ready (true by default)
created_at
Fixed timestamp, recording when this resource was created.
mandate_request[currency]
ISO 4217 currency code. Currently only “GBP” is supported as we only have one scheme that is per_payment_authorised.
links[mandate]
(Optional) ID of the mandate that was created from this mandate request. this mandate request.
mandate_request[scheme]
A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
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.
payment_request[amount]
Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_request[currency]
ISO 4217 currency code. Currently only “GBP” is supported as we only have one scheme that is per_payment_authorised.
payment_request[description]
A human-readable description of the payment. This will be displayed to the payer when authorising the billing request.
links[payment]
(Optional) ID of the payment that was created from this payment request.
payment_request[scheme]
A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
customer[company_name]
Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
customer[created_at]
Fixed timestamp, recording when this resource was created.
customer[email]
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer[family_name]
Customer’s surname. Required unless a company_name is provided.
customer[given_name]
Customer’s first name. Required unless a company_name is provided.
customer[id]
Unique identifier, beginning with “CU”.
customer[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”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.
customer[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.
customer[phone_number]
ITU E.123 formatted phone number, including country code.
customer_bank_account[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. This field is required unless the request includes a customer bank account token.
customer_bank_account[account_number_ending]
The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
customer_bank_account[account_type]
Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
customer_bank_account[bank_name]
Name of bank, taken from the bank details.
customer_bank_account[country_code]
ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.
customer_bank_account[created_at]
Fixed timestamp, recording when this resource was created.
customer_bank_account[currency]
ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
customer_bank_account[enabled]
Boolean value showing whether the bank account is enabled or disabled.
customer_bank_account[id]
Unique identifier, beginning with “BA”.
links[customer]
ID of the customer that owns this bank account.
customer_bank_account[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.
customer_billing_detail[address_line1]
The first line of the customer’s address.
customer_billing_detail[address_line2]
The second line of the customer’s address.
customer_billing_detail[address_line3]
The third line of the customer’s address.
customer_billing_detail[city]
The city of the customer’s address.
customer_billing_detail[country_code]
ISO 3166-1 alpha-2 code.
customer_billing_detail[created_at]
Fixed timestamp, recording when this resource was created.
customer_billing_detail[danish_identity_number]
For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer_billing_detail[id]
Unique identifier, beginning with “CU”.
customer_billing_detail[postal_code]
The customer’s postal code.
customer_billing_detail[region]
The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).
schemes
The schemes associated with this customer billing detail
customer_billing_detail[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.
status
One of:
  • pending: the billing_request is pending and can be used

  • ready_to_fulfil: the billing_request is ready to fulfil

  • fulfilled: the billing_request has been fulfilled and a payment created

  • cancelled: the billing_request has been cancelled and cannot be used

links[bank_authorisation]
(Optional) ID of the bank authorisation that was used to verify this request.
links[customer]
ID of the customer that will be used for this request
links[customer_bank_account]
(Optional) ID of the customer_bank_account that will be used for this request
links[customer_billing_detail]
ID of the customer billing detail that will be used for this request

List Billing Requests

Returns a cursor-paginated list of your billing_requests.

Relative endpoint: GET /billing_requests

Warning: The product described here is considered early-access and only available on request. Please get in touch (api@gocardless.com) if you’re interested in trying it out.

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
created_at
Fixed timestamp, recording when this resource was created.
customer
ID of a customer. If specified, this endpoint will return all requests for the given customer.
limit
Number of records to return.
status
One of:
  • pending: the billing_request is pending and can be used

  • ready_to_fulfil: the billing_request is ready to fulfil

  • fulfilled: the billing_request has been fulfilled and a payment created

  • cancelled: the billing_request has been cancelled and cannot be used







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

HTTP/1.1 200 OK
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "billing_requests": [
    {
       "id": "BRQ123",
       "created_at": "2021-03-22T16:23:48.486Z",
       "status": "pending",
       "auto_fulfil": true,
       "mandate_request": null,
       "payment_request": {
           "description": "£5 Top Up",
           "currency": "GBP",
           "amount": 500,
           "scheme": "faster_payments",
           "links": {}
       },
       "metadata": null,
       "links": {
           "customer": "CU123",
           "customer_billing_detail": "CBD123",
           "customer_bank_account": "BA123"
       }
     }
   ]
}

Create a billing_request

Relative endpoint: POST /billing_requests

Warning: The product described here is considered early-access and only available on request. Please get in touch (api@gocardless.com) if you’re interested in trying it out.

Parameters

auto_fulfil
Should the billing request be fulfilled as soon as it’s ready (true by default)
mandate_request[currency]
ISO 4217 currency code. Currently only “GBP” is supported as we only have one scheme that is per_payment_authorised.
mandate_request[scheme]
A Direct Debit scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “pad” and “sepa_core” are supported.
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.
payment_request[amount]
Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_request[currency]
ISO 4217 currency code. Currently only “GBP” is supported as we only have one scheme that is per_payment_authorised.
payment_request[description]
A human-readable description of the payment. This will be displayed to the payer when authorising the billing request.
links[customer]
ID of the customer against which this request should be made.
links[customer_bank_account]
(Optional) ID of the customer_bank_account against which this request should be made.






POST https://api.gocardless.com/billing_requests HTTP/1.1
  {
    "billing_requests": {
      "payment_request": {
        "description": "First Payment",
        "amount": "500",
        "currency": "GBP"
      },
      "mandate_request": {
        "scheme": "bacs"
      },
      "auto_fulfil": true
    }
  }

HTTP/1.1 201 Created
Location: /billing_requests/BRQ123
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "auto_fulfil": false,
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": null,
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "creditor_name": "Mr Creditor",
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
                "type": "collect_bank_account_details",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account_details"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": null,
                "family_name": null,
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": null,
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}

Get a single billing request

Fetches a billing request

Relative endpoint: GET /billing_requests/BRQ123

Warning: The product described here is considered early-access and only available on request. Please get in touch (api@gocardless.com) if you’re interested in trying it out.







GET https://api.gocardless.com/billing_requests/BRQ123 HTTP/1.1

HTTP/1.1 200
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "auto_fulfil": false,
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": null,
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "creditor_name": "Mr Creditor",
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
                "type": "collect_bank_account_details",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account_details"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": null,
                "family_name": null,
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": null,
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}

Collect customer details for the billing request

If the billing request has a pending collect_customer_details action, this endpoint can be used to collect the details in order to complete it.

The endpoint takes the same payload as Customers, but checks that the customer fields are populated correctly for the billing request scheme.

Whatever is provided to this endpoint is used to update the referenced customer, and will take effect immediately after the request is successful.

Relative endpoint: POST /billing_requests/BRQ123/actions/collect_customer_details

Warning: The product described here is considered early-access and only available on request. Please get in touch (api@gocardless.com) if you’re interested in trying it out.

Parameters

customer[company_name]
Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).
customer[email]
Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer[family_name]
Customer’s surname. Required unless a company_name is provided.
customer[given_name]
Customer’s first name. Required unless a company_name is provided.
customer[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”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.
customer[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.
customer[phone_number]
ITU E.123 formatted phone number, including country code.
customer_billing_detail[address_line1]
The first line of the customer’s address.
customer_billing_detail[address_line2]
The second line of the customer