Migrate from the Connect v1 BankAccounts API

The following information helps you migrate from the Connect v1 BankAccounts API code to the correct Square API counterparts. For general guidance about the differences between Connect v1 and Square APIs, see the Connect v1 Migration guide.

Link to section

Migration overview

The Connect v1 BankAccounts API lets you view external linked bank accounts.

Link to section

Important dates

  • Deprecation: 2020-02-26
  • Retirement: 2021-02-26
Link to section

If you need help

If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section

New features in the Square BankAccounts API

The Square BankAccounts API provides all the functionality of the Connect v1 BankAccounts API and adds these features:

  • Pagination. The BankAccounts API reporting endpoints provide pagination.
  • Webhooks. Square Webhooks provide notifications when a bank account is created, verified, or disabled.
Link to section

Get a v1 BankAccount using the Square BankAccounts API

You can use a v1 bank account ID to retrieve the Square API equivalent BankAccount object. Call the Square API GetBankAccountByV1Id endpoint.

GET /v2/bank-accounts/by-v1-id/{v1_bank_account_id}
Link to section


Square BankAccounts API endpoints replace the v1 BankAccounts endpoints in v1 BankAccounts API.

You must update the code that relies on the following endpoints to avoid breaking when the v1 BankAccounts API retires:

v1 endpointSquare replacementUsage
ListBankAccountsListBankAccountsGets a list of BankAccount objects.
RetrieveBankAccountGetBankAccountGets a single BankAccount.
N/AGetBankAccountByV1IdGets a single v1 BankAccount by ID.


When you use the Connect v1 API to get a list of bank accounts, you set a location ID in the URL path. With the Square API, you specify the location ID by setting the ID as a query parameter of the request:

Connect v1 API

GET /v1/{location_id}/bank-accounts

Square API

GET /v2/bank-accounts?location_id={location_id}
Link to section

Field Mapping

All fields in the v1 BankAccount object are available in the Square BankAccount object. As a result, most code only needs to update the endpoint reference and field names to work properly.

Link to section

v1 BankAccount

The Square API BankAccount object contains all the fields of the v1 object, but they are mapped to new names:

v1 fieldSquare fieldNotes
routing_numbersecondary_bank_identification_numberThe v1 routing_number combined both bank ID numbers in Canada and Japan.
merchant_idlocation_idThe ID of the Location of the seller associated with the bank account.
Link to section

Bank ID numbers

The primary_bank_identification_number and secondary_bank_identification_number correspond to different bank account fields according to country.

Country Primary bank ID numberSecondary bank ID number
Australia (AU)BSB code
Canada (CA)Institution numberTransit number
Japan (JP)Bank codeBranch code
United Kingdom (GB)Sort code
United States (US)Routing number