Customer Bank Account

View as Markdown

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

Create a customer bank account#

POST/customer_bank_accounts

Creates a new customer bank account object.

There are three different ways to supply bank account details:

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

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

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

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

const customerBankAccount = await client.customerBankAccounts.create({
  account_number: "55779911",
  branch_code: "200000",
  account_holder_name: "Frank Osborne",
  country_code: "GB",
  links: {
    customer: "CU123"
  }
});

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

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

customerBankAccountCreateParams := gocardless.CustomerBankAccountCreateParams{
  AccountNumber:     "55779911",
  BranchCode:        "200000",
  AccountHolderName: "Frank Osborne",
  CountryCode:       "GB",
  Links: gocardless.CustomerBankAccountCreateParamsLinks{
    Customer: "CU123",
  },
}

customerBankAccount, err := client.CustomerBankAccounts.Create(ctx, customerBankAccountCreateParams)

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

var customerBankAccountResponse = await client.CustomerBankAccounts.CreateAsync(customerBankAccountRequest);
GoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;

Responsehttp

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

Request Body

customer_bank_accountsobject

10 properties

account_numberstring

Bank account number - see local details for more information. Alternatively you can provide an iban.

bank_codestring

Bank code - see local details for more information. Alternatively you can provide an iban.

branch_codestring

Branch code - see local details for more information. Alternatively you can provide an iban.

ibanstring

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.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

account_holder_namestring

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_typestring

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.

savingschecking

metadataobject

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.

linksobject

2 properties

customerstring

ID of the customer that owns this bank account.

customer_bank_account_tokenstring

ID of a customer bank account token to use in place of bank account parameters.

Response 201

Resource created successfully

customer_bank_accountsobject

14 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

bank_account_tokenstring

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.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

metadataobject

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.

linksobject

1 properties

customerstring

ID of the customer that owns this bank account.

trusted_recipientboolean

Whether this customer bank account is registered as a trusted recipient for Outbound Payments. Only present when the feature is enabled for the organisation.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

full: The name provided matches the name held by the bank.
close: The name provided is a close but not exact match to the name held by the bank.
cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.

fullclosecannot_perform_verification

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

List customer bank accounts#

GET/customer_bank_accounts

Returns a cursor-paginated list of your bank accounts.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.customer_bank_accounts.list

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

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

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

// List all 'enabled' customer bank accounts.
await client.customerBankAccounts.list({ enabled: true });

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

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

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

customerBankAccountListParams := gocardless.CustomerBankAccountListParams{
  Enabled: true,
}

customerBankAccountListResult, err := client.CustomerBankAccounts.List(ctx, customerBankAccountListParams)
for _, customerBankAccount := range customerBankAccountListResult.CustomerBankAccounts {
    fmt.Println(customerBankAccount.Id)
}

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

var customerBankAccountListResponse = client.CustomerBankAccounts.All(customerBankAccountRequest);
foreach (GoCardless.Resources.CustomerBankAccount customerBankAccount in customerBankAccountListResponse)
{
    Console.WriteLine(customerBankAccount.Id);
}

Responsehttp

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

Response 200

Successful response

customer_bank_accountsarray

14 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

bank_account_tokenstring

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.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

metadataobject

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.

linksobject

1 properties

customerstring

ID of the customer that owns this bank account.

trusted_recipientboolean

Whether this customer bank account is registered as a trusted recipient for Outbound Payments. Only present when the feature is enabled for the organisation.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

full: The name provided matches the name held by the bank.
close: The name provided is a close but not exact match to the name held by the bank.
cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.

fullclosecannot_perform_verification

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Get a single customer bank account#

GET/customer_bank_accounts/{customer_bank_account_id}

Retrieves the details of an existing bank account.

Path Parameters

Name	Type	Description
`customer_bank_account_id`required	string	The customer bank account id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.customer_bank_accounts.get("BA123")

client.customer_bank_accounts.get("BA123")

const customerBankAccount = await client.customerBankAccounts.find("BA123");

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

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

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

var customerBankAccountResponse = await client.CustomerBankAccounts.GetAsync("BA0123");
GoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;

Responsehttp

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

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

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

Response 200

Successful response

customer_bank_accountsobject

14 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

bank_account_tokenstring

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.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

metadataobject

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.

linksobject

1 properties

customerstring

ID of the customer that owns this bank account.

trusted_recipientboolean

Whether this customer bank account is registered as a trusted recipient for Outbound Payments. Only present when the feature is enabled for the organisation.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

full: The name provided matches the name held by the bank.
close: The name provided is a close but not exact match to the name held by the bank.
cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.

fullclosecannot_perform_verification

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Update a customer bank account#

PUT/customer_bank_accounts/{customer_bank_account_id}

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

Path Parameters

Name	Type	Description
`customer_bank_account_id`required	string	The customer bank account id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

PUT https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
Content-Type: application/json
{
  "customer_bank_accounts": {
    "metadata": {
      "key": "value"
    }
  }
}

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

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

const customerBankAccount = await client.customerBankAccounts.update(
  "BA123",
  {
    metadata: {
      key: "value"
    }
  }
);

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

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

customerBankAccountUpdateParams := gocardless.CustomerBankAccountUpdateParams{
  Metadata: map[string]string{"key": "value"},
}

customerBankAccount, err := client.CustomerBankAccounts.Update(ctx, "BA123", customerBankAccountUpdateParams)

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

var customerBankAccountResponse = await client.CustomerBankAccounts.UpdateAsync("BA0123", customerBankAccountRequest);

Responsehttp

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

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

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

Request Body

customer_bank_accountsobject

1 properties

metadataobject

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.

Response 200

Successful response

customer_bank_accountsobject

14 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

bank_account_tokenstring

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.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

metadataobject

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.

linksobject

1 properties

customerstring

ID of the customer that owns this bank account.

trusted_recipientboolean

Whether this customer bank account is registered as a trusted recipient for Outbound Payments. Only present when the feature is enabled for the organisation.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

full: The name provided matches the name held by the bank.
close: The name provided is a close but not exact match to the name held by the bank.
cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.

fullclosecannot_perform_verification

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Disable a customer bank account#

POST/customer_bank_accounts/{customer_bank_account_id}/actions/disable

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.

Path Parameters

Name	Type	Description
`customer_bank_account_id`required	string	The customer bank account id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.customer_bank_accounts.disable("BA123")

client.customer_bank_accounts.disable("BA123")

const customerBankAccount = await client.customerBankAccounts.disable("BA123");

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

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

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

var customerBankAccountResponse = await client.CustomerBankAccounts.DisableAsync("BA0123");

Responsehttp

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

Response 200

Action completed successfully

customer_bank_accountsobject

14 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

bank_account_tokenstring

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.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

metadataobject

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.

linksobject

1 properties

customerstring

ID of the customer that owns this bank account.

trusted_recipientboolean

Whether this customer bank account is registered as a trusted recipient for Outbound Payments. Only present when the feature is enabled for the organisation.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

full: The name provided matches the name held by the bank.
close: The name provided is a close but not exact match to the name held by the bank.
cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.

fullclosecannot_perform_verification

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject