Restricted: this endpoint requires approved [custom payment pages](https://support.gocardless.com/hc/en-gb/articles/115004521925-Custom-Payment-Pages).
Note: this endpoint is a legacy API endpoint and does not support GoCardless' newest features. We recommend using the [Billing Requests API](/billing-requests/overview) instead.
### Request body Wrap request body attributes in a `customer_bank_accounts` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `account_number` | string \| null | No | Bank account number - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`. | | `bank_code` | string \| null | No | Bank code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`. | | `branch_code` | string \| null | No | Branch code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`. | | `iban` | string \| null | No | International Bank Account Number. Alternatively you can provide [local details](#appendix-local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](#local-bank-details-sweden). | | `country_code` | string \| null | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string \| null | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_type` | enum \| null | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `metadata` | object | No | 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` | object | Yes | | ### Responses | Status | Description | | --- | --- | | 201 | Resource created successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | ### Response body The response is wrapped in a `customer_bank_accounts` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | No | Unique identifier, beginning with "BA". | | `created_at` | string | No | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_number_ending` | string \| null | No | The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies. | | `account_type` | enum \| null | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `country_code` | string \| null | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string \| null | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `bank_name` | string \| null | No | Name of bank, taken from the bank details. | | `bank_account_token` | string \| null | No | 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. | | `enabled` | boolean | No | Boolean value showing whether the bank account is enabled or disabled. | | `metadata` | object | No | 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` | object | No | | | `trusted_recipient` | boolean | No | 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_result` | enum | No | 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. | ### Error body Errors are wrapped in an `error` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | integer | No | | | `documentation_url` | string | No | | | `errors` | array | Yes | | | `message` | string | Yes | | | `request_id` | string | Yes | | | `type` | string | No | | --- ## List customer bank accounts `GET /customer_bank_accounts` Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your bank accounts. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `before` | query | string \| null | No | Cursor pointing to the end of the desired set. | | `after` | query | string \| null | No | Cursor pointing to the start of the desired set. | | `limit` | query | | No | Number of records to return. | | `created_at` | query | object | No | | | `customer` | query | string | No | Unique identifier, beginning with "CU". | | `enabled` | query | | No | Get enabled or disabled customer bank accounts. | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | ### Response body Each item in the `customer_bank_accounts` array has the following attributes. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | No | Unique identifier, beginning with "BA". | | `created_at` | string | No | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_number_ending` | string \| null | No | The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies. | | `account_type` | enum \| null | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `country_code` | string \| null | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string \| null | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `bank_name` | string \| null | No | Name of bank, taken from the bank details. | | `bank_account_token` | string \| null | No | 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. | | `enabled` | boolean | No | Boolean value showing whether the bank account is enabled or disabled. | | `metadata` | object | No | 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` | object | No | | | `trusted_recipient` | boolean | No | 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_result` | enum | No | 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. | ### Error body Errors are wrapped in an `error` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | integer | No | | | `documentation_url` | string | No | | | `errors` | array | Yes | | | `message` | string | Yes | | | `request_id` | string | Yes | | | `type` | string | No | | --- ## Get a single customer bank account `GET /customer_bank_accounts/{customer_bank_account_id}` Retrieves the details of an existing bank account. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `customer_bank_account_id` | path | string | Yes | The customer bank account id | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | ### Response body The response is wrapped in a `customer_bank_accounts` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | No | Unique identifier, beginning with "BA". | | `created_at` | string | No | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_number_ending` | string \| null | No | The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies. | | `account_type` | enum \| null | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `country_code` | string \| null | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string \| null | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `bank_name` | string \| null | No | Name of bank, taken from the bank details. | | `bank_account_token` | string \| null | No | 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. | | `enabled` | boolean | No | Boolean value showing whether the bank account is enabled or disabled. | | `metadata` | object | No | 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` | object | No | | | `trusted_recipient` | boolean | No | 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_result` | enum | No | 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. | ### Error body Errors are wrapped in an `error` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | integer | No | | | `documentation_url` | string | No | | | `errors` | array | Yes | | | `message` | string | Yes | | | `request_id` | string | Yes | | | `type` | string | No | | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `customer_bank_account_id` | path | string | Yes | The customer bank account id | ### Request body Wrap request body attributes in a `customer_bank_accounts` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | ### Response body The response is wrapped in a `customer_bank_accounts` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | No | Unique identifier, beginning with "BA". | | `created_at` | string | No | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_number_ending` | string \| null | No | The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies. | | `account_type` | enum \| null | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `country_code` | string \| null | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string \| null | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `bank_name` | string \| null | No | Name of bank, taken from the bank details. | | `bank_account_token` | string \| null | No | 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. | | `enabled` | boolean | No | Boolean value showing whether the bank account is enabled or disabled. | | `metadata` | object | No | 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` | object | No | | | `trusted_recipient` | boolean | No | 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_result` | enum | No | 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. | ### Error body Errors are wrapped in an `error` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | integer | No | | | `documentation_url` | string | No | | | `errors` | array | Yes | | | `message` | string | Yes | | | `request_id` | string | Yes | | | `type` | string | No | | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `customer_bank_account_id` | path | string | Yes | The customer bank account id | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | ### Response body The response is wrapped in a `customer_bank_accounts` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | No | Unique identifier, beginning with "BA". | | `created_at` | string | No | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_number_ending` | string \| null | No | The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies. | | `account_type` | enum \| null | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `country_code` | string \| null | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string \| null | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `bank_name` | string \| null | No | Name of bank, taken from the bank details. | | `bank_account_token` | string \| null | No | 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. | | `enabled` | boolean | No | Boolean value showing whether the bank account is enabled or disabled. | | `metadata` | object | No | 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` | object | No | | | `trusted_recipient` | boolean | No | 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_result` | enum | No | 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. | ### Error body Errors are wrapped in an `error` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | integer | No | | | `documentation_url` | string | No | | | `errors` | array | Yes | | | `message` | string | Yes | | | `request_id` | string | Yes | | | `type` | string | No | |