Bank Accounts API Overview

Use the Bank Accounts API to retrieve information about the bank accounts linked to a Square account. You must first link a bank account to a Square account in the Seller Dashboard. You can then use the following endpoints to retrieve the bank account information:

  • GetBankAccount - Retrieves information about a specific bank account linked to a Square account.
  • ListBankAccounts - Retrieves information about all bank accounts linked to a Square account.
  • GetBankAccountByBV1ID - This endpoint is provided only if you currently use the V1 Bank Accounts API. If you have a V1 bank account ID, you can use this endpoint to retrieve bank account information.

These APIs return bank account information as an object of the BankAccount type. The bank account information always includes the primary_bank_identification_number field and optionally the secondary_bank_identification_number field. The values for these fields depend on the country of the bank as shown:

Country of the bankISO country codeprimary_bank_identification_number fieldsecondary_bank_identification_number field
United StatesUSRouting numberN/A
JapanJPBank codeBranch code
United KingdomGBSort codeN/A
CanadaCAInstitution numberTransit number
AustraliaAUBSB codeN/A
SEPA countriesCountry code of the BICSwift BICN/A

Single Euro Payments Area (SEPA) countries include Austria, Belgium, Bulgaria, Cyprus, Croatia, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Monaco, Netherlands, Norway, Poland, Portugal, Romania, Slovenia, Slovakia, Spain and Sweden, Switzerland, United Kingdom (if linked using an IBAN).

Link to section

Link a bank account

The Bank Accounts API supports only retrieving information about the linked bank accounts. You can link a bank account to a Square account in the Seller Dashboard. To link an existing bank account to a Square account, you need the following information:

  • The bank account number.
  • The type of the account (such as checking or saving).
  • The name of the person who holds the bank account.
  • The primary bank identification number (in the United States, this is the routing number of the bank).

Bank accounts cannot receive deposits until Square completes a verification process on the bank account. Square performs this verification automatically when you link a bank account.

The verification process varies by country but the entire process usually takes a few minutes. In some cases, it can take up to 4 business days. As part of the verification process, Square credits and debits a small amount (for example, $0.01 USD) resulting in no change in your balance. Be sure you have a positive balance in your bank account before attempting to link it to Square to ensure that the account can be verified.

After Square verifies a bank account, the status field on the BankAccount object is set to VERIFIED. Square can then deposit funds to the linked bank.

Link to section

Requirements and limitations

The following apply when using the Bank Accounts API:

  • The country of the bank account must match the country of the associated account.
  • Applications using OAuth must have BANK_ACCOUNTS_READ permission to retrieve bank account information linked to a Square account.
Link to section

Retrieve a bank account by ID

You can retrieve information about a linked bank account using the GetBankAccount endpoint. In the request, you provide the following information:

  • The ID of the BankAccount object in the endpoint URL.
  • The access token of the Square seller in the Authorization header.

The following is an example request:

Get bank account

The following is an example response of the bank account in the United States:

Note

A BankAccount version can change for a number of reasons. First, the version is assigned when the BankAccount object is created (through the Seller Dashboard). The version then changes after Square verifies it. Later, the BankAccount version can change if Square disables the account. For example, if the external bank account is closed with the bank, then any money transfer fail. If the money transfer fails, Square sets the BankAccount status to disabled. After Square enables the account, the BankAccount object gets yet another version.

The BankAccount version is primarily useful when processing webhook events. For example, your application might process webhook events in batches. In this case, when there are multiple notifications of the same BankAccount object, your application can use the BankAccount object version (included in the event data) to determine the latest event.

For more information about bank account fields, see BankAccount.

Link to section

Retrieve all bank accounts linked to a Square account

If you don't have the bank account ID or you want to get a list of all the bank accounts linked to a Square account, you can use the ListBankAccounts endpoint. The endpoint returns information about all the bank accounts linked to a Square account, identified by access token in the Authorization header.

List bank accounts

The following is a sample response:

For more information about bank account fields, see BankAccount. You can also view only the bank accounts linked to a specific location using the location_id parameter. The following is an example of filtering by location_id:

List bank accounts

The API can return information for up to 1000 bank accounts in each response. If the result is truncated, the response includes a cursor that you can use in the next request to fetch the next set of bank accounts. You can also optionally include the limit parameter to specify the maximum number of bank accounts to return in a response. The following example request includes the limit parameter and the cursor in the endpoint URL:

List bank accounts

For more information, see Pagination.

Link to section

Retrieve a bank account by using an ID issued by the V1 Bank Accounts API

While transitioning from the deprecated V1 RetrieveBankAccount endpoint, you can retrieve information about a linked bank account using the GetBankAccountByBV1Id endpoint. In response, the API returns bank account information that also includes a Square API bank account ID. You can then use this ID for future references.

Note

This is a transitional endpoint that will be deprecated when the V1 Settlements API is deprecated.

In the request, you provide the following information:

  • The V1 bank account id in the endpoint URL.
  • The access token of the Square seller in the Authorization header.

The following is an example request:

Get bank account by v1Id

The following is an example response:

Link to section

Available webhooks

The Bank Accounts API supports the following set of webhooks:

EventPermissionDescription
bank_account.disabledBANK_ACCOUNTS_READPublished when Square sets the status of a bank account to DISABLED.
bank_account.verifiedBANK_ACCOUNTS_READPublished when Square sets the status of a bank account to VERIFIED.
bank_account.createdBANK_ACCOUNTS_READPublished when you link a seller's or buyer's bank account to a Square account. Square sets the initial status to VERIFICATION_IN_PROGRESS and publishes the event.

You can subscribe to these webhooks events to get notified when there are changes to a BankAccount. For a list of supported webhooks, see V2 Webhook Events Reference. For more information about using webhooks, see Square Webhooks Overview.