Creditor Bank Account

View as Markdown

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.

Create a creditor bank account#

POST/creditor_bank_accounts

Creates a new creditor bank account object.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB",
    "account_holder_name": "Acme",
    "links": {
      "creditor": "CR123"
    }
  }
}

@client.creditor_bank_accounts.create(
  params: {
    account_holder_name: "Example Ltd",
    account_number: "55779911",
    branch_code: "200000",
    country_code: "GB",
    links: {
      creditor: "CR123"
    }
  }
)

client.creditor_bank_accounts.create(params={
  "account_number": "55779911",
  "branch_code": "200000",
  "country_code": "GB",
  "account_holder_name": "Acme",
  "links": {
    "creditor": "CR123"
  }
})

const creditorBankAccount = await client.creditorBankAccounts.create({
  account_number: "55779911",
  branch_code: "200000",
  country_code: "GB",
  account_holder_name: "Acme",
  links: {
    creditor: "CR123"
  }
});

$client->creditorBankAccounts()->create([
  "params" => ["account_number" => "55779911",
               "branch_code" => "200000",
               "country_code" => "GB",
               "account_holder_name" => "Acme",
               "links" => ["creditor" => "CR123"]]
]);

CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .withAccountHolderName("Acme")
  .withLinksCreditor("CR123")
  .execute();

creditorBankAccountCreateParams := gocardless.CreditorBankAccountCreateParams{
  AccountNumber:             "55779911",
  BranchCode:                "200000",
  CountryCode:               "GB",
  AccountHolderName:         "Acme",
}

creditorBankAccount, err := client.CreditorBankAccounts.Create(ctx, creditorBankAccountCreateParams)

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

var creditorBankAccountResponse = await client.CreditorBankAccounts.CreateAsync(creditorBankAccountRequest);
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;

Responsehttp

HTTP/1.1 201 Created
Location: /creditor_bank_accounts/BA123
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    },
    "verification_status": "pending"
  }
}

Request Body

creditor_bank_accountsobject

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

set_as_default_payout_accountboolean

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.

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

creditorstring

ID of the creditor that owns this bank account.

Response 201

Resource created successfully

creditor_bank_accountsobject

12 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

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

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

creditorstring

ID of the creditor that owns this bank account.

verification_statusstring

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

pendingin_reviewsuccessfulcould_not_verify

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 creditor bank accounts#

GET/creditor_bank_accounts

Returns a cursor-paginated list of your creditor bank accounts.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.creditor_bank_accounts.list

@client.creditor_bank_accounts.list(params: { enabled: true })

client.creditor_bank_accounts.list().records

client.creditor_bank_accounts.list(params={"creditor": "CR123"}).records

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

// List all 'enabled' creditor bank accounts.
const enabledCreditorBankAccounts = await client.creditorBankAccounts.list({ enabled: true });

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

$client->creditorBankAccounts()->list([
  "params" => ["enabled" => true]
]);

for (CreditorBankAccount creditorBankAccount : client.creditorBankAccounts().all().withCreditor("CR123").execute()) {
  System.out.println(creditorBankAccount.getId());
}

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

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

var creditorBankAccountListResponse = client.CreditorBankAccounts.All(creditorBankAccountRequest);
foreach (GoCardless.Resources.CreditorBankAccount creditorBankAccount in creditorBankAccountListResponse)
{
    Console.WriteLine(creditorBankAccount.Id);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": "BA123"
    },
    "limit": 50
  },
  "creditor_bank_accounts":[{
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    },
    "verification_status": "pending"
  }]
}

Response 200

Successful response

creditor_bank_accountsarray

12 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

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

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

creditorstring

ID of the creditor that owns this bank account.

verification_statusstring

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

pendingin_reviewsuccessfulcould_not_verify

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 creditor bank account#

GET/creditor_bank_accounts/{creditor_bank_account_id}

Retrieves the details of an existing creditor bank account.

Path Parameters

Name	Type	Description
`creditor_bank_account_id`required	string	The creditor bank account id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.creditor_bank_accounts.get("BA123")

client.creditor_bank_accounts.get("BA123")

const creditorBankAccount = await client.creditorBankAccounts.find('BA123');

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

CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().get("BA123").execute();

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

var creditorBankAccountResponse = await client.CreditorBankAccounts.GetAsync("BA0123");
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": true,
    "links": {
      "creditor": "CR123"
    },
    "verification_status": "pending"
  }
}

Response 200

Successful response

creditor_bank_accountsobject

12 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

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

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

creditorstring

ID of the creditor that owns this bank account.

verification_statusstring

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

pendingin_reviewsuccessfulcould_not_verify

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 creditor bank account#

POST/creditor_bank_accounts/{creditor_bank_account_id}/actions/disable

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.

Path Parameters

Name	Type	Description
`creditor_bank_account_id`required	string	The creditor bank account id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.creditor_bank_accounts.disable("BA123")

client.creditor_bank_accounts.disable("BA123")

const creditorBankAccountResponse = await client.creditorBankAccounts.disable("BA123");

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

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

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

var creditorBankAccountResponse = await client.CreditorBankAccounts.DisableAsync("BA0123");

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "id": "BA123",
    "created_at": "2014-05-27T12:43:17.000Z",
    "account_holder_name": "Acme",
    "account_number_ending": "11",
    "account_type": null,
    "country_code": "GB",
    "currency": "GBP",
    "bank_name": "BARCLAYS BANK PLC",
    "enabled": false,
    "links": {
      "creditor": "CR123"
    },
    "verification_status": "pending"
  }
}

Response 200

Action completed successfully

creditor_bank_accountsobject

12 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

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

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

creditorstring

ID of the creditor that owns this bank account.

verification_statusstring

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

pendingin_reviewsuccessfulcould_not_verify

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