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
PayTo**
Australia
Faster Payments*** UK & Channel Islands (inc. Jersey & Guernsey) + Isle of Man + Gibraltar (The customer needs to select UK as the country)

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.

** PayTo although not technically a Direct Debit scheme can be used as an alternative to BECS.

*** Faster Payments is not a Direct Debit scheme, but an alternative to BACS that can be used for instant and variable recurring payments.

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 Billing Requests API to create customers, bank accounts and mandates.

The following endpoints are therefore restricted:

  • Billing Requests: Create_customer_details, Collect_bank_account
  • 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 PayTo:

  • There is no advance notice period and payments can be taken almost instantaneously.

For Faster Payments:

  • There is no advance notice period and payments can be taken almost instantaneously.

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

18th July 2023
Updated our public certificate policy.
21 June 2023
Added the resource_metadata property to Events.
16 March 2023
Added show_success_redirect_button parameter to Billing Request Flow creation.
1st March 2023
Changed the Payout Items API to only return Payout Items created in the previous 6 months.
22nd February 2023
Made the Billing Requests API and the Blocks API respond in English if the Accept-Language header isn’t set, like other API endpoints. These two APIs used to infer the language from the IP address of the client, which wasn’t the intended behaviour.
8th February 2023
Added billing_request[purpose_code] parameter to Billing Request creation.
13th January 2023
Added the verified_at timestamp field to the mandates API.
23rd December 2022
Updated our public certificate policy.
20th December 2022
Added authorisation_source parameter to the Mandate creation API and mandate_request[authourisation_source] parameter to the BillingRequest creation API. This field is required for offline mandates.
13th December 2022
Added creditor_type parameter to the Creditors API. This field represents the type of business of the creditor. It will now be required when creating a creditor and it will be returned when fetching creditors.
9th December 2022
Added language parameter to Billing Request Flow creation.
11th November 2022
Added mandate_request[description] and mandate_request[constraints] parameter to Billing Request creation. Constraints restricts the kind of payment that can be taken against a mandate.
1st November 2022
Payout Items are no longer ordered by type. The order of Payout Items for a given Payout is still consistent between requests.
5th August 2022
Added payer_requested_dual_signature parameter to Billing Request action confirm payer details.
21st July 2022
Added prefilled_customer and prefilled_bank_account parameters to Billing Request creation.
14th July 2022
Added mandate_request[reference] parameter to Billing Request creation.
10th May 2022
Autogiro scheme is now available in Billing Request flow. Documentaion can be found here
4th May 2022
Event creation is now an asynchronous process. This means it can take some time between an action occurring and its corresponding event being made available in API responses.
26th January 2022
Added support for filtering events by instalment schedule in the events List API.
31st December 2021
Added support for Sepa Credit Transfer and Sepa Instant Credit Transfer, the Instant Bank Pay schemes inside Billing Request.
18th November 2021
Added block endpoints. These endpoints allow to create a block based on payers bank_account, email and email_domain, view the blocked items.
5th August 2021
Fixed reason codes sent for BECS so that they are consistent with the documentation. Eg. direct_debit_not_enabled events will be sent with Reason code 2 instead of RETURNS-2, as per documentation.
30th March 2021
Added Scenario Simulators endpoint. These allow manual testing of certain flows in the Sandbox environment
26th March 2021
Added a new resource called Billing Requests. 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.
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.

Timeouts

Some timeouts affect HTTP requests and connections to the API.

  • Request Timeout - we have a request timeout of 29 seconds. A single request cannot last more than this amount of time.
  • Keepalive Timeout - we have a keepalive timeout (also known as an idle timeout) of 10 minutes on persistent HTTP connections. If a connection has been open with no request for that time period, the connection will be closed.

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.

Dates and Times

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)
Content-Type: application/json
{
  "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.
410
Gone. The authenticated user can access the requested resource, but it has been removed. The response body will explain which resource has been removed.
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 retry the request. If the problem persists, please report this to the GoCardless support team and quote the request_id.
504
Gateway Timeout. The request timed out and should be retried. If the problem persists, 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
This is an error that has occured within GoCardless while processing your requests. In some cases, depending on the specific issue highlighted in errors, the request should be retried. If the problem persists, it should be reported to our support team with the request_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.

GoCardless errors

internal_server_error
An internal error occurred while processing your request. This should be reported to our support team with the request_id, so we can resolve the issue.

request_timed_out
The request did not complete within a reasonable time. In this case, the request should be retried (possibly with different parameters). If the problem persists, it should be reported to our support team with the request_id, so we can resolve the issue.

query_timed_out
The query for this request did not complete within a reasonable time, potentially due to being too complex. In this case, the request should be retried (possibly with different parameters). If the problem persists, it should be reported to our support team with the request_id, so we can resolve the issue.

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.

payout_items_data_archived
Payout items for payouts created more than 6 months ago have been archived. Please contact support if you require access to this data.

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.

billing_request_must_be_ready_to_fulfil

The billing request must have no outstanding required actions. To check the actions please view the actions array in the billing request get response.

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
Content-Type: application/json
{
  "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)
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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)
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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)
Content-Type: application/json
{
  "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"
        }
      }
    ]
  }
}

Billing Requests

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.

Properties

id
Unique identifier, beginning with “BAU”.
authorisation_type
Type of authorisation, can be either ‘mandate’ or ‘payment’.
authorised_at
Fixed timestamp, recording when the user has been authorised.
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.
qr_code_url
URL to a QR code PNG image of the bank authorisation url. This QR code can be used as an alternative to providing the url to the payer to allow them to authorise with their mobile devices.
redirect_uri
URL that the payer can be redirected to after authorising the payment.

On completion of bank authorisation, the query parameter of either outcome=success or outcome=failure will be appended to the redirect_uri to indicate the result of the bank authorisation. If the bank authorisation is expired, the query parameter outcome=timeout will be appended to the redirect_uri, in which case you should prompt the user to try the bank authorisation step again.

The redirect_uri you provide should handle the outcome query parameter for displaying the result of the bank authorisation as outlined above.

The BillingRequestFlow ID will also be appended to the redirect_uri as query parameter id=BRF123.

Defaults to https://pay.gocardless.com/billing/static/thankyou.

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.

Create a Bank Authorisation

Create a Bank Authorisation.

Relative endpoint: POST /bank_authorisations

Restricted: this endpoint is restricted as the authorisation must be used within a checkout flow that meets regulatory requirements for each payment scheme. Integrators should use a Billing Request Flow to do this.

If you would like to enable bank authorisations, you will need to go through a separate compliance process. For more details please get in touch.

Parameters

redirect_uri
URL that the payer can be redirected to after authorising the payment.

On completion of bank authorisation, the query parameter of either outcome=success or outcome=failure will be appended to the redirect_uri to indicate the result of the bank authorisation. If the bank authorisation is expired, the query parameter outcome=timeout will be appended to the redirect_uri, in which case you should prompt the user to try the bank authorisation step again.

The redirect_uri you provide should handle the outcome query parameter for displaying the result of the bank authorisation as outlined above.

The BillingRequestFlow ID will also be appended to the redirect_uri as query parameter id=BRF123.

Defaults to https://pay.gocardless.com/billing/static/thankyou.

links[billing_request]
ID of the billing request against which this authorisation was created.
POST https://api.gocardless.com/bank_authorisations HTTP/1.1
Content-Type: application/json
{
  "bank_authorisations": {
    "redirect_uri": "https://my-company.com/landing",
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

HTTP/1.1 201 Created
Location: /bank_authorisations/BAU123
Content-Type: application/json
{
  "bank_authorisations": {
    "id": "BAU123",
    "url": "https://pay-staging.gocardless.com/obauth/BAU123",
    "qr_code_url": "https://pay-staging.gocardless.com/obauth/BAU123/qr_code",
    "created_at": "2021-03-25T17:26:28.305Z",
    "authorisation_type": "payment",
    "last_visited_at": null,
    "authorised_at": null,
    "expires_at": "2021-03-25T17:41:28.000Z",
    "redirect_uri": "https://my-company.com/landing",
    "links": {
      "billing_request": "BRQ123",
      "institution": "monzo"
    }
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->bankAuthorisations()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "links" => [
      "billing_request" => "BRQ123"
    ]
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.bank_authorisations.create(params={
  "redirect_uri": "https://my-company.com/landing",
  "links": {
    "billing_request": "BRQ123"
  }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.bank_authorisations.create(
  params: {
    redirect_uri: "https://my-company.com/landing",
    links: {
        billing_request: "BRQ123"
    }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

BankAuthorisation bankAuthorisation = client.bankAuthorisations().create()
  .withRedirectUri("https://my-company.com/landing")
  .withLinksBillingRequest("BRQ123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const bankAuthorisation = await client.bankAuthorisations.create({
  redirect_uri: "https://my-company.com/landing",
  links: {
    billing_request: "BRQ123"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var authorisationLinks = new gocardless.BankAuthorisationCreateRequest.BankAuthorisationLinks
{
  BillingRequest = "BRQ123"
};

var resp = await gocardless.BankAuthorisations.CreateAsync(
  new GoCardless.Services.BankAuthorisationCreateRequest()
  {
    RedirectUri = "https://my-company.com/landing",
    links = authorisationLinks,
  }
);

GoCardless.Resources.BankAuthorisation bankAuthorisation = resp.BankAuthorisation;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  bankAuthorisationCreateParams := gocardless.BankAuthorisationCreateParams{
    RedirectUri: "https://my-company.com/landing",
    Links: gocardless.BankAuthorisationCreateParamsLinks{
      BillingRequest: "BR123",
    },
  }
  
  bankAuthorisation, err :=  client.BankAuthorisations.Create(context, bankAuthorisationCreateParams)

}

Get a Bank Authorisation

Get a single bank authorisation.

Relative endpoint: GET /bank_authorisations/BAU123

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

HTTP/1.1 200
Content-Type: application/json
{
  "bank_authorisations": {
    "id": "BAU123",
    "url": "https://pay-staging.gocardless.com/obauth/BAU123",
    "qr_code_url": "https://pay-staging.gocardless.com/obauth/BAU123/qr_code",
    "created_at": "2021-03-25T17:26:28.305Z",
    "authorisation_type": "payment",
    "last_visited_at": null,
    "authorised_at": null,
    "expires_at": "2021-03-25T17:41:28.000Z",
    "redirect_uri": "https://my-company.com/landing",
    "links": {
      "billing_request": "BRQ123",
      "institution": "monzo"
    }
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

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

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

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

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

const resp = await client.bankAuthorisations.find("BAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BankAuthorisations.GetAsync("BAU123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  bankAuthorisation, err := client.BankAuthorisations.Get(context, "BAU123")

}

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.

See Billing Requests: Overview for how-to’s, explanations and tutorials.

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:

  • available_currencies: List of currencies the current mandate supports

  • bank_authorisation: Describes the behaviour of bank authorisations, for the bank_authorisation action

  • collect_customer_details: Additional parameters to help complete the collect_customer_details action

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

  • institution_guess_status: Describes whether we inferred the institution from the provided bank account details. One of:
    • not_needed: we won’t attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
    • pending: we are waiting on the bank details in order to infer the institution
    • failed: we weren’t able to infer the institution
    • success: we inferred the institution and added it to the resources of a Billing Request
  • 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.

  • status: Status of the action

  • type: Unique identifier for the action.
created_at
Fixed timestamp, recording when this resource was created.
fallback_enabled
(Optional) If true, this billing request can fallback from instant payment to direct debit. Should not be set if GoCardless payment intelligence feature is used.

See Billing Requests: Retain customers with Fallbacks for more information.

mandate_request[authorisation_source]
This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

constraints[end_date]
The latest date at which payments can be taken, must occur after start_date if present

This is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.

constraints[max_amount_per_payment]
The maximum amount that can be charged for a single payment. Required for VRP.
periodic_limits
List of periodic limits and constraints which apply to them

Each instance will contain these properties:

  • alignment: The alignment of the period.

    calendar - this will finish on the end of the current period. For example this will expire on the Monday for the current week or the January for the next year.

    creation_date - this will finish on the next instance of the current period. For example Monthly it will expire on the same day of the next month, or yearly the same day of the next year.

  • max_payments: (Optional) The maximum number of payments that can be collected in this periodic limit.

  • max_total_amount: The maximum total amount that can be charged for all payments in this periodic limit. Required for VRP.

  • period: The repeating period for this mandate

constraints[start_date]
The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

mandate_request[currency]
ISO 4217 currency code.
mandate_request[description]
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
links[mandate]
(Optional) ID of the mandate that was created from this mandate request. this mandate request.
mandate_request[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_request[scheme]
A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_request[verify]
Verification preference for the mandate. One of:
  • minimum: only verify if absolutely required, such as when part of scheme rules

  • recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified

  • when_available: if verification mechanisms are available, use them

  • always: as when_available, but fail to create the Billing Request if a mechanism isn’t available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

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[app_fee]
The amount to be deducted from the payment as an app fee, to be paid to the partner integration which created the billing request, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
payment_request[currency]
ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in Germany only.
payment_request[description]
A human-readable description of the payment and/or mandate. 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[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[scheme]
(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in Germany (EUR). In Germany, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.
purpose_code
Specifies the high-level purpose of a mandate and/or payment using a set of pre-defined categories. Required for the PayTo scheme, optional for all others. Currently mortgage, utility, loan, dependant_support, gambling, retail, salary, personal, government, pension, tax and other 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[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).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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

  • fulfilling: the billing request is currently undergoing fulfilment

  • 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[creditor]
ID of the associated creditor.
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
links[mandate_request]
(Optional) ID of the associated mandate request
links[mandate_request_mandate]
(Optional) ID of the mandate that was created from this mandate request. this mandate request.
links[organisation]
ID of the associated organisation.
links[payment_request]
(Optional) ID of the associated payment request
links[payment_request_payment]
(Optional) ID of the payment that was created from this payment request.

Create a Billing Request

Relative endpoint: POST /billing_requests

Note: Instant Bank Pay is only available for transactions in GBP with your customers in the UK and for EUR with your customers in Germany. We will be adding other countries soon.

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

fallback_enabled
(Optional) If true, this billing request can fallback from instant payment to direct debit. Should not be set if GoCardless payment intelligence feature is used.

See Billing Requests: Retain customers with Fallbacks for more information.

mandate_request[authorisation_source]
This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

mandate_request[constraints]
Constraints that will apply to the mandate_request. (Optional) Specifically for PayTo and VRP.

Properties:

  • end_date: The latest date at which payments can be taken, must occur after start_date if present

    This is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.

  • max_amount_per_payment: The maximum amount that can be charged for a single payment. Required for VRP.
  • periodic_limits: List of periodic limits and constraints which apply to them
  • start_date: The date from which payments can be taken.

    This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

mandate_request[currency]
ISO 4217 currency code.
mandate_request[description]
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_request[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_request[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_request[scheme]
A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_request[verify]
Verification preference for the mandate. One of:
  • minimum: only verify if absolutely required, such as when part of scheme rules

  • recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified

  • when_available: if verification mechanisms are available, use them

  • always: as when_available, but fail to create the Billing Request if a mechanism isn’t available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

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[app_fee]
The amount to be deducted from the payment as an app fee, to be paid to the partner integration which created the billing request, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
payment_request[currency]
ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in Germany only.
payment_request[description]
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_request[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[scheme]
(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in Germany (EUR). In Germany, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.
purpose_code
Specifies the high-level purpose of a mandate and/or payment using a set of pre-defined categories. Required for the PayTo scheme, optional for all others. Currently mortgage, utility, loan, dependant_support, gambling, retail, salary, personal, government, pension, tax and other are supported.
links[creditor]
ID of the associated creditor. Only required if your account manages multiple creditors.
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
Content-Type: application/json
{
  "billing_requests": {
    "payment_request": {
      "description": "First Payment",
      "amount": "500",
      "currency": "GBP"
    },
    "mandate_request": {
      "scheme": "bacs"
    }
  }
}

HTTP/1.1 201 Created
Location: /billing_requests/BRQ123
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "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": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "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
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->create([
  "params" => [
    "payment_request" => [
      "description" => "First Payment",
      "amount" => "500",
      "currency" => "GBP",
    ],
    "mandate_request" => [
      "scheme" => "bacs"
    ]
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_requests.create(params={
  "payment_request": {
    "description": "First Payment",
    "amount": "500",
    "currency": "GBP",
  },
  "mandate_request": {
    "scheme": "bacs"
  }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_requests.create(
  params: {
    payment_request: {
      description: "First Payment",
      amount: "500",
      currency: "GBP",
    },
    mandate_request: {
      scheme: "bacs"
    }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

BillingRequest billingRequest = client.billingRequests().create()
  .withPaymentRequestDescription("First Payment")
  .withPaymentRequestAmount(500)
  .withPaymentRequestCurrency(Currency.GBP)
  .withMandateRequestScheme("bacs")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const billingRequest = await client.billingRequests.create({
  payment_request: {
    description: "First Payment",
    amount: "500",
    currency: "GBP",
  },
  mandate_request: {
    scheme: "bacs"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var paymentRequest = new gocardless.BillingRequestCreateRequest.BillingRequestPaymentRequest
{
  Description = "First payment",
  Amount = 500,
  Currency = "GBP",
};

var mandateRequest = new gocardless.BillingRequestCreateRequest.BillingRequestMandateRequest
{
  Scheme = "bacs",
};

var resp = await gocardless.BillingRequests.CreateAsync(
  new GoCardless.Services.BillingRequestCreateRequest()
  {
    PaymentRequest = paymentRequest,
    MandateRequest = mandateRequest,
  }
);

GoCardless.Resources.BillingRequest billingRequest = resp.BillingRequest;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestCreateParams := gocardless.BillingRequestCreateParams{
    PaymentRequest: &gocardless.BillingRequestCreateParamsPaymentRequest{
      Amount:      1000,
      Currency:    "GBP",
      Description: "First Payment",
    },
    MandateRequest: &gocardless.BillingRequestCreateParamsMandateRequest{
      Scheme: "bacs",
    },
  }
  
  billingRequest, err := client.BillingRequests.Create(context, billingRequestCreateParams)

}

Collect customer details

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

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

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 and a customer was linked during billing request creation, the linked customer language will be used. Otherwise, the language is 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’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[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[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).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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).
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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_customer_details HTTP/1.1
Content-Type: application/json
{
  "data": {
    "customer": {
      "email": "alice@example.com",
      "given_name": "Alice",
      "family_name": "Smith"
    },
    "customer_billing_detail": {
      "address_line1": "1 Somewhere Lane"
    }
  }
}

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "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",
            "creditor": "CR123",
            "mandate_request": "MRQ123"
        },
        "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": [],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": "alice@example.com",
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->collectCustomerDetails("BR123", [
  "params" => [
    "customer" => [
      "email" => "alice@example.com",
      "given_name" => "Alice",
      "family_name" => "Smith"
    ],
    "customer_billing_detail" => [
      "address_line1" => "1 Somewhere Lane"
    ]
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_requests.collect_customer_details("BR123", params={
  customer: {
    email: "alice@example.com",
    given_name: "Alice",
    family_name: "Smith",
  },
  customer_billing_detail: {
    address_line1: "1 Somewhere Lane"
  }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_requests.collect_customer_details("BR123", {
  params: {
    customer: {
      email: "alice@example.com",
      given_name: "Alice",
      family_name: "Smith",
    },
    customer_billing_detail: {
      address_line1: "1 Somewhere Lane"
    }
  }
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.billingRequests().collectCustomerDetails("BR123")
  .withCustomerEmail("alice@example.com")
  .withCustomerGivenName("Alice")
  .withCustomerFamilyName("Smith")
  .withCustomerBillingDetailAddressLine1("1 Somewhere Lane")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const resp = await client.billingRequests.collectCustomerDetails("BR123", {
  customer: {
    email: "alice@example.com",
    given_name: "Alice",
    family_name: "Smith",
  },
  customer_billing_detail: {
    address_line1: "1 Somewhere Lane"
  }
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var customer = new gocardless.BillingRequests.CollectCustomerDetailsRequest.BillingRequestCustomer
{
  Email = "alice@example.com",
  GivenName = "Alice",
  FamilyName = "Smith",
};

var customerBillingDetail = = new gocardless.BillingRequests.CollectCustomerDetailsRequest.BillingRequestCustomerBillingDetail
{
  AddressLine1 = "1 Somewhere Lane",
};

var resp = await gocardless.BillingRequests.CollectCustomerDetails("BR123",
  new BillingRequestCollectCustomerDetailsRequest
  {
    Customer = customer,
    CustomerBillingDetail = customerBillingDetail,
  });
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestCollectCustomerDetailsParams := gocardless.BillingRequestCollectCustomerDetailsParams{
    Customer: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomer{
      GivenName:  "Alice",
      FamilyName: "Smith",
      Email:      "alice@example.com",
    },
    CustomerBillingDetail: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomerBillingDetail{
      AddressLine1: "1 Somewhere Lane",
    },
  }
  
  billingRequest, err := client.BillingRequests.CollectCustomerDetails(context, "BR123", billingRequestCollectCustomerDetailsParams)

}

Collect bank account details

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

The endpoint takes the same payload as Customer Bank Accounts, but check the bank account is valid for the billing request scheme before creating and attaching it.

ACH scheme For compliance reasons, an extra validation step is done using a third-party provider to make sure the customer’s bank account can accept Direct Debit. If a bank account is discovered to be closed or invalid, the customer is requested to adjust the account number/routing number and succeed in this check to continue with the flow.

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

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

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_number_suffix
Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_bank_account HTTP/1.1
Content-Type: application/json
{
  "data": {
    "account_number": "55779911",
    "branch_code": "200000",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB"
  }
}

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "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_bank_account": "BA123",
          "creditor": "CR123",
          "mandate_request": "MRQ123"
        },
        "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": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_bank_account": {
                "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"
                }
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->collectBankAccount("BR123", [
  "params" => [
    "account_number" => "55779911",
    "branch_code" => "200000",
    "account_holder_name" => "Frank Osborne",
    "country_code" => "GB"
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_requests.collect_bank_account("BR123", params={
  account_number: "55779911",
  branch_code: "200000",
  account_holder_name: "Frank Osborne",
  country_code: "GB",
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_requests.collect_bank_account("BR123", {
  params: {
    account_number: "55779911",
    branch_code: "200000",
    account_holder_name: "Frank Osborne",
    country_code: "GB",
  }
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.billingRequests().collectBankAccount("BR123")
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withAccountHolderName("Frank Osborne")
  .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 resp = await client.billingRequests.collectBankAccount("BR123", {
  account_number: "55779911",
  branch_code: "200000",
  account_holder_name: "Frank Osborne",
  country_code: "GB",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequests.CollectBankAccountAsync("BR123",
  new BillingRequestCollectBankAccountRequest
  {
    AccountNumber = "55779911",
    BranchCode = "200000",
    AccountHolderName = "Frank Osborne",
    CountryCode = "GB",
  });
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestCollectBankAccountParams := gocardless.BillingRequestCollectBankAccountParams{
    BranchCode:        "200000",
    CountryCode:       "GB",
    AccountNumber:     "55779911",
    AccountHolderName: "Frank Osborne",
  }
  
  billingRequest, err := client.BillingRequests.CollectBankAccount(context, "BR123", billingRequestCollectBankAccountParams)

}

Confirm the payer details

This is needed when you have a mandate request. As a scheme compliance rule we are required to allow the payer to crosscheck the details entered by them and confirm it.

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

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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/confirm_payer_details HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "ready_to_fulfil",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": null
        "metadata": null,
        "links": {
            "customer": "CU123",
            "customer_bank_account": "BA123",
            "creditor": "CR123",
            "mandate_request": "MRQ123"
        },
        "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": "completed"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "confirm_payer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_customer_details",
                    "collect_bank_account"
                ],
                "status": "completed"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_bank_account": {
                "id": "BA123",
                "created_at": "2022-11-01T16:30:37.969Z",
                "account_number_ending": "11",
                "account_holder_name": "HOME LOAN ACCOUNT",
                "account_type": null,
                "bank_name": "BARCLAYS BANK PLC",
                "currency": "GBP",
                "country_code": "GB",
                "metadata": {},
                "enabled": true,
                "links": {
                    "customer": "CU123"
                },
                "branch_code_ending": "00"
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->confirmPayerDetails("BR123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.billing_requests.confirm_payer_details("BR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.billingRequests().confirmPayerDetails("BR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const resp = await client.billingRequests.confirmPayerDetails("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequests.ConfirmPayerDetailsAsync("BR123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  BillingRequestConfirmPayerDetailsParams := gocardless.BillingRequestConfirmPayerDetailsParams{}
  billingRequest, err := client.BillingRequests.ConfirmPayerDetails(context, "BR123", BillingRequestConfirmPayerDetailsParams)

}

Fulfil a Billing Request

If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment.

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

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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/fulfil HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "fulfilled",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {
              "mandate": "MD123"
            }
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {
              "payment": "PM123"
            }
        },
        "metadata": null,
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "creditor_name": "Mr Creditor",
        "actions": [],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->fulfil("BR123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.billing_requests.fulfil("BR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.billingRequests().fulfil("BR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const resp = await client.billingRequests.fulfil("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequests.FulfilAsync("BR123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestFulfilParams := gocardless.BillingRequestFulfilParams{}
  billingRequest, err := client.BillingRequests.Fulfil(context, "BR123", billingRequestFulfilParams)

}

Cancel a Billing Request

Immediately cancels a billing request, causing all billing request flows to expire.

Relative endpoint: POST /billing_requests/BRQ123/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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/cancel HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "cancelled",
        "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": [],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

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

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

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

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

const resp = await client.billingRequests.cancel("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequests.CancelAsync("BR123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestCancelParams := gocardless.BillingRequestCancelParams{}
  billingRequest, err := client.BillingRequests.Fulfil(context, "BR123", billingRequestCancelParams)

}

List Billing Requests

Returns a cursor-paginated list of your billing requests.

Relative endpoint: GET /billing_requests

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

  • fulfilling: the billing request is currently undergoing fulfilment

  • 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
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "billing_requests": [
    {
       "id": "BRQ123",
       "created_at": "2021-03-22T16:23:48.486Z",
       "status": "pending",
       "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"
       }
     }
   ]
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->list();
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

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

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

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

var billingRequestListResponse = gocardless.BillingRequests.All();
foreach (GoCardless.Resources.BillingRequest billingRequest in billingRequestListResponse)
{
    Console.WriteLine(billingRequest.Id);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestListParams := gocardless.BillingRequestListParams{}
  billingRequestListResult, err :=  client.BillingRequests.List(context, billingRequestListParams)
  for _, billingRequest := range billingRequestListResult.BillingRequests {
      fmt.Println(billingRequest.Id)
  }

}

Get a single Billing Request

Fetches a billing request

Relative endpoint: GET /billing_requests/BRQ123

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

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "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": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "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
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

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

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

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

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

const resp = await client.billingRequests.find("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequests.GetAsync("BR123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequest, err := client.BillingRequests.Get(context, "BR123")

}

Notify the customer

Notifies the customer linked to the billing request, asking them to authorise it. Currently, the customer can only be notified by email.

This endpoint is currently supported only for Instant Bank Pay Billing Requests.

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

Parameters

notification_type
required Currently, can only be email.
redirect_uri
URL that the payer can be redirected to after authorising the payment.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/notify HTTP/1.1
Content-Type: application/json
{
  "data": {
    "notification_type": "email",
    "redirect_uri": "https://my-company.com"
  }
}

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "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": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->notify("BR123", [
  "params" => [
    "notification_type" => "email",
    "redirect_uri" => "https://my-company.com"
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_requests.notify("BR123", params={
  notification_type: "email",
  redirect_uri: "https://my-company.com",
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_requests.notify("BR123", {
  params: {
    notification_type: "email",
    redirect_uri: "https://my-company.com",
  }
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.billingRequests().notify("BR123")
  .withNotificationType("email")
  .withRedirectUri("https://my-company.com")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const resp = await client.billingRequests.notify("BR123", {
  notification_type: "email",
  redirect_uri: "https://my-company.com",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequests.NotifyAsync("BR123",
  new BillingRequestNotifyRequest
  {
    NotificationType = "email",
    RedirectUri = "https://my-company.com",
  });
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestNotifyParams := gocardless.BillingRequestNotifyParams{
    NotificationType: "email",
    RedirectUri:      "https://my-company.com",
  }
  
  billingRequest, err := client.BillingRequests.Fulfil(context, "BR123", billingRequestNotifyParams)

}

Trigger fallback

Triggers a fallback from the open-banking flow to direct debit. Note, the billing request must have fallback enabled.

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

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

Parameters

POST https://api.gocardless.com/billing_requests/BRQ123/actions/fallback HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "bacs",
            "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": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "completed"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "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
            }
      },
      "fallback_enabled": true,
      "fallback_occurred": true
  }
}







Change currency

This will allow for the updating of the currency and subsequently the scheme if needed for a Billing Request. This will only be available for mandate only flows which do not have the lock_currency flag set to true on the Billing Request Flow. It will also not support any request which has a payments request.

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

Parameters

currency
required 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.








Select institution for a Billing Request

Creates an Institution object and attaches it to the Billing Request

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

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

Parameters

country_code
required ISO 3166-1 alpha-2 code. The country code of the institution.
institution
required The unique identifier for this institution
POST https://api.gocardless.com/billing_requests/BRQ123/actions/select_institution HTTP/1.1
Content-Type: application/json
{
  "data": {
    "institution": "monzo",
    "country_code": "GB"
  }
}

HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "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": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "completed"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            },
            "institution": {
                "id": "monzo",
                "name": "Monzo",
                "icon_url": "https://images.yapily.com/image/332bb781-3cc2-4f3e-ae79-1aba09fac991?size",
                "roles": ["institutions_list", "heartbeat", "read_refund_account", "read_debtor_account"],
                "country_code": "GB"
            }
        }
    }
}







Billing Request Flows

Billing Request Flows can be created to enable a payer to authorise a payment created for a scheme with strong payer authorisation (such as open banking single payments).

Properties

id
Unique identifier, beginning with “BRF”.
authorisation_url
URL for a GC-controlled flow which will allow the payer to fulfil the billing request
auto_fulfil
(Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.
created_at
Timestamp when the flow was created
exit_uri
URL that the payer can be taken to if there isn’t a way to progress ahead in flow.
expires_at
Timestamp when the flow will expire. Each flow currently lasts for 7 days.
language
Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.
lock_bank_account
If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock bank account if these have already been completed as a part of the billing request.

lock_currency
If true, the payer will not be able to change their currency/scheme manually within the flow. Note that this only applies to the mandate only flows - currency/scheme can never be changed when there is a specified subscription or payment.
lock_customer_details
If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock customer details if these have already been completed as a part of the billing request.

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[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.
redirect_uri
URL that the payer can be redirected to after completing the request flow.
session_token
Session token populated when responding to the initialise action
show_redirect_buttons
If true, the payer will be able to see redirect action buttons on Thank You page. These action buttons will provide a way to connect back to the billing request flow app if opened within a mobile app. For successful flow, the button will take the payer back the billing request flow where they will see the success screen. For failure, button will take the payer to url being provided against exit_uri field.
show_success_redirect_button
If true, the payer will be able to see a redirect action button on the Success page. This action button will provide a way to redirect the payer to the given redirect_uri. This functionality is helpful when merchants do not want payers to be automatically redirected or on Android devices, where automatic redirections are not possible.
links[billing_request]
ID of the billing request against which this flow was created.

Create a Billing Request Flow

Creates a new billing request flow.

Relative endpoint: POST /billing_request_flows

Parameters

auto_fulfil
(Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.
exit_uri
URL that the payer can be taken to if there isn’t a way to progress ahead in flow.
language
Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.
lock_bank_account
If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock bank account if these have already been completed as a part of the billing request.

lock_currency
If true, the payer will not be able to change their currency/scheme manually within the flow. Note that this only applies to the mandate only flows - currency/scheme can never be changed when there is a specified subscription or payment.
lock_customer_details
If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock customer details if these have already been completed as a part of the billing request.

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[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.
redirect_uri
URL that the payer can be redirected to after completing the request flow.
show_redirect_buttons
If true, the payer will be able to see redirect action buttons on Thank You page. These action buttons will provide a way to connect back to the billing request flow app if opened within a mobile app. For successful flow, the button will take the payer back the billing request flow where they will see the success screen. For failure, button will take the payer to url being provided against exit_uri field.
show_success_redirect_button
If true, the payer will be able to see a redirect action button on the Success page. This action button will provide a way to redirect the payer to the given redirect_uri. This functionality is helpful when merchants do not want payers to be automatically redirected or on Android devices, where automatic redirections are not possible.
links[billing_request]
required ID of the billing request against which this flow was created.
POST https://api.gocardless.com/billing_request_flows HTTP/1.1
Content-Type: application/json
{
  "billing_request_flows": {
    "redirect_uri": "https://my-company.com/landing",
    "exit_uri": "https://my-company.com/exit",
    "prefilled_customer": {
      "given_name": "Frank",
      "family_name": "Osborne",
      "email": "frank.osborne@acmeplc.com"
    },
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

HTTP/1.1 201 Created
Location: /billing_request_flows/BRF123456
Content-Type: application/json
{
  "billing_request_flows": {
    "id": "BRF123456",
    "auto_fulfil": true,
    "redirect_uri": "https://my-company.com/landing",
    "exit_uri": "https://my-company.com/exit",
    "authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=BRF123456",
    "lock_customer_details": false,
    "lock_currency": false,
    "lock_bank_account": false,
    "session_token": null,
    "expires_at": "2021-07-30T16:25:16.982Z",
    "created_at": "2021-07-23T16:25:16.983Z",
    "links": {
      "billing_request": "BRQ123"
    },
    "show_redirect_buttons": false,
    "show_success_redirect_button": false
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequestFlows()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "exit_uri" => "https://my-company.com/exit",
    "prefilled_customer" => [
      "given_name" => "Frank",
      "family_name" => "Osborne",
      "email" => "frank.osborne@acmeplc.com"
    ],
    "links" => [
      "billing_request" => "BRQ123"
    ]
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_request_flows.create(params={
  "redirect_uri": "https://my-company.com/landing",
  "exit_uri": "https://my-company.com/exit",
  "prefilled_customer": {
      "given_name": "Frank",
      "family_name": "Osborne",
      "email": "frank.osborne@acmeplc.com"
  },
  "links": {
    "billing_request": "BRQ123"
  }
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_request_flows.create(
  params: {
    redirect_uri: "https://my-company.com/landing",
    exit_uri: "https://my-company.com/exit",
    prefilled_customer: {
      given_name: "Frank",
      family_name: "Osborne",
      email: "frank.osborne@acmeplc.com"
    },
    links: {
      billing_request: "BRQ123",
    }
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

BillingRequestFlow billingRequestFlow = client.billingRequestFlows().create()
  .withRedirectUri("https://my-company.com/landing")
  .withExitUri("https://my-company.com/exit")
  .withPrefilledCustomerGivenName("Frank")
  .withPrefilledCustomerFamilyName("Osborne")
  .withPrefilledCustomerEmail("frank.osborne@acmeplc.com")
  .withLinksBillingRequest("BRQ123")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const billingRequestFlow = await client.billingRequestFlows.create({
  redirect_uri: "https://my-company.com/landing",
  exit_uri: "https://my-company.com/exit",
  prefilled_customer: {
    given_name: "Frank",
    family_name: "Osborne",
    email: "frank.osborne@acmeplc.com"
  },
  links: {
    billing_request: "BRQ123",
  }
});
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 resp = await gocardless.BillingRequestFlows.CreateAsync(
  new GoCardless.Services.BillingRequestFlowCreateRequest()
  {
    RedirectUri = "https://my-company.com/landing",
    ExitUri = "https://my-company.com/exit",
    PrefilledCustomer = prefilledCustomer,
    Links = new gocardless.BillingRequestFlowCreateRequest.BillingRequestFlowLinks
    {
      BillingRequest = "BRQ123",
    },
  }
);

GoCardless.Resources.BillingRequestFlow billingRequestFlow = resp.BillingRequestFlow;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestFlowCreateParams := gocardless.BillingRequestFlowCreateParams{
    RedirectUri: "https://my-company.com/landing",
    ExitUri:     "https://my-company.com/exit",
    PrefilledCustomer: &gocardless.RedirectFlowCreateParamsPrefilledCustomer{
      AddressLine1: "338-346 Goswell Road",
      City:         "London",
      GivenName:    "Tim",
      FamilyName:   "Rogers",
      Email:        "tim@gocardless.com",
      PostalCode:   "EC1V 7LQ",
    },
    Links: gocardless.BillingRequestFlowCreateParamsLinks{
      BillingRequest: "BR123",
    },
  }
  
  billingRequestFlow, err := client.BillingRequestFlows.Create(context, billingRequestFlowCreateParams)

}

Initialise a Billing Request Flow

Returns the flow having generated a fresh session token which can be used to power integrations that manipulate the flow.

Relative endpoint: POST /billing_request_flows/BRF123/actions/initialise

Parameters

POST https://api.gocardless.com/billing_request_flows/BRF123/actions/initialise HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
  "billing_request_flows":{
      "id":"BRF123",
      "auto_fulfil":true,
      "redirect_uri":null,
      "exit_uri":null,
      "authorisation_url":"https://pay-sandbox.gocardless.com/billing/static/flow?id=BRF123",
      "lock_customer_details":false,
      "lock_bank_account":false,
      "lock_currency": false,
      "session_token":"sesh_sandbox_DHTMvJAUajbd9KTCoXNFcTv4RSoWdMbauhnalxiqwbdsb",
      "expires_at":"2021-09-01T08:45:38.016Z",
      "created_at":"2021-08-25T08:45:38.017Z",
      "links":{
        "billing_request":"BRQ123"
      },
      "show_redirect_buttons": false,
    "show_success_redirect_button": false
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequestFlows()->initialise("BRF123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

@client.billing_request_flows.initialise("BRF123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.billingRequestFlows().initialise("BRF123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const resp = await client.billingRequestFlows.initialise("BRF123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequestFlows.InitialiseAsync("BRF123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestFlowInitialiseParams := gocardless.BillingRequestFlowInitialiseParams{}
  billingRequestFlow, err := client.BillingRequestFlows.Initialise(context, "BRF123", billingRequestFlowInitialiseParams)

}

Billing Request Templates

Billing Request Templates

Properties

id
Unique identifier, beginning with “BRT”.
authorisation_url
Permanent URL that customers can visit to allow them to complete a flow based on this template, before being returned to the redirect_uri.
created_at
Fixed timestamp, recording when this resource was created.
mandate_request_currency
ISO 4217 currency code.
mandate_request_description
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_request_metadata
Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
mandate_request_scheme
A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_request_verify
Verification preference for the mandate. One of:
  • minimum: only verify if absolutely required, such as when part of scheme rules

  • recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified

  • when_available: if verification mechanisms are available, use them

  • always: as when_available, but fail to create the Billing Request if a mechanism isn’t available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

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 for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.
payment_request_amount
Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_request_currency
ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in Germany only.
payment_request_description
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_request_metadata
Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
payment_request_scheme
(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in Germany (EUR). In Germany, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.
redirect_uri
URL that the payer can be redirected to after completing the request flow.
updated_at
Dynamic timestamp recording when this resource was last updated.

List Billing Request Templates

Returns a cursor-paginated list of your Billing Request Templates.

Relative endpoint: GET /billing_request_templates

Parameters

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.
GET https://api.gocardless.com/billing_request_templates HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "billing_request_templates": [
    {
      "id": "BRT123",
      "name": "12 Month Gold Plan",
      "mandate_request_currency": "GBP",
      "mandate_request_scheme": null,
      "mandate_request_verify": null,
      "mandate_request_metadata": null,
      "payment_request_description": "One-time joining fee",
      "mandate_request_description": "Recurring fee",
      "payment_request_amount": "69.99",
      "payment_request_currency": "GBP",
      "payment_request_scheme": null,
      "payment_request_metadata": null,
      "redirect_uri": "https://my-company.com/landing",
      "authorisation_url": "https://pay.gocardless.com/BRT123",
      "metadata": {
        "checkout-flow": "primary"
      },
      "created_at": "2021-07-27T17:10:33.784Z",
      "updated_at": "2021-07-27T17:10:33.784Z"
    }
  ]
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequestTemplates()->list();
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

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

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

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

var billingRequestTemplateListResponse = gocardless.BillingRequestTemplates.All();
foreach (GoCardless.Resources.BillingRequestTemplate billingRequestTemplate in billingRequestTemplateListResponse)
{
    Console.WriteLine(billingRequestTemplate.Id);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestTemplateListParams := gocardless.BillingRequestTemplateListParams{}
  billingRequestTemplateListResult, err := client.BillingRequestTemplates.List(context, billingRequestTemplateListParams)
  for _, billingRequestTemplate := range billingRequestTemplateListResult.BillingRequestTemplates {
      fmt.Println(billingRequestTemplate.Id)
  }

}

Get a single Billing Request Template

Fetches a Billing Request Template

Relative endpoint: GET /billing_request_templates/BRT123

GET https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
  "billing_request_templates": {
    "id": "BRT123",
    "name": "12 Month Gold Plan",
    "mandate_request_currency": "GBP",
    "mandate_request_scheme": null,
    "mandate_request_verify": null,
    "mandate_request_metadata": null,
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "payment_request_amount": "69.99",
    "payment_request_currency": "GBP",
    "payment_request_scheme": null,
    "payment_request_metadata": null,
    "redirect_uri": "https://my-company.com/landing",
    "authorisation_url": "https://pay.gocardless.com/BRT123",
    "metadata": {
      "checkout-flow": "primary"
    },
    "created_at": "2021-07-27T17:10:33.784Z",
    "updated_at": "2021-07-27T17:10:33.784Z"
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

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

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

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

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

const resp = await client.billingRequestTemplates.find("BRT123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequestTemplates.GetAsync("BRT123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestTemplate, err := client.BillingRequestTemplates.Get(context, "BRT123")

}

Create a Billing Request Template

Relative endpoint: POST /billing_request_templates

Parameters

mandate_request_currency
ISO 4217 currency code.
mandate_request_description
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_request_metadata
Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
mandate_request_scheme
A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_request_verify
Verification preference for the mandate. One of:
  • minimum: only verify if absolutely required, such as when part of scheme rules

  • recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified

  • when_available: if verification mechanisms are available, use them

  • always: as when_available, but fail to create the Billing Request if a mechanism isn’t available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

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 for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.
payment_request_amount
Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_request_currency
ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in Germany only.
payment_request_description
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_request_metadata
Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
payment_request_scheme
(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in Germany (EUR). In Germany, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.
redirect_uri
URL that the payer can be redirected to after completing the request flow.
links[creditor]
ID of the associated creditor. Only required if your account manages multiple creditors.
POST https://api.gocardless.com/billing_request_templates HTTP/1.1
Content-Type: application/json
{
  "billing_request_templates": {
    "name": "12 Month Gold Plan",
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "payment_request_currency": "GBP",
    "payment_request_amount": "69.99",
    "mandate_request_currency": "GBP",
    "redirect_uri": "https://my-company.com/landing",
    "metadata": {
      "checkout-flow": "primary"
    }
  }
}

HTTP/1.1 201 Created
Location: /billing_request_templates/BRT123
Content-Type: application/json
{
  "billing_request_templates": {
    "id": "BRT123",
    "name": "12 Month Gold Plan",
    "mandate_request_currency": "GBP",
    "mandate_request_scheme": null,
    "mandate_request_verify": null,
    "mandate_request_metadata": null,
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "payment_request_amount": "69.99",
    "payment_request_currency": "GBP",
    "payment_request_scheme": null,
    "payment_request_metadata": null,
    "redirect_uri": "https://my-company.com/landing",
    "authorisation_url": "https://pay.gocardless.com/BRT123",
    "metadata": {
      "checkout-flow": "primary"
    },
    "created_at": "2021-07-27T17:10:33.784Z",
    "updated_at": "2021-07-27T17:10:33.784Z"
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequestTemplates()->create([
  "params" => [
    "name" => "12 Month Gold Plan",
    "payment_request_description" => "One-time joining fee",
    "mandate_request_description" => "Recurring fee",
    "payment_request_currency" => "GBP",
    "payment_request_amount" => "69.99",
    "mandate_request_currency" => "GBP",
    "redirect_uri" => "https://my-company.com/landing",
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_request_templates.create(params={
  "name": "12 Month Gold Plan",
  "payment_request_description": "One-time joining fee",
  "mandate_request_description": "Recurring fee",
  "payment_request_currency": "GBP",
  "payment_request_amount": "69.99",
  "mandate_request_currency": "GBP",
  "redirect_uri": "https://my-company.com/landing",
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_request_templates.create(
  params: {
    name: "12 Month Gold Plan",
    payment_request_description: "One-time joining fee",
    mandate_request_description: "Recurring fee",
    payment_request_currency: "GBP",
    payment_request_amount: "69.99",
    mandate_request_currency: "GBP",
    redirect_uri: "https://my-company.com/landing",
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().create()
  .withPaymentRequestDescription("One-time joining fee")
  .withPaymentRequestCurrency("GBP")
  .withPaymentRequestAmount("69.99")
  .withMandateRequestCurrency("GBP")
  .withRedirectUri("https://my-company.com/landing")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const billingRequestTemplate = await client.billingRequestTemplates.create({
  name: "12 Month Gold Plan",
  payment_request_description: "One-time joining fee",
  mandate_request_description: "Recurring fee",
  payment_request_currency: "GBP",
  payment_request_amount: "69.99",
  mandate_request_currency: "GBP",
  redirect_uri: "https://my-company.com/landing",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequestTemplates.CreateAsync(
  new GoCardless.Services.BillingRequestTemplateCreateRequest()
  {
    PaymentRequestDescription = "One-time joining fee",
    PaymentRequestCurrency = "GBP",
    PaymentRequestAmount = 6999,
    MandateRequestCurrency = "GBP",
    RedirectUri = "https://my-company.com/landing",
  }
);

GoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestTemplateCreateParams := gocardless.BillingRequestTemplateCreateParams{
    Name:                      "12 Month Gold Plan",
    PaymentRequestDescription: "One-time joining fee",
    PaymentRequestCurrency:    "GBP",
    PaymentRequestAmount:      6999,
    MandateRequestCurrency:    "GBP",
    RedirectUri:               "https://my-company.com/landing",
  }
  
  billingRequestTemplate, err := client.BillingRequestTemplates.Create(context, billingRequestTemplateCreateParams)

}

Update a Billing Request Template

Updates a Billing Request Template, which will affect all future Billing Requests created by this template.

Relative endpoint: PUT /billing_request_templates/BRQ123

Parameters

mandate_request_currency
ISO 4217 currency code.
mandate_request_description
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_request_metadata
Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
mandate_request_scheme
A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_request_verify
Verification preference for the mandate. One of:
  • minimum: only verify if absolutely required, such as when part of scheme rules

  • recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified

  • when_available: if verification mechanisms are available, use them

  • always: as when_available, but fail to create the Billing Request if a mechanism isn’t available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

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 for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.
payment_request_amount
Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_request_currency
ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in Germany only.
payment_request_description
A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_request_metadata
Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
payment_request_scheme
(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in Germany (EUR). In Germany, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.
redirect_uri
URL that the payer can be redirected to after completing the request flow.
PUT https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1
Content-Type: application/json
{
  "billing_request_templates": {
    "name": "12 Month Silver Plan",
    "payment_request_amount": "49.99"
  }
}

HTTP/1.1 200 OK
Location: /billing_request_templates/BRT123
Content-Type: application/json
{
  "billing_request_templates": {
    "id": "BRT123",
    "name": "12 Month Silver Plan",
    "mandate_request_currency": "GBP",
    "mandate_request_scheme": null,
    "mandate_request_verify": null,
    "mandate_request_metadata": null,
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "payment_request_amount": "49.99",
    "payment_request_currency": "GBP",
    "payment_request_scheme": null,
    "payment_request_metadata": null,
    "redirect_uri": "https://my-company.com/landing",
    "authorisation_url": "https://pay.gocardless.com/BRT123",
    "metadata": {
      "checkout-flow": "primary"
    },
    "created_at": "2021-07-27T17:10:33.784Z",
    "updated_at": "2021-07-30T11:28:11.123Z"
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequestTemplates()->update("BRT123", [
  "params" => [
    "name" => "12 Month Silver Plan",
    "payment_request_amount" => "49.99"
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_request_templates.update("BRT123", params={
  "name": "12 Month Silver Plan",
  "payment_request_amount": "49.99",
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_request_templates.update("BRT123", params: {
  name: "12 Month Silver Plan",
  payment_request_amount: "49.99",
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().update("BRT123")
  .withName("12 Month Silver Plan")
  .withPaymentRequestAmount("49.99")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const billingRequestTemplate = await client.billingRequestTemplates.update({
  name: "12 Month Silver Plan",
  payment_request_amount: "49.99",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequestTemplates.UpdateAsync(
  "BRT123",
  new GoCardless.Services.BillingRequestTemplateUpdateRequest()
  {
    Name = "12 Month Silver Plan",
    PaymentRequestAmount = 4999,
  }
);

GoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  billingRequestTemplateUpdateParams := gocardless.BillingRequestTemplateUpdateParams{
    Name:                 "12 Month Silver Plan",
    PaymentRequestAmount: 4999,
  }
  
  billingRequestTemplate, err := client.BillingRequestTemplates.Update(context, "BRT123", billingRequestTemplateUpdateParams)

}

Institutions

Institutions that are supported when creating Bank Authorisations for a particular country or purpose.

Not all institutions support both Payment Initiation (PIS) and Account Information (AIS) services.

Properties

id
The unique identifier for this institution
autocompletes_collect_bank_account
Flag to show if selecting this institution in the select_institution action can auto-complete the collect_bank_account action. The bank can return the payer’s bank account details to GoCardless.
country_code
ISO 3166-1 alpha-2 code. The country code of the institution.
icon_url
A URL pointing to the icon for this institution
logo_url
A URL pointing to the logo for this institution
name
A human readable name for this institution

List Institutions

Returns a list of supported institutions.

Relative endpoint: GET /institutions

Deprecated: This list institutions endpoint is no longer supported. We strongly recommend using the List Institutions For Billing Request instead.

Parameters

country_code
ISO 3166-1 alpha-2 code. The country code of the institution.
GET https://api.gocardless.com/institutions?country_code=GB HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "institutions": [
    {
      "id": "monzo",
      "name": "Monzo",
      "logo_url": "https://assets.gocardless.com/icon",
      "icon_url": "https://assets.gocardless.com/icon",
      "country_code": "GB"
    }
  ]
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

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

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

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

Institution institution = client.institutions().all().withCountryCode("GB").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

// List of all institutions.
const institutions = await client.institutions.list();

// List of institutions for a country code.
const institutions = await client.institutions.list({ countryCode: 'GB'});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

// List of institutions for a country code.
var request = new GoCardless.Services.InstitutionListRequest()
 {
     CountryCode = "GB",
 };

var institutionListResponse = gocardless.Institutions.All(request);

// List of all institutions.
var institutionListResponse = gocardless.Institutions.All();
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  institutionListParams := gocardless.InstitutionListParams{}
  institutionListResult, err := client.Institutions().List(context, institutionListParams)
  for _, institution := range institutionListResult.Institutions {
      fmt.Println(institution.Id)
  }

}

List institutions for Billing Request

Returns all institutions valid for a Billing Request.

This endpoint is currently supported only for FasterPayments.

Relative endpoint: GET /billing_requests/BRQ123/institutions

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

Parameters

country_code
required ISO 3166-1 alpha-2 code. The country code of the institution.
ids
ID(s) of the institution(s) to retrieve. More than one ID can be specified using a comma-separated string.
search
A search substring for retrieving institution(s), based on the institution’s name.
GET https://api.gocardless.com/billing_requests/BRQ123/institutions?country_code=GB HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
  "institutions": [
    {
        "id": "BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1",
        "name": "Bank of Scotland Business",
        "logo_url": "https://cdn.nordigen.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "icon_url": "https://cdn.nordigen.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "country_code": "GB",
        "autocompletes_collect_bank_account": true
    },
    {
        "id": "BANK_OF_SCOTLAND_BOFSGBS1",
        "name": "Bank of Scotland Personal",
        "logo_url": "https://cdn.nordigen.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "icon_url": "https://cdn.nordigen.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "country_code": "GB",
        "autocompletes_collect_bank_account": true
    }
  ]
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->institutions()->listForBillingRequest("BR123", [
  "params" => ["country_code" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

@client.institutions.listForBillingRequest("BR123", params={
  "country_code": "GB"
}).records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.institutions.listForBillingRequest("BR123", {
  params: { country_code: "GB" }
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

client.institutions().listForBillingRequest("BR123").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 institutions = await client.institutions.list_for_billing_request("BR123", { countryCode: 'GB'});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var request = new GoCardless.Services.InstitutionListForBillingRequestRequest()
 {
     CountryCode = "GB",
 };

var institutionListResponse = await gocardless.Institutions.ListForBillingRequestAsync("BR123", request);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  institutionListForBillingRequestParams := gocardless.InstitutionListForBillingRequestParams{
    CountryCode: "GB",
  }
  institutionListForBillingRequestResult, err := client.Institutions().ListForBillingRequest(context, "BR123", institutionListForBillingRequestParams)
  for _, institution := range institutionListForBillingRequestResult.Institutions {
      fmt.Println(institution.Id)
  }

}

Core Endpoints

Blocks

Blocks are created to prevent certain customer details from being used when creating mandates.

The details used to create blocks can be exact matches, like a bank account or an email, or a more generic match such as an email domain or bank name. Please be careful when creating blocks for more generic matches as this may block legitimate payers from using your service.

New block types may be added over time.

A block is in essence a simple rule that is used to match against details in a newly created mandate. If there is a successful match then the mandate is transitioned to a “blocked” state.

Please note:

  • Payments and subscriptions cannot be created against a mandate in blocked state.
  • A mandate can never be transitioned out of the blocked state.

The one exception to this is when blocking a ‘bank_name’. This block will prevent bank accounts from being created for banks that match the given name. To ensure we match bank names correctly an existing bank account must be used when creating this block. Please be aware that we cannot always match a bank account to a given bank name.

This API is currently only available for GoCardless Protect+ integrators - please get in touch if you would like to use this API.

Properties

id
Unique identifier, beginning with “BLC”.
active
Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
block_type
Type of entity we will seek to match against when blocking the mandate. This can currently be one of ‘email’, ‘email_domain’, ‘bank_account’, or ‘bank_name’.
created_at
Fixed timestamp, recording when this resource was created.
reason_description
This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
reason_type
The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
resource_reference
This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.
updated_at
Fixed timestamp, recording when this resource was updated.

Create a block

Creates a new Block of a given type. By default it will be active.

Relative endpoint: POST /blocks

Note: Block will be enabled if you try to create a block that already exists and is disabled.

Parameters

active
Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
block_type
Type of entity we will seek to match against when blocking the mandate. This can currently be one of ‘email’, ‘email_domain’, ‘bank_account’, or ‘bank_name’.
reason_description
This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
reason_type
The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
resource_reference
This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.
POST https://api.gocardless.com/blocks HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com"
  }
}

HTTP/1.1 201 Created
Location: /block/BLC123
Content-Type: application/json
{
  "blocks": {
    "id": "BLC123",
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com",
    "active": "true",
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T17:26:28.305Z"
  }
}

POST https://api.gocardless.com/blocks HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123"
  }
}

HTTP/1.1 201 Created
Location: /block/BLC456
Content-Type: application/json
{
  "blocks": {
    "id": "BLC456",
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123",
    "active": "true",
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T17:26:28.305Z"
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$block = $client->blocks()->create([
  "params" => [
      "block_type" => "email",
      "reason_type" => "no_intent_to_pay",
      "resource_reference" => "example@example.com",
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

block = client.blocks.create(
  params={
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com"
  }
)
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

block = @client.blocks.create(
  params: {
    block_type: "email",
    reason_type: "no_intent_to_pay",
    resource_reference: "example@example.com"
  }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Block block = client.blocks().create()
  .withBlockType(Block.BlockType.EMAIL)
  .withReasonType(Block.ReasonType.NO_INTENT_TO_PAY)
  .withResourceReference("example@example.com")
  .execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const block = await client.blocks.create({
  block_type: Types.BlockBlockType.Email,
  resource_reference: 'CU123',
  reason_type: Types.BlockReasonType.NoIntentToPay,
})
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.Blocks.CreateAsync(
  new GoCardless.Services.BlockCreateRequest()
  {
      BlockType = GoCardless.Services.BlockCreateRequest.BlockBlockType.Email,
      ReasonType = GoCardless.Services.BlockCreateRequest.BlockReasonType.NoIntentToPay,
      ResourceReference = "example@example.com"
  }
);
GoCardless.Resources.Block block = resp.Block;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  blockCreateParams := gocardless.BlockCreateParams{
    BlockType:         "email",
    ReasonType:        "no_intent_to_pay",
    ResourceReference: "example@example.com",
  }
  
  block, err := client.Blocks.Create(context, blockCreateParams)

}

Get a single block

Retrieves the details of an existing block.

Relative endpoint: GET /blocks/BLC123

GET https://api.gocardless.com/blocks/BLC456 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "blocks": {
    "id": "BLC456",
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com",
    "active": "true",
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T17:26:28.305Z"
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

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

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

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

Block block = client.blocks().get("BLC456").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const block = await client.blocks.find("BLC456");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.Blocks.GetAsync("BLC456");
GoCardless.Resources.Block block = resp.Block;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  block, err := client.Blocks.Get(context, "BLC456")

}

List multiple blocks

Returns a cursor-paginated list of your blocks.

Relative endpoint: GET /blocks

Parameters

after
Cursor pointing to the start of the desired set.
before
Cursor pointing to the end of the desired set.
block
ID of a Block.
block_type
Type of entity we will seek to match against when blocking the mandate. This can currently be one of ‘email’, ‘email_domain’, ‘bank_account’, or ‘bank_name’.
created_at
Fixed timestamp, recording when this resource was created.
limit
Number of records to return.
reason_type
The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
updated_at
Fixed timestamp, recording when this resource was updated.
GET https://api.gocardless.com/blocks HTTP/1.1

HTTP/1.1 200 OK
Location: /blocks
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "blocks": [
    {
      "id": "BLC123",
      "block_type": "email",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "example@example.com",
      "active": "true",
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    },
    {
      "id": "BLC456",
      "block_type": "email_domain",
      "reason_type": "identity_fraud",
      "resource_reference": "example.com",
      "active": "true",
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    }
  ]
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

foreach ($client->blocks()->all() as $record) {
  echo $record->id;
  echo $record->block_type;
}
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

for block in client.blocks.all():
  print(block.id)
  print(block.block_type)
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.blocks.all.each do |block|
  puts block.id
  puts block.block_type
end
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

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

for await (const block of client.blocks.all({})) {
  console.log(block.id);
  console.log(block.block_type);
}
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

foreach (GoCardless.Resources.Block block in gocardless.Blocks.All())
{
    Console.WriteLine(block.Id);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  blockListParams := gocardless.BlockListParams{}
  blockListResult, err := client.Blocks.List(context, blockListParams)
  for _, block := range blockListResult.Blocks {
      fmt.Println(block.Id)

}

Disable a block

Disables a block so that it no longer will prevent mandate creation.

Relative endpoint: POST /blocks/BLC123/actions/disable

POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "blocks": {
    "id": "BLC123",
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123",
    "active": "false",
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T19:26:28.305Z"
  }
}

POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1
HTTP/1.1 409 Conflict

POST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/disable HTTP/1.1
HTTP/1.1 404 NotFound
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$block = $client->blocks()->disable("BLC123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

block = @client.blocks.disable("BLC123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Block block = client.blocks().disable("BLC123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const block = await client.blocks.disable("BLC456");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.Blocks.DisableAsync("BLC123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  block, err := client.Blocks.Disable(context, "BLC123")

}

Enable a block

Enables a previously disabled block so that it will prevent mandate creation

Relative endpoint: POST /blocks/BLC123/actions/enable

POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "blocks": {
    "id": "BLC123",
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123",
    "active": "true",
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T19:26:28.305Z"
  }
}

POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1
HTTP/1.1 409 Conflict

POST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/enable HTTP/1.1
HTTP/1.1 404 NotFound
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$block = $client->blocks()->enable("BLC123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

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

block = @client.blocks.enable("BLC123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Block block = client.blocks().enable("BLC123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const block = await client.blocks.enable("BLC456");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.Blocks.EnableAsync("BLC123");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  block, err := client.Blocks.Enable(context, "BLC123")

}

Create blocks by reference

Creates new blocks for a given reference. By default blocks will be active. Returns 201 if at least one block was created. Returns 200 if there were no new blocks created.

Relative endpoint: POST /blocks/block_by_ref

Parameters

active
Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
reason_description
This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
reason_type
The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
reference_type
Type of entity we will seek to get the associated emails and bank accounts to create blocks from. This can currently be one of ‘customer’ or ‘mandate’.
reference_value
This field is a reference to the entity you wish to block based on its emails and bank accounts. This may be the ID of a customer or a mandate. This means in order to block by reference the entity must have already been created as a resource.
POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "reference_type": "customer",
    "reference_value": "CU123",
    "reason_type": "no_intent_to_pay"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "blocks": [
    {
      "id": "BLC123",
      "block_type": "email",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "example@example.com",
      "active": "true",
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    },
    {
      "id": "BLC456",
      "block_type": "bank_account",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "BA123",
      "active": "true",
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    }
  ]
}

POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "reference_type": "customer",
    "reference_value": "CU123",
    "reason_type": "no_intent_to_pay"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "blocks": [
    {
      "id": "BLC123",
      "block_type": "email",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "example@example.com",
      "active": "true",
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    },
    {
      "id": "BLC456",
      "block_type": "bank_account",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "BA123",
      "active": "true",
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    }
  ]
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$block = $client->blocks()->blockByRef([
  "params" => [
      "reference_type" => "customer",
      "reference_value" => "CU123",
      "reason_type" => "no_intent_to_pay",
  ]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

response = client.blocks.block_by_ref(
  params={
    "reference_type": "customer",
    "reference_value": "CU123",
    "reason_type": "no_intent_to_pay"
  }
)
blocks = response.records
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

resp = @client.blocks.block_by_ref(
  params: {
    reference_type: "customer",
    reference_value: "CU123"
    reason_type: "no_intent_to_pay",
  }
)
blocks = resp.records
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

Iterable<Block> iterable = client.blocks().blockByRef()
        .withReferenceType("customer")
        .withReferenceValue("CU123")
        .withReasonType("no_intent_to_pay")
        .execute();
List<Block> blocks = Lists.newArrayList(iterable);
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.blocks.block_by_ref(
  {
    reference_type: Types.BlockReferenceType.Customer,
    reference_value: 'CU123',
    reason_type: Types.BlockReasonType.NoIntentToPay
  }
);
const blocks = response.blocks;
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await client.Blocks.BlockByRefAsync(new BlockBlockByRefRequest() {
  ReferenceType = "customer",
    ReferenceValue = "CU123",
    ReasonType = "no_intent_to_pay",
});
IReadOnlyList < GoCardless.Resources.Block > blocks = resp.Blocks;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  blockBlockByRefParams := gocardless.BlockBlockByRefParams{
    ReferenceType: "customer",
    ReferenceValue: "CU123",
    ReasonType: "no_intent_to_pay",
  }
  
  blockBlockByRefResult, err := client.Blocks.BlockByRef(context, blockBlockByRefParams)
  for _, block := range blockBlockByRefResult.Blocks {
      fmt.Println(block.Id)
  }

}

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.
bank_reference_prefix
Prefix for the bank reference of payouts sent to this creditor. For instance, if the creditor’s bank_reference_prefix was ACME, the bank reference of a payout sent to that creditor could be ACME-8G7Q8.

This prefix is also used for refunds in EUR and GBP.

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.
creditor_type
The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.
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 trading 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 scheme identifier’s support address.

  • address_line2: The second line of the scheme identifier’s support address.

  • address_line3: The third line of the scheme identifier’s support address.

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

  • city: The city of the scheme identifier’s support address.

  • country_code: ISO 3166-1 alpha-2 code.

  • created_at: Fixed timestamp, recording when this resource was created.

  • currency: The currency of the scheme identifier.

  • email: Scheme identifier’s support email address.

  • id: Unique identifier, usually beginning with “SU”.

  • 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. This should usually be the merchant’s trading name.

  • phone_number: Scheme identifier’s support phone number.

  • postal_code: The scheme identifier’s support postal code.

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

  • region: The scheme identifier’s support address region, county or department.

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

  • status: The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.

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 GoCardless Embed customers. Please contact us if you are interested in using this product. Partners should instead manage multiple merchant accounts by building a partner integration.

Parameters

country_code
required ISO 3166-1 alpha-2 code.
creditor_type
required The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.
name
required The creditor’s trading name.
bank_reference_prefix
Prefix for the bank reference of payouts sent to this creditor. For instance, if the creditor’s bank_reference_prefix was ACME, the bank reference of a payout sent to that creditor could be ACME-8G7Q8.

This prefix is also used for refunds in EUR and GBP.

POST https://api.gocardless.com/creditors HTTP/1.1
Content-Type: application/json
{
  "creditors": {
    "name": "Acme",
    "country_code": "GB",
    "creditor_type": "company",
    "bank_reference_prefix": "ACME"
  }
}

HTTP/1.1 201 Created
Location: /creditors/CR123
Content-Type: application/json
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {}
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->creditors()->create([
  'params' => ['name' => 'Acme',
               'country_code' => 'GB',
               'bank_reference_prefix' => 'ACME',
               'creditor_type' => 'company']
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.creditors.create(params={
  "name": "Acme",
  "country_code": "GB",
  "creditor_type": "company",
  "bank_reference_prefix": "ACME",
})
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.creditors.create(
  params: {
    name: "Acme",
    country_code: "GB",
    creditor_type: "company",
    bank_reference_prefix: "ACME",
  }
)
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("Acme")
  .withCountryCode("GB")
  .withCreditorType("company")
  .withBankReferencePrefix("ACME")
  .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: "Acme",
  country_code: "GB",
  creditor_type: "company",
  bank_reference_prefix: "ACME",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var creditorRequest = new GoCardless.Services.CreditorCreateRequest()
{
    Name = "Acme",
    CountryCode = "GB",
    CreditorType = "company",
    BankReferencePrefix = "ACME",
};

var creditorResponse = await gocardless.Creditors.CreateAsync(creditorRequest);
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorCreateParams := gocardless.CreditorCreateParams{
    Name:                "Acme",
    CountryCode:         "GB",
    CreditorType:        "company",
    BankReferencePrefix: "ACME",
  }
  
  creditor, err := client.Creditors.Create(context, creditorCreateParams)

}

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.
GET https://api.gocardless.com/creditors HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null,
    },
    "limit": 50
  },
  "creditors":[{
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {}
  }]
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorListParams := gocardless.CreditorListParams{
    Limit: 3,
  }
  
  // List the first three creditors.
  creditorListResult, err := client.Creditors.List(context, creditorListParams)
  for _, creditor := creditorListResult.Creditors {
      fmt.Println(creditor.Name)
  }

}

Get a single creditor

Retrieves the details of an existing creditor.

Relative endpoint: GET /creditors/CR123

Parameters

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {}
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditor, err := client.Creditors.Get(context, "CR123")

}

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.
bank_reference_prefix
Prefix for the bank reference of payouts sent to this creditor. For instance, if the creditor’s bank_reference_prefix was ACME, the bank reference of a payout sent to that creditor could be ACME-8G7Q8.

This prefix is also used for refunds in EUR and GBP.

city
The city of the creditor’s address.
country_code
ISO 3166-1 alpha-2 code.
name
The creditor’s trading 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.
PUT https://api.gocardless.com/creditors/CR123 HTTP/1.1
Content-Type: application/json
{
  "creditors": {
    "links": {
      "default_gbp_payout_account": "BA789"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {
      "default_gbp_payout_account": "BA789",
    }
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->creditors()->update('CR123', [
  'params' => ['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={
  "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: "BA789" }
  }
)
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")
  .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",
  {
    links: {
      default_gbp_payout_account: "BA789"
    }
  }
);
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 = "BA789"
    }
};

var creditorResponse = await gocardless.Creditors.UpdateAsync("CR0123", creditorRequest);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorUpdateParams := gocardless.CreditorUpdateParams{
    Links: &gocardless.CreditorUpdateParamsLinks{
      DefaultGbpPayoutAccount: "BA789",
    },
  }
  
  creditor, err := client.Creditors.Update(context, "CR123", creditorUpdateParams)

}

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 true. 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.
POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB",
    "account_holder_name": "Acme",
    "links": {
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 Created
Location: /creditor_bank_accounts/BA123
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$client->creditorBankAccounts()->create([
  "params" => ["account_number" => "55779911",
               "branch_code" => "200000",
               "country_code" => "GB",
               "account_holder_name" => "Acme",
               "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",
  "account_holder_name": "Acme",
  "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",
    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")
  .withAccountHolderName("Acme")
  .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",
  account_holder_name: "Acme",
  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",
    Links = new GoCardless.Services.CreditorBankAccountCreateRequest.CreditorBankAccountLinks()
    {
        Creditor = "CR0123"
    }
};

var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.CreateAsync(creditorBankAccountRequest);
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorBankAccountCreateParams := gocardless.CreditorBankAccountCreateParams{
    AccountNumber:             "55779911",
    BranchCode:                "200000",
    CountryCode:               "GB",
    AccountHolderName:         "Acme",
  }
  
  creditorBankAccount, err := client.CreditorBankAccounts.Create(context, creditorBankAccountCreateParams)

}

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
If true, only return enabled bank accounts. If false, only return disabled bank accounts.
limit
Number of records to return.
GET https://api.gocardless.com/creditor_bank_accounts HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": "BA123",
    },
    "limit": 50
  },
  "creditor_bank_accounts":[{
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    }
  }, {
  ...
  }]
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorBankAccountListParams := gocardless.CreditorBankAccountListParams{}
  creditorBankAccountListResult, err := client.CreditorBankAccounts.List(context, creditorBankAccountListParams)
  for _, creditorBankAccount := range creditorBankAccountListResult.CreditorBankAccounts {
      fmt.Println(creditorBankAccount.Id)
  }

}

Get a single creditor bank account

Retrieves the details of an existing creditor bank account.

Relative endpoint: GET /creditor_bank_accounts/BA123

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorBankAccount, err := client.CreditorBankAccounts.Get(context, "BA123")

}

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

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": false,
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  creditorBankAccount, err := client.CreditorBankAccounts.Disable(context, "BA123")

}

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.
limit
Number of records to return.
source
Source currency
target
Target currency
GET https://api.gocardless.com/currency_exchange_rates?source=GBP&target=EUR HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
    "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
    }
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  currencyExchangeRateListParams := gocardless.CurrencyExchangeRateListParams{
    Source: "EUR",
    Target: "GBP",
  }
  
  currencyExchangeRateListResult, err := client.CurrencyExchangeRates.List(context, currencyExchangeRateListParams)
  for _, currencyExchangeRate := range currencyExchangeRateListResult.CurrencyExchangeRates {
      fmt.Println(currencyExchangeRate.Id)
  }

}

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

Note: this endpoint is a legacy API endpoint and does not support GoCardless’ newest features. We recommend using the Billing Requests API instead.

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.

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.
POST https://api.gocardless.com/customers HTTP/1.1
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerCreateParams := gocardless.CustomerCreateParams{
    AddressLine1: "27 Acer Road",
    AddressLine2: "Apt 2",
    City:         "London",
    PostalCode:   "E8 3GX",
    CountryCode:  "GB",
    Email:        "user@example.com",
    GivenName:    "Frank",
    FamilyName:   "Osborne",
  }
  
  customer, err := client.Customers.Create(context, customerCreateParams)

}

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. One of:
  • asc

  • desc

sort_field
Field by which to sort records. One of:
  • name

  • company_name

  • created_at

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }, {
  ...
  }]
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerListParams := gocardless.CustomerListParams{
    Currency: "GBP",
  }
  
  customerListResult, err := client.Customers.List(context, customerListParams)
  for _, customer GivenName range customerListResult.Customers {
      fmt.Println(customer.GivenName)
  }

}

Get a single customer

Retrieves the details of an existing customer.

Relative endpoint: GET /customers/CU123

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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"
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customer, err := client.Customers.Get(context, "CU123")

}

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.
PUT https://api.gocardless.com/customers/CU123 HTTP/1.1
Content-Type: application/json
{
  "customers": {
    "email": "updated_user@example.com",
    "given_name": "Jenny",
    "family_name": "Osborne",
    "metadata": {
      "salesforce_id": "EFGH5678"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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"
  }
}
$client = new \GoCardlessPro\Client([
  '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);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerUpdateParams := gocardless.CustomerUpdateParams{
    Email: "updated_user@example.com",
  }
  
  customer, err := client.Customers.Update(context, "CU123", customerUpdateParams)

}

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

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
Content-Type: application/json
{
  "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"
  }
}
$client = new \GoCardlessPro\Client([
  '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");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customer, err := client.Customers.Remove(context, "CU123")

}

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.

Note: To ensure the customer’s bank accounts are valid, verify them first using bank_details_lookups, before proceeding with creating the accounts

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

Note: this endpoint is a legacy API endpoint and does not support GoCardless’ newest features. We recommend using the Billing Requests API instead.

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.

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.
POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerBankAccountCreateParams := gocardless.CustomerBankAccountCreateParams{
    AccountNumber:     "55779911",
    BranchCode:        "200000",
    AccountHolderName: "Frank Osborne",
    CountryCode:       "GB",
    Links: gocardless.CustomerBankAccountCreateParamsLinks{
      Customer: "CU123",
    },
  }
  
  customerBankAccount, err := client.CustomerBankAccounts.Create(context, customerBankAccountCreateParams)

}

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.
GET https://api.gocardless.com/customer_bank_accounts HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }]
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerBankAccountListParams := gocardless.CustomerBankAccountListParams{
    Enabled: true,
  }
  
  customerBankAccountListResult, err := client.CustomerBankAccounts.List(context, customerBankAccountListParams)
  for _, customerBankAccount := range customerBankAccountListResult.CustomerBankAccounts {
      fmt.Println(customerBankAccount.Id)
  }

}

Get a single customer bank account

Retrieves the details of an existing bank account.

Relative endpoint: GET /customer_bank_accounts/BA123

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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"
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerBankAccount, err := client.CustomerBankAccounts.Get(context, "BA123")

}

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.
PUT https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
Content-Type: application/json
{
  "customer_bank_accounts": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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"
  }
}
$client = new \GoCardlessPro\Client([
  '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);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerBankAccountUpdateParams := gocardless.CustomerBankAccountUpdateParams{
    Metadata: map[string]interface{}{"key": "value"},
  }
  
  customerBankAccount, err := client.CustomerBankAccounts.Update(context, customerBankAccountUpdateParams)

}

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

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerBankAccount, err := client.CustomerBankAccounts.Disable(context, "BA123")

}

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. One of:
  • payment_created

  • payment_cancelled

  • mandate_created

  • mandate_blocked

  • subscription_created

  • subscription_cancelled

  • instalment_schedule_created

  • instalment_schedule_cancelled

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

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

HTTP/1.1 201 Created
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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
Content-Type: application/json
{
  "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."
      }
    ]
  }
}

$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  customerNotificationHandleParams := map[string]interface{}{}
  customerNotification, err := client.CustomerNotifications.Handle(context, "PCN123", customerNotificationHandleParams)

}

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. Event creation is an asynchronous process, so it can take some time between an action occurring and its corresponding event getting included in API responses. See here for a complete list of event types.

Properties

id
Unique identifier, beginning with “EV”.
action
What has happened to the resource. See Event Actions for the possible actions.
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: See here for a complete list of customer notification types.

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

  • payer: this event was triggered by a Payer

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 bank payment 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
The metadata that was passed when making the API request that triggered the event (for instance, cancelling a mandate).

This field will only be populated if the details[origin] field is api otherwise it will be an empty object.

resource_metadata
The metadata of the resource that the event is for. For example, this field will have the same value of the mandate[metadata] field on the response you would receive from performing a GET request on a mandate.
resource_type
The resource type for this event. One of:
  • billing_requests

  • creditors

  • instalment_schedules

  • mandates

  • payer_authorisations

  • payments

  • payouts

  • refunds

  • scheme_identifiers

  • subscriptions

links[bank_authorisation]
ID of a bank authorisation.
links[billing_request]
ID of a billing request.
links[billing_request_flow]
ID of a billing request flow.
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[mandate_request_mandate]
If resource_type is billing_requests, this is the ID of the mandate which has been created.
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[payment_request_payment]
If resource_type is billing_requests, this is the ID of the payment which has been created for Instant Bank Payment.
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[scheme_identifier]
If resource_type is scheme_identifiers, this is the ID of the scheme_identifier 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.
billing_request
ID of a billing request. If specified, this endpoint will return all events for the given billing request.
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 an creditor. If specified, this endpoint will return all events for the given creditor.
include
Includes linked resources in the response. Must be used with the resource_type parameter specified. The include should be one of:
  • billing_request

  • creditor

  • instalment_schedule

  • mandate

  • payer_authorisation

  • payment

  • payout

  • refund

  • scheme_identifier

  • subscription

instalment_schedule
ID of an instalment schedule. If specified, this endpoint will return all events for the given instalment schedule.
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 billing_request, creditor, instalment_schedule, mandate, payer_authorisation, payment, payout, refund, scheme_identifier or subscription parameters. The type can be one of:
  • billing_requests

  • creditors

  • instalment_schedules

  • mandates

  • payer_authorisations

  • payments

  • payouts

  • refunds

  • scheme_identifiers

  • subscriptions

scheme_identifier
ID of a scheme identifier. If specified, this endpoint will return all events for the given scheme identifier.
subscription
ID of a subscription. If specified, this endpoint will return all events for the given subscription.
GET https://api.gocardless.com/events HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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": {},
      "resource_metadata": { "order_id": "123" },
      "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": {},
      "resource_metadata": { "order_dispatch_date": "2014-05-22" },
      "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
Content-Type: application/json
{
  "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": {},
      "resource_metadata": { "order_dispatch_date": "2014-05-22" },
      "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"
        }
      }
    ]
  }
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  eventListParams := gocardless.EventListParams{
    ResourceType: "payments",
  }
  
  eventListResult, err := client.Events.List(context, eventListParams)
  for _, event := range eventListResult.Events {
      fmt.Println(event.Action)
  }

}

Get a single event

Retrieves the details of a single event.

Relative endpoint: GET /events/EV123

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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": {},
    "resource_metadata": { "order_dispatch_date": "2014-05-22" },
    "links": {
      "payment": "PM123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  event, err := client.Events.Get(context, "EV123")

}

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)
Content-Type: application/json
{
  "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)
Content-Type: application/json
{
  "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
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 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. Restricted: You can not specify a payment reference for Faster Payments.
retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.
links[mandate]
required ID of the associated mandate which the instalment schedule will create payments against.
POST https://api.gocardless.com/instalment_schedules HTTP/1.1
Content-Type: application/json

{
  "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
Content-Type: application/json
{
 "instalment_schedules": {
   "id": "IS123",
   "status": "pending",
   "total_amount": "2500",
   "metadata": {},
   "payment_errors": {},
   "links": {
     "mandate": "MD123",
     "customer": "CU123"
   }
 }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$instalment_schedule = $client->instalmentSchedules()->createWithDates([
    "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'
    ]
]);
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);

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 = GoCardless.Services.InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleCurrency.GBP,
        Name = "ACME Invoice 103",
        Instalments = new InstalmentScheduleInstalments[]
        {
            new InstalmentScheduleInstalments
            {
                ChargeDate = "2019-08-20",
                Amount = 3400,
            },
            new InstalmentScheduleInstalments
            {
                ChargeDate = "2019-09-03",
                Amount = 3400
            },
            new InstalmentScheduleInstalments
            {
                ChargeDate = "2019-09-17",
                Amount = 3200
            },
        },
        Links = new GoCardless
            .Services
            .InstalmentScheduleCreateWithDatesRequest
            .InstalmentScheduleLinks
            {
                Mandate = "MD0000XH9A3T4C"
            },
        Metadata = new Dictionary<string, string>
        {
            {"Invoice ID", "001"}
        },
        IdempotencyKey = "random_instalment_schedule_specific_string"
    }
);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  instalmentScheduleCreateWithDatesParams := gocardless.InstalmentScheduleCreateWithDatesParams{
    TotalAmount: 10000,
    AppFee: 10,
    Currency: "GBP",
    Instalments: []gocardless.InstalmentScheduleCreateWithDatesParamsInstalments{
      {
        Amount:     3400,
        ChargeDate: "2019-08-20",
      },
      {
        Amount:     3400,
        ChargeDate: "2019-09-03",
      },
      {
        Amount:     3400,
        ChargeDate: "2019-09-17",
      },
    },
    Links: gocardless.InstalmentScheduleCreateWithDatesParamsLinks{
      Mandate: "MD123",
    },
    Metadata: map[string]interface{}{"invoiceId": "001"},
  }
  
  requestOption := gocardless.WithIdempotencyKey("random_instalment_schedule_specific_string")
  instalmentSchedule, err := client.InstalmentSchedules().CreateWithDates(context, instalmentScheduleCreateWithDatesParams, requestOption)

}

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
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 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. Restricted: You can not specify a payment reference for Faster Payments.
retry_if_possible
On failure, automatically retry payments using intelligent retries. Default is false. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.
links[mandate]
required ID of the associated mandate which the instalment schedule will create payments against.
POST https://api.gocardless.com/instalment_schedules HTTP/1.1
Content-Type: application/json
{
  "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
Content-Type: application/json
{
 "instalment_schedules": {
   "id": "IS123",
   "status": "pending",
   "total_amount": "2500",
   "metadata": {},
   "payment_errors": {},
   "links": {
     "mandate": "MD123",
     "customer": "CU123"
   }
 }
}
$client = new \GoCardlessPro\Client([
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

$instalment_schedule = $client->instalmentSchedules()->createWithSchedule([
    "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"
    ]
]);
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 = GoCardless.Services.InstalmentScheduleCreateWithScheduleRequest.InstalmentScheduleCurrency.GBP,
        Name = "ACME Invoice 103",
        Instalments = new GoCardless
            .Services
            .InstalmentScheduleCreateWithScheduleRequest
            .InstalmentScheduleInstalments
            {
                StartDate = "2019-08-20",
                IntervalUnit = InstalmentScheduleCreateWithScheduleRequest.InstalmentScheduleInstalments.InstalmentScheduleIntervalUnit.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"
    }
);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  instalmentScheduleCreateWithScheduleParams := gocardless.InstalmentScheduleCreateWithScheduleParams{
    TotalAmount: 10000,
    AppFee:      10,
    Currency:    "GBP",
    Instalments: gocardless.InstalmentScheduleCreateWithScheduleParamsInstalments{
      Interval:     2,
      IntervalUnit: "monthly",
      Amounts:      []int{3400, 3400, 3200},
    },
    Metadata: map[string]interface{}{"invoiceId": "001"},
  }
  
  requestOption := gocardless.WithIdempotencyKey("random_instalment_schedule_specific_string")
  instalmentSchedule, err := client.InstalmentSchedules().CreateWithSchedule(context, instalmentScheduleCreateWithScheduleParams, requestOption)

}

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
GET https://api.gocardless.com/instalment_schedules?after=IS123 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }]
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  instalmentScheduleListParams := gocardless.InstalmentScheduleListParams{}
  instalmentScheduleListResult, err := client.InstalmentSchedules.List(context, instalmentScheduleListParams)
  for _, instalmentSchedule := range instalmentScheduleListResult.InstalmentSchedules {
      fmt.Println(instalmentSchedule.Name)
  }

}

Get a single instalment schedule

Retrieves the details of an existing instalment schedule.

Relative endpoint: GET /instalment_schedules/IS123

GET https://api.gocardless.com/instalment_schedules/IS123 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
 "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": {}
   }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  instalmentSchedule, err := client.InstalmentSchedules.Get(context, "IS123")

}

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.
PUT https://api.gocardless.com/instalment_schedules/IS123 HTTP/1.1
Content-Type: application/json
{
  "instalment_schedules": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
 "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"
   }
  }
}
$client = new \GoCardlessPro\Client([
  '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);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  instalmentScheduleUpdateParams := gocardless.InstalmentScheduleUpdateParams{
    Metadata: map[string]interface{"key": "value"}
  }
  
  instalmentSchedule, err := client.InstalmentSchedules.Update(context, "IS123", instalmentScheduleUpdateParams)

}

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

POST https://api.gocardless.com/instalment_schedules/IS123/actions/cancel HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  instalmentScheduleCancelParams = make(map[string]interface)
  instalmentSchedule, err := client.InstalmentSchedules.Cancel(context, "IS123", instalmentScheduleCancelParams)

}

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.
authorisation_source
This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

consent_parameters[end_date]
The latest date at which payments can be taken, must occur after start_date if present
consent_parameters[max_amount_per_payment]
The maximum amount that can be charged for a single payment
periods
Frequency configuration

Each instance will contain these properties:

  • max_amount_per_period: The maximum total amount that can be charged for all payments in this period

  • max_payments_per_period: The maximum number of payments that can be collected in this period

  • period: The repeating period for this mandate

consent_parameters[start_date]
The date from which payments can be taken
created_at
Fixed timestamp, recording when this resource was created.
funds_settlement
This field will decide how GoCardless handles settlement of funds from the customer.
  • managed will be moved through GoCardless’ account, batched, and payed out.
  • direct will be a direct transfer from the payer’s account to the merchant where invoicing will be handled separately.
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
Bank payment 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

  • suspended_by_payer: the mandate has been suspended by payer

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

  • blocked: the mandate has been blocked and payments cannot be created

verified_at
Timestamp recording when this mandate was verified.
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

Note: this endpoint is a legacy API endpoint and does not support GoCardless’ newest features. We recommend using the Billing Requests API instead.

Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.

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

authorisation_source
This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

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

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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
Bank payment 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.
POST https://api.gocardless.com/mandates HTTP/1.1
Content-Type: application/json
{
  "mandates": {
    "scheme": "bacs",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 Created
Location: /mandates/MD123
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateCreateParams := gocardless.MandateCreateParams{
    Scheme: "bacs",
    Links: gocardless.MandateCreateParamsLinks{
      CustomerBankAccount: "BA123",
      Creditor:            "CR123",
    },
    Metadata: map[string]interface{}{"contract": "ABCD1234"},
  }
  
  mandate, err := client.Mandates().Create(context, mandateCreateParams)

}

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.
mandate_type
Mandate type
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
GET https://api.gocardless.com/mandates HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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",
    "mandate_type": "bank_debit",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }]
}
$client = new \GoCardlessPro\Client([
  '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);
}
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateListParams := gocardless.MandateListParams{
    Customer: "CU123",
  }
  
  mandateListResult, err := client.Mandates.List(context, mandateListParams)
  for _, mandate := mandateListResult.Mandates {
      fmt.Println(mandate.Id)
  }

}

Get a single mandate

Retrieves the details of an existing mandate.

Relative endpoint: GET /mandates/MD123

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "mandate_type": "bank_debit",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandate, err := client.Mandates.Get(context, "MD123")

}

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.
PUT https://api.gocardless.com/mandates/MD123 HTTP/1.1
Content-Type: application/json
{
  "mandates": {
    "metadata": {
      "key": "value"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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);
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateUpdateParams := gocardless.MandateUpdateParams{
    Metadata: map[string]interface{}{"key": "value"},
  }
  
  mandate, err := client.Mandates.Update(context, "MD123", mandateUpdateParams)

}

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.
POST https://api.gocardless.com/mandates/MD123/actions/cancel HTTP/1.1
Content-Type: application/json
{
  "data": {
    "metadata": {}
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateCancelParams := gocardless.MandateCancelParams{}
  mandate, err := client.Mandates.Cancel(context, "MD123", mandateCancelParams)

}

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.
POST https://api.gocardless.com/mandates/MD123/actions/reinstate HTTP/1.1
Content-Type: application/json
{
  "data": {
    "metadata": {
      "ticket_id": "TK123"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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");
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateReinstateParams := gocardless.MandateReinstateParams{}
  mandate, err := client.Mandates.Reinstate(context, "MD123", mandateReinstateParams)

}

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.
  • created: A new mandate import.

  • submitted: After the integrator has finished adding mandates and submitted the import.

  • cancelled: If the integrator cancelled the mandate import.

  • processing: Once a mandate import has been approved by a GoCardless team member it will be in this state while mandates are imported.

  • processed: When all mandates have been imported successfully.

links[creditor]
ID of the associated creditor.

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 bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported.
links[creditor]
ID of the associated creditor. Only required if your account manages multiple creditors.
POST https://api.gocardless.com/mandate_imports HTTP/1.1
Content-Type: application/json
{
  "mandate_imports": {
    "scheme": "bacs"
  }
}

HTTP/1.1 201 Created
Location: /mandate_imports/IM000010790WX1
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "created",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateImportCreateParams := gocardless.MandateImportCreateParams{
    Scheme: "bacs",
  }
  
  mandateImport, err := client.MandateImports.Create(context, mandateImportCreateParams)

}

Get a mandate import

Returns a single mandate import.

Relative endpoint: GET /mandate_imports/IM000010790WX1

Parameters

GET https://api.gocardless.com/mandate_imports/IM000010790WX1 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "created",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateImport, err := client.MandateImports.Get("IM000010790WX1")

}

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

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "submitted",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

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

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "processing",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;
package main

import (
  gocardless "github.com/gocardless/gocardless-pro-go/v2"
)

func main() {
  accessToken := "your_access_token_here"
  config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
  if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
  }
  client, err := gocardless.New(config)
  if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
  }

  mandateImportSubmitParams := map[string]interface{}
  mandateImport, err := client.MandateImports.Submit(context, "IM000010790WX1", mandateImportSubmitParams)

}

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

POST https://api.gocardless.com/mandate_imports/IM000010790WX1/actions/cancel HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM000010790WX1",
    "scheme": "bacs",
    "status": "cancelled",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}
$client = new \GoCardlessPro\Client([
  '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;