Bank Accounts API

Bank Accounts API

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 on the seller dashboard. You can then use the following endpoints to retrieve the bank account information:

  • GetBankAccount — Retrieve information of a specific bank account linked to a Square account.

  • ListBankAccounts — Retrieve information of all the 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 the 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 bank ISO Country Code primary_bank_identification_number field

secondary_bank_identification_number field

United States US Routing number n/a
Japan JP Bank code Branch code
United Kingdom GB Sort code n/a
Canada CA Institution number Transit number
Australia AU BSB code n/a

Linking a bank account
Permalink Get a link to this section

The Bank Accounts API supports only retrieving information about the linked bank accounts. You can link a bank account to a Square account on 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 (e.g. checking, saving)

  • The name of the person who holds the bank account

  • The primary bank identification number (in the US, 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 will credit and debit 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 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.

Requirements and limitations
Permalink Get a link to this section

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 the BANK_ACCOUNTS_READ permission to retrieve bank account information linked to a square account.

Retrieve a bank account by ID
Permalink Get a link to this section

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

  • ID of the BankAccount in the endpoint URL.

  • Access token of the Square seller in the Authorization header.

The following is an example request:

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
'https://connect.squareup.com/v2/bank-accounts/{{BANK_ACCOUNT_ID}}'

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

{
   "bank_account":{
      "id":"bact:cgvL1yv43VFjexample",
      "account_number_suffix":"526",
      "country":"US",
      "currency":"USD",
      "account_type":"CHECKING",
      "holder_name":"John Doe",
      "primary_bank_identification_number":"101211111",
      "location_id":"S8GWD5example",
      "status":"VERIFICATION_SUCCEEDED",
      "creditable":true,
      "debitable":true,
      "version":5,
      "bank_name":"Bank Name"           
   }
}

Note

A BankAccount version can change for a number of reasons. First, the version is assigned when the BankAccount is created (through the 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 would fail. If the money transfer fails, Square sets the BankAccount status to disabled). After Square enables the account, the BankAccount gets yet another version.

The Bank account 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 bank account object version (included in the event data) to determine the latest event.

For more information about bank account fields, see BankAccount.

Retrieve all bank accounts linked to a Square account
Permalink Get a link to this section

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

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareup.com/v2/bank-accounts'

The following is a sample response:

{
   "bank_accounts":[
      {
         "id":"bact:cgvL1yv43VFjexample",
         "account_number_suffix":"526",
         "country":"US",
         "currency":"USD",
         "account_type":"CHECKING",
         "holder_name":"John Doe",
         "primary_bank_identification_number":"101211111",
         "location_id":"S8GWD5example",
         "status":"VERIFICATION_SUCCEEDED",
         "creditable":true,
         "debitable":true,
         "version":5,.
         "bank_name":"Bank Name"
      }
   ]
}

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:

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareup.com/v2/bank-accounts?location_id={{LOCATION_ID}}'

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 both the limit and the cursor in the endpoint URL.

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareup.com/v2/bank-accounts?limit=100&cursor={{CURSOR_STRING}}'

For more information, see Pagination.

Retrieve a bank account by using an ID issued by the V1 Bank Accounts API
Permalink Get a link to this section

While transitioning from the deprecated V1 Retrieve bank account endpoint, you can retrieve information about a linked bank account using the GetBankAccountByBV1Id endpoint. In response, the API returns bank account information that will also include 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.

  • Access token of the Square seller in the Authorization header.

The following is an example request:

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
'https://connect.squareup.com/v2/bank-accounts/by-v1-id/{{V1_BANK_ACCOUNT_ID}}'

The following is an example response:

{
   "bank_account":{
      "id":"bact:cgvL1yv43VFjexample",
      "account_number_suffix":"526",
      "country":"US",
      "currency":"USD",
      "account_type":"CHECKING",
      "holder_name":"John Doe",
      "primary_bank_identification_number":"101211111",
      "location_id":"S8GWD5example",
      "status":"VERIFICATION_SUCCEEDED",
      "creditable":true,
      "debitable":true,
      "version":5,
      "bank_name":"Bank Name"
   }
}

Available webhooks
Permalink Get a link to this section

The BankAccounts API supports a set of webhooks. You can subscribe to these webhooks events to get notified when there are changes to a BankAccount. For a list of supported webhooks, see Subscribe to Webhook Events.