Overview

This is the documentation for the GoCardless API.

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

OpenAPI Documentation
If you’re looking for the OpenAPI specification, you can view it from the OpenAPI documentation here.

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:

• Customers: Create
• Customer bank accounts: Create
• Payer details Confirm payer details
• 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

Payment creation

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:

Standard ACH can take 4-5 business days to receive payment, while Faster ACH through GoCardless will take 2-3 business days.

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 1 interbank business days before the payment due date.

You will need to notify your customers 2 working days in advance of the payment being collected or as soon as the payment is created if the payment is created less than 2 days before it is 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.

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:

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.

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

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. Minimum of 1.

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.

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.

insufficient_permissions_continue_on_dashboard

The access token you are using does not have permission to complete this action. This action can only be performed from the GoCardless dashboard.

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

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

Please note: bank authorisations can still fail despite an outcome=success on the redirect_uri. It is therefore recommended to wait for the relevant bank authorisation event, such as BANK_AUTHORISATION_AUTHORISED, BANK_AUTHORISATION_DENIED, or BANK_AUTHORISATION_FAILED in order to show the correct outcome to the user.

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.

Please note: bank authorisations can still fail despite an outcome=success on the redirect_uri. It is therefore recommended to wait for the relevant bank authorisation event, such as BANK_AUTHORISATION_AUTHORISED, BANK_AUTHORISATION_DENIED, or BANK_AUTHORISATION_FAILED in order to show the correct outcome to the user.

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.

Get a Bank Authorisation

Get a single bank authorisation.

Relative endpoint: GET /bank_authorisations/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. Important: All properties associated with subscription_request and instalment_schedule_request are only supported for ACH and PAD schemes.

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.

fallback_occurred

True if the billing request was completed with direct debit.

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

instalment_schedule_request[currency]

ISO 4217 currency code. Currently “USD” and “CAD” are supported.

instalments_with_dates

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

Each instance will contain these properties:

• amount: Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

• charge_date: A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

• description: A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

amounts

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

instalments_with_schedule[interval]

Number of interval_units between charge dates. Must be greater than or equal to 1.

instalments_with_schedule[interval_unit]

The unit of time between customer charge dates. One of weekly, monthly or yearly.

instalments_with_schedule[start_date]

The date on which the first payment should be charged. Must be on or after the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate’s next_possible_charge_date

links[instalment_schedule]

(Optional) ID of the instalment_schedule that was created from this instalment schedule request.

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

instalment_schedule_request[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.

instalment_schedule_request[payment_reference]

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details.

instalment_schedule_request[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.

instalment_schedule_request[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.

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[consent_type]

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

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 PayTo and VRP.

constraints[payment_method]

A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.

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. Defaults to flexible for PayTo if not specified.

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.

mandate_request[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.

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[payer_requested_dual_signature]

This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.

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[sweeping]

If true, this billing request would be used to set up a mandate solely for moving (or sweeping) money from one account owned by the payer to another account that the payer also owns. This is required for Faster Payments

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_context_code

Specifies the context or scenario in which the payment is being made. Defines whether the payment is for advance/arrears billing, point of sale transactions, ecommerce, or account transfers. This helps banks and payment processors understand the payment scenario and apply appropriate processing rules and risk controls.

payment_purpose_code

Specifies the underlying purpose of the payment. Defines the specific reason or type of service/goods the payment relates to, improving straight-through processing and compliance. See VRP Commercial Payment Purpose Codes for the complete list of valid codes.

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 supported Eurozone countries 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[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.

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[reference]

A custom payment reference defined by the merchant. It is only available for payments on the PayTo scheme or payments using the Direct Funds settlement model on the Faster Payments scheme.

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 supported Eurozone countries (EUR). For Eurozone countries, 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/category of a mandate and/or payment using a set of pre-defined categories. Provides context on the nature and reason for the payment to facilitate processing and compliance. See Billing Request Purpose Codes for the complete list of valid codes.

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. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. 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_account_token]

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

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

subscription_request[amount]

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

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

subscription_request[count]

The total number of payments that should be taken by this subscription.

subscription_request[currency]

ISO 4217 currency code. Currently “USD” and “CAD” are supported.

subscription_request[day_of_month]

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

subscription_request[interval]

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

subscription_request[interval_unit]

The unit of time between customer charge dates. One of weekly, monthly or yearly.

links[subscription]

(Optional) ID of the subscription that was created from this subscription request.

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

subscription_request[month]

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

subscription_request[name]

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

subscription_request[payment_reference]

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details.

subscription_request[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.

subscription_request[start_date]

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate’s next_possible_charge_date.

links[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[instalment_schedule_request]

(Optional) ID of the associated instalment schedule request

links[instalment_schedule_request_instalment_schedule]

(Optional) ID of the instalment_schedule that was created from this instalment schedule 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_provider]

(Optional) ID of the associated payment provider

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.

links[subscription_request]

(Optional) ID of the associated subscription request

links[subscription_request_subscription]

(Optional) ID of the subscription that was created from this subscription request.

Create a Billing Request

Important: All properties associated with subscription_request and instalment_schedule_request are only supported for ACH and PAD schemes.

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 supported Eurozone countries. 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.

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

instalment_schedule_request[currency]

ISO 4217 currency code. Currently “USD” and “CAD” are supported.

instalment_schedule_request[instalments_with_dates]

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

instalment_schedule_request[instalments_with_schedule]

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

Properties:

• amounts: List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).
• interval: Number of interval_units between charge dates. Must be greater than or equal to 1.
• interval_unit: The unit of time between customer charge dates. One of weekly, monthly or yearly.
• 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

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

instalment_schedule_request[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.

instalment_schedule_request[payment_reference]

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details.

instalment_schedule_request[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.

instalment_schedule_request[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.

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[consent_type]

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

mandate_request[constraints]

Constraints that will apply to the mandate_request. (Optional) Specifically required 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 PayTo and VRP.
• payment_method: A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.
• 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[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.

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[sweeping]

If true, this billing request would be used to set up a mandate solely for moving (or sweeping) money from one account owned by the payer to another account that the payer also owns. This is required for Faster Payments

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_context_code

Specifies the context or scenario in which the payment is being made. Defines whether the payment is for advance/arrears billing, point of sale transactions, ecommerce, or account transfers. This helps banks and payment processors understand the payment scenario and apply appropriate processing rules and risk controls.

payment_purpose_code

Specifies the underlying purpose of the payment. Defines the specific reason or type of service/goods the payment relates to, improving straight-through processing and compliance. See VRP Commercial Payment Purpose Codes for the complete list of valid codes.

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 supported Eurozone countries 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[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.

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[reference]

A custom payment reference defined by the merchant. It is only available for payments on the PayTo scheme or payments using the Direct Funds settlement model on the Faster Payments scheme.

payment_request[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. Important: This is not applicable to IBP and VRP payments.

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 supported Eurozone countries (EUR). For Eurozone countries, 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/category of a mandate and/or payment using a set of pre-defined categories. Provides context on the nature and reason for the payment to facilitate processing and compliance. See Billing Request Purpose Codes for the complete list of valid codes.

subscription_request[amount]

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

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

subscription_request[count]

The total number of payments that should be taken by this subscription.

subscription_request[currency]

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

subscription_request[day_of_month]

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

subscription_request[interval]

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

subscription_request[interval_unit]

The unit of time between customer charge dates. One of weekly, monthly or yearly.

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

subscription_request[month]

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

subscription_request[name]

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

subscription_request[payment_reference]

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details.

subscription_request[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.

subscription_request[start_date]

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate’s next_possible_charge_date.

links[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.

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

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.

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.

If the scheme is PayTo and the pay_id is available, this can be included in the payload along with the country_code.

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.

BACS scheme Payer Name Verification is enabled by default for UK based bank accounts, meaning we verify the account holder name and bank account number match the details held by the relevant bank.

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

Parameters

account_holder_name

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. 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.

pay_id

A unique record such as an email address, mobile number or company number, that can be used to make and accept payments.

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

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

Parameters

metadata

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

payer_requested_dual_signature

This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.

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.

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.

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 a single Billing Request

Fetches a billing request

Relative endpoint: GET /billing_requests/BRQ123

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.

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

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. If nothing is provided, institutions with the country code ‘GB’ are returned by default.

institution

required The unique identifier for this institution

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

customer_details_captured

Identifies whether a Billing Request belongs to a specific customer

exit_uri

URL that the payer can be taken to if there isn’t a way to progress ahead in flow, for example if the customer searches for a bank that doesn’t exist or isn’t supported on the scheme.

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.

skip_success_screen

If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.

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.

customer_details_captured

Identifies whether a Billing Request belongs to a specific customer

exit_uri

URL that the payer can be taken to if there isn’t a way to progress ahead in flow, for example if the customer searches for a bank that doesn’t exist or isn’t supported on the scheme.

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.

skip_success_screen

If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.

links[billing_request]

required ID of the billing request against which this flow was created.

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

Billing Request Templates

Billing Request Templates are reusable templates that result in numerous Billing Requests with similar attributes. They provide a no-code solution for generating various types of multi-user payment links.

Each template includes a reusable URL that can be embedded in a website or shared with customers via email. Every time the URL is opened, it generates a new Billing Request.

Billing Request Templates overcome the key limitation of the Billing Request: a Billing Request cannot be shared among multiple users because it is intended for single-use and is designed to cater to the unique needs of individual customers.

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

mandate_request_constraints[max_amount_per_payment]

The maximum amount that can be charged for a single payment. Required for PayTo and VRP.

mandate_request_constraints[payment_method]

A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.

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. Defaults to flexible for PayTo if not specified.

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

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

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 supported Eurozone countries 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 supported Eurozone countries (EUR). For Eurozone countries, 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.

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 supported Eurozone countries (EUR). For Eurozone countries, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.

Get a single Billing Request Template

Fetches a Billing Request Template

Relative endpoint: GET /billing_request_templates/BRT123

Create a Billing Request Template

Relative endpoint: POST /billing_request_templates

Parameters

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

mandate_request_constraints[max_amount_per_payment]

The maximum amount that can be charged for a single payment. Required for PayTo and VRP.

mandate_request_constraints[payment_method]

A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.

mandate_request_constraints[periodic_limits]

List of periodic limits and constraints which apply to them

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

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

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 supported Eurozone countries 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 supported Eurozone countries (EUR). For Eurozone countries, 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.

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/BRT123

Parameters

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

mandate_request_constraints[max_amount_per_payment]

The maximum amount that can be charged for a single payment. Required for PayTo and VRP.

mandate_request_constraints[payment_method]

A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.

mandate_request_constraints[periodic_limits]

List of periodic limits and constraints which apply to them

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

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

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 supported Eurozone countries 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 supported Eurozone countries (EUR). For Eurozone countries, 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.

Billing Request with Actions

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

bank_authorisations[authorisation_type]

Type of authorisation, can be either ‘mandate’ or ‘payment’.

bank_authorisations[authorised_at]

Fixed timestamp, recording when the user has been authorised.

bank_authorisations[created_at]

Timestamp when the flow was created

bank_authorisations[expires_at]

Timestamp when the url will expire. Each authorisation url currently lasts for 15 minutes, but this can vary by bank.

bank_authorisations[id]

Unique identifier, beginning with “BAU”.

bank_authorisations[last_visited_at]

Fixed timestamp, recording when the authorisation URL has been visited.

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.

bank_authorisations[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.

bank_authorisations[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.

Please note: bank authorisations can still fail despite an outcome=success on the redirect_uri. It is therefore recommended to wait for the relevant bank authorisation event, such as BANK_AUTHORISATION_AUTHORISED, BANK_AUTHORISATION_DENIED, or BANK_AUTHORISATION_FAILED in order to show the correct outcome to the user.

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.

bank_authorisations[url]

URL for an oauth flow that will allow the user to authorise the payment

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.

billing_requests[created_at]

Fixed timestamp, recording when this resource was created.

billing_requests[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.

billing_requests[fallback_occurred]

True if the billing request was completed with direct debit.

billing_requests[id]

Unique identifier, beginning with “BRQ”.

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

instalment_schedule_request[currency]

ISO 4217 currency code. Currently “USD” and “CAD” are supported.

instalments_with_dates

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

Each instance will contain these properties:

• amount: Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

• charge_date: A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

• description: A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

amounts

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

instalments_with_schedule[interval]

Number of interval_units between charge dates. Must be greater than or equal to 1.

instalments_with_schedule[interval_unit]

The unit of time between customer charge dates. One of weekly, monthly or yearly.

instalments_with_schedule[start_date]

The date on which the first payment should be charged. Must be on or after the mandate’s next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate’s next_possible_charge_date

links[instalment_schedule]

(Optional) ID of the instalment_schedule that was created from this instalment schedule request.

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

instalment_schedule_request[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.

instalment_schedule_request[payment_reference]

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details.

instalment_schedule_request[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.

instalment_schedule_request[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[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[instalment_schedule_request]

(Optional) ID of the associated instalment schedule request

links[instalment_schedule_request_instalment_schedule]

(Optional) ID of the instalment_schedule that was created from this instalment schedule 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_provider]

(Optional) ID of the associated payment provider

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.

links[subscription_request]

(Optional) ID of the associated subscription request

links[subscription_request_subscription]

(Optional) ID of the subscription that was created from this subscription request.

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[consent_type]

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

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 PayTo and VRP.

constraints[payment_method]

A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.

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. Defaults to flexible for PayTo if not specified.

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.

mandate_request[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.

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[payer_requested_dual_signature]

This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.

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[sweeping]

If true, this billing request would be used to set up a mandate solely for moving (or sweeping) money from one account owned by the payer to another account that the payer also owns. This is required for Faster Payments

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.

billing_requests[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.

billing_requests[payment_context_code]

Specifies the context or scenario in which the payment is being made. Defines whether the payment is for advance/arrears billing, point of sale transactions, ecommerce, or account transfers. This helps banks and payment processors understand the payment scenario and apply appropriate processing rules and risk controls.

billing_requests[payment_purpose_code]

Specifies the underlying purpose of the payment. Defines the specific reason or type of service/goods the payment relates to, improving straight-through processing and compliance. See VRP Commercial Payment Purpose Codes for the complete list of valid codes.

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 supported Eurozone countries 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[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.

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[reference]

A custom payment reference defined by the merchant. It is only available for payments on the PayTo scheme or payments using the Direct Funds settlement model on the Faster Payments scheme.

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 supported Eurozone countries (EUR). For Eurozone countries, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.

billing_requests[purpose_code]

Specifies the high-level purpose/category of a mandate and/or payment using a set of pre-defined categories. Provides context on the nature and reason for the payment to facilitate processing and compliance. See Billing Request Purpose Codes for the complete list of valid codes.

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. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. 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_account_token]

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

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.

billing_requests[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

subscription_request[amount]

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

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

subscription_request[count]

The total number of payments that should be taken by this subscription.

subscription_request[currency]

ISO 4217 currency code. Currently “USD” and “CAD” are supported.

subscription_request[day_of_month]

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

subscription_request[interval]

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

subscription_request[interval_unit]

The unit of time between customer charge dates. One of weekly, monthly or yearly.

links[subscription]

(Optional) ID of the subscription that was created from this subscription request.

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

subscription_request[month]

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

subscription_request[name]

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

subscription_request[payment_reference]

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer’s bank statement. See the documentation for the create payment endpoint for more details.

subscription_request[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.

subscription_request[start_date]

The date on which the first payment should be charged. If fulfilled after this date, this will be set as 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.

Create a Billing Request with Actions

Creates a billing request and completes any specified actions in a single request. This endpoint allows you to create a billing request and immediately complete actions such as collecting customer details, bank account details, or other required actions.

Relative endpoint: POST /billing_requests/create_with_actions

Note: to modify data on an already created billing request, call individual action endpoints. Calling this endpoint creates a new billing request everytime.

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

Warning: ACH/PAD is not supported on this endpoint.

Parameters

actions[bank_authorisation_redirect_uri]

URL for an oauth flow that will allow the user to authorise the payment

actions[collect_bank_account]

 

Properties:

• account_holder_name: Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. 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.
• pay_id: A unique record such as an email address, mobile number or company number, that can be used to make and accept payments.

actions[collect_customer_details]

 

Properties:

• customer:
• customer_billing_detail:

actions[confirm_payer_details]

 

Properties:

• 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_requested_dual_signature: This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.

actions[create_bank_authorisation]

Create a bank authorisation object as part of this request

actions[select_institution]

 

Properties:

• country_code: ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code ‘GB’ are returned by default.
• institution: The unique identifier for this institution

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 required 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 PayTo and VRP.
• payment_method: A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.
• 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[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.

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[sweeping]

If true, this billing request would be used to set up a mandate solely for moving (or sweeping) money from one account owned by the payer to another account that the payer also owns. This is required for Faster Payments

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_context_code

Specifies the context or scenario in which the payment is being made. Defines whether the payment is for advance/arrears billing, point of sale transactions, ecommerce, or account transfers. This helps banks and payment processors understand the payment scenario and apply appropriate processing rules and risk controls.

payment_purpose_code

Specifies the underlying purpose of the payment. Defines the specific reason or type of service/goods the payment relates to, improving straight-through processing and compliance. See VRP Commercial Payment Purpose Codes for the complete list of valid codes.

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 supported Eurozone countries 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[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.

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[reference]

A custom payment reference defined by the merchant. It is only available for payments on the PayTo scheme or payments using the Direct Funds settlement model on the Faster Payments scheme.

payment_request[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. Important: This is not applicable to IBP and VRP payments.

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 supported Eurozone countries (EUR). For Eurozone countries, 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/category of a mandate and/or payment using a set of pre-defined categories. Provides context on the nature and reason for the payment to facilitate processing and compliance. See Billing Request Purpose Codes for the complete list of valid codes.

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.

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. If nothing is provided, institutions with the country code ‘GB’ are returned by default.

icon_url

A URL pointing to the icon for this institution

limits[daily]

Daily limit details for this institution, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). The ‘limits’ property is only available via an authenticated request with a generated access token

limits[single]

Single transaction limit details for this institution, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). The ‘limits’ property is only available via an authenticated request with a generated access token

logo_url

A URL pointing to the logo for this institution

name

A human readable name for this institution

status

The status of the institution

List Institutions

Returns a list of supported institutions.

Relative endpoint: GET /institutions

Parameters

branch_code

(Currently only supports UK sort-codes) The six-digit number that identifies both the bank and the specific branch where an account is held, eg. ‘601234’.

country_code

ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code ‘GB’ are returned by default.

feature

The feature that institutions support. The available options include pis, and vrp_sweeping. If nothing is provided, institutions supporting ‘pis’ are returned by default.

scheme

The scheme that institutions support. The available options include faster_payments, sepa_credit_transfer, and sepa_instant_credit_transfer. If nothing is provided, institutions supporting ‘faster_payments’ are returned by default.

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. If nothing is provided, institutions with the country code ‘GB’ are returned by default.

ids

ID(s) of the institution(s) to retrieve. More than one ID can be specified using a comma-separated string.

include_disabled

Indicates whether to include temporarily disabled institutions in the response. If not provided or set to false, only enabled institutions will be returned.

search

A search substring for retrieving institution(s), based on the institution’s name.

Core Endpoints

Balances

Returns the balances for a creditor. These balances are the same as what’s shown in the dashboard with one exception (mentioned below under balance_type).

These balances will typically be 3-5 minutes old. The balance amounts likely won’t match what’s shown in the dashboard as the dashboard balances are updated much less frequently (once per day).

Properties

amount

The total amount in the balance, defined as the sum of all debits subtracted from the sum of all credits, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

balance_type

Type of the balance. Could be one of

• pending_payments_submitted: Payments we have submitted to the scheme but not yet confirmed. This does not exactly correspond to Pending payments in the dashboard, because this balance does not include payments that are pending submission.

• confirmed_funds: Payments that have been confirmed minus fees and unclaimed debits for refunds, failures and chargebacks. These funds have not yet been moved into a payout.

• pending_payouts: Confirmed payments that have been moved into a payout. This is the total due to be paid into your bank account in the next payout run (payouts happen once every business day). pending_payouts will only be non-zero while we are generating and submitting the payouts to our partner bank.

currency

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

last_updated_at

Dynamic timestamp recording when this resource was last updated.

links[creditor]

ID of the associated creditor.

List balances

Returns a cursor-paginated list of balances for a given creditor. This endpoint is rate limited to 60 requests per minute.

Relative endpoint: GET /balances

Parameters

creditor

required ID of a creditor.

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.

Bank Account Details

Retrieve bank account details in JWE encrypted format

Properties

ciphertext

Base64 URL encoded encrypted payload, in this case bank details.

encrypted_key

Base64 URL encoded symmetric content encryption key, encrypted with the asymmetric key from your JWKS.

iv

Base64 URL encoded initialization vector, used during content encryption.

protected

Base64 URL encoded JWE header values, containing the following keys:

• alg: the asymmetric encryption type used to encrypt symmetric key, e.g: RSA-OAEP.
• enc: the content encryption type, e.g: A256GCM.
• kid: the ID of an RSA-2048 public key, from your JWKS, used to encrypt the AES key.

tag

Base64 URL encoded authentication tag, used to verify payload integrity during decryption.

Get encrypted bank details

Returns bank account details in the flattened JSON Web Encryption format described in RFC 7516.

You must specify a Gc-Key-Id header when using this endpoint. See Public Key Setup for more details.

Relative endpoint: GET /bank_account_details/BA123

Note: See our Security Requirements before using this feature

Restricted: This endpoint is restricted to organisations with the Encrypted Bank Details Access upgrade

Parameters

Bank Account Holder Verifications

Create a bank account holder verification for a bank account.

Properties

id

The unique identifier for the bank account holder verification resource, e.g. “BAHV123”.

actual_account_name

The actual account name returned by the recipient’s bank, populated only in the case of a partial match.

result

Result of the verification, could be one of

• full_match: The verification has confirmed that the account name exactly matches the details provided.

• partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.

• no_match: The verification concludes the provided name does not match the account details.

• unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

status

The status of the bank account holder verification.

• pending: We have triggered the verification, but the result has not come back yet.

• completed: The verification is complete and is ready to be used.

type

Type of the verification that has been performed eg. Confirmation of Payee

Create a bank account holder verification.

Verify the account holder of the bank account. A complete verification can be attached when creating an outbound payment. This endpoint allows partner merchants to create Confirmation of Payee checks on customer bank accounts before sending outbound payments.

Relative endpoint: POST /bank_account_holder_verifications

Parameters

type

required Type of the verification that has been performed eg. Confirmation of Payee

links[bank_account]

required The ID of the bank account to verify, e.g. “BA123”.

Get a bank account holder verification.

Fetches a bank account holder verification by ID.

Relative endpoint: GET /bank_account_holder_verifications/BAHV123

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.

Get a single block

Retrieves the details of an existing block.

Relative endpoint: GET /blocks/BLC123

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.

Disable a block

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

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

Enable a block

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

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

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.

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.

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 a single creditor

Retrieves the details of an existing creditor.

Relative endpoint: GET /creditors/CR123

Parameters

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.

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.

verification_status

Verification status of the Bank Account. Can be one of pending, in_review or successful

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.

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 a single creditor bank account

Retrieves the details of an existing creditor bank account.

Relative endpoint: GET /creditor_bank_accounts/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

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

Customers

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

Properties

id

Unique identifier, beginning with “CU”.

address_line1

The first line of the customer’s address.

address_line2

The second line of the customer’s address.

address_line3

The third line of the customer’s address.

city

The city of the customer’s address.

company_name

Customer’s company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”).

country_code

ISO 3166-1 alpha-2 code.

created_at

Fixed timestamp, recording when this resource was created.

danish_identity_number

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).

email

Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

family_name

Customer’s surname. Required unless a company_name is provided.

given_name

Customer’s first name. Required unless a company_name is provided.

language

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to “en”.

metadata

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

phone_number

ITU E.123 formatted phone number, including country code.

postal_code

The customer’s postal code.

region

The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

swedish_identity_number

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

Create a customer

Creates a new customer object.

Relative endpoint: POST /customers

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

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

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.

List customers

Returns a cursor-paginated list of your customers.

Relative endpoint: GET /customers

Parameters

action_required

Boolean indicating whether the customer has any actions required.

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 a single customer

Retrieves the details of an existing customer.

Relative endpoint: GET /customers/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.

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

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. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. 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_account_token

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

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:

• Local details

• IBAN

• Customer Bank Account Tokens

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. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. 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.

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 a single customer bank account

Retrieves the details of an existing bank account.

Relative endpoint: GET /customer_bank_accounts/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.

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

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

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 Types 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[item_count]

Count of rows in the csv. This is sent for export events

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

• exports

• instalment_schedules

• mandates

• payer_authorisations

• payments

• payouts

• refunds

• scheme_identifiers

• subscriptions

• outbound_payments

• payment_account_transactions

source[name]

The name of the event’s source.

source[type]

The type of the event’s source.

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]

This is the id of the mandate request associated to this event

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[outbound_payment]

If resource_type is outbound_payments, this is the ID of the outbound_payment which has been updated.

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_account_transaction]

If resource_type is payment_account_transaction, this is the ID of a transaction which has been recorded on the payment account.

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.