CONNECT V1 MIGRATIONS

Migrate from Connect v1 BankAccounts API

BankAccounts API

Migration overview
Permalink Get a link to this section

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

Important dates
Permalink Get a link to this section

  • Deprecation: 2020-02-26

  • Retirement: 2021-02-26

If you need help
Permalink Get a link to this section

If you need help migrating to Square APIs or need more time to complete your migration, please contact Developer Support, join our Slack, or reach out to your Square Account Manager.

New features in Square BankAccounts API
Permalink Get a link to this section

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

  • Pagination — The Square BankAccounts API reporting endpoints provide pagination.

  • Webhooks — Square v2 Webhooks (beta) provide notifications when a bank account is created, verified, or disabled.

Getting a v1 BankAccount using the Square BankAccounts API
Permalink Get a link to this section

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}

Endpoints
Permalink Get a link to this section

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

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

v1 endpoint
Square replacement
Usage
ListBankAccounts ListBankAccountsGets a list of BankAccount objects
RetrieveBankAccount GetBankAccountGets a single BankAccount
N/A GetBankAccountByV1IdGets a single v1 BankAccount by ID

Note

When you used 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}

Field Mapping
Permalink Get a link to this section

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

V1 BankAccount
Permalink Get a link to this section

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

v1 fieldSquare fieldNotes
routing_numberprimary_bank_identification_number
routing_numbersecondary_bank_identification_numberThe v1 routing_number combined both bank ID numbers in Canada and Japan.
typeaccount_type
currency_codecurrency
nameholder_name
merchant_idlocation_idThe id of the Location of the seller associated with the bank account

Bank ID numbers
Permalink Get a link to this section

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