Set up the QuickBooks Online Bank Feeds integration

Set up our integration with QuickBooks Online Bank Feeds.

Set up the QuickBooks Online Bank Feeds integration to let your SMB users connect bank accounts from your application to QuickBooks Online (QBO).

Prerequisites

Before setting up the integration, make sure that:

Enable the QBO Bank Feeds integration

In the Codat Portal:

  1. Click Settings > Integrations > Bank feeds.
  2. Click the toggle next to QuickBooks Online Bank Feeds to set the integration to Enabled.

You can also enable the integration directly from its Integration settings page.

Add a custom callout to the Link Site

You can add a custom callout to the QBO Bank Feeds Link site. This can provide additional guidance to your users when they're connecting their bank accounts to QBO.

In the Codat Portal:

  1. Click Settings > Integrations > Bank feeds
  2. Click Manage next to QuickBooks Online Bank Feeds.
  3. Enter text in the Callout title and Callout body boxes (maximum 50 and 150 characters respectively). Only plain text is supported.
  4. Click Save.

The callout is displayed at the bottom of the QBO Bank Feeds Link site. For example:

QBO Bank Feeds Link site showing custom callout text above the "Get credentials" button.QBO Bank Feeds Link site showing custom callout text above the "Get credentials" button.

Add a "Connect bank feeds" button to your application

Add functionality—for example, a button or link—to your application that lets your users connect their bank accounts to QBO for the purposes of viewing bank feeds. Use an appropriate UI label, such as Connect account to QuickBooks.

See the next procedure for details on the functionality to provide.

Create a Company and data connection

  1. When an SMB customer clicks the button or link you added, create a Company for them using the Create company endpoint:

    POST https://api.codat.io/companies
    

    Request body:

    {
      "name": "COMPANY_NAME"
    }
    

    The endpoint returns a JSON response containing the company id and the redirect URL.

  2. Using the POST /connections endpoint, create a data connection that specifies one or more bank accounts to make available to the SMB customer to connect to QBO.

    POST https://api.codat.io/companies/COMPANY_ID/connections
    

    In the request body specify hcws as the platformKey and a list of bankAccounts in a connectionInfo object. All fields in the example below are required.

    The sortCode in the bank account body refers to the bank code. Regions other than the UK use different terms for the sort code.

    {
        "platformKey": "hcws",
        "connectionInfo": {
            "bankAccounts": [
                {
                    "id": "acc-001",
                    "accountName": "account-081",
                    "sortCode": "123456",
                    "accountType": "checking",                   
                    "accountNumber": "12345670",
                    "currency": "USD",
                    "balance": 5300
                },
                {
                    "id": "acc-002",
                    "accountName": "account-095",
                    "sortCode": "123456",
                    "accountType": "checking",                   
                    "accountNumber": "12345671",
                    "currency": "USD",
                    "balance": 7300
                }
            ]
        }
    }
    

    The endpoint returns a 200 response and a dataConnection object, in PendingAuth status, containing:

    • A linkUrl property.
    • A connectionInfo property containing a list of bank accounts.
    {
        "id": "7baba7cc-4ae0-48fd-a617-98d55a6fc008",
        "integrationId": "6b113e06-e818-45d7-977b-8e6bb3d01269",
        "sourceId": "56e6575a-3f1f-4918-b009-f7535555f0d6",
        "platformName": "QuickBooks Online Bank Feeds",
        "linkUrl": "https://link-api.codat.io/companies/COMPANY_ID/connections/CONNECTION_ID/start?otp=742871",
        "status": "PendingAuth",
        "created": "2022-09-01T10:21:57.0807447Z",
        "sourceType": "BankFeed",
        "connectionInfo": {
            "bankAccounts": [
                {
                    "id": "acc-001",
                    "accountName": "account-081",
                    "accountType": "checking",
                    "accountNumber": "12345670",                   
                    "currency": "USD",
                    "balance": 5300,
                    "modifiedDate": "2022-09-01T10:21:57.3191704Z"
                },
                {
                    "id": "acc-002",
                    "accountName": "account-095",
                    "accountType": "checking",
                    "accountNumber": "12345671",                   
                    "currency": "USD",
                    "balance": 7300,
                    "modifiedDate": "2022-09-01T10:21:57.3191705Z"
                }
            ]
        }
    }
    
  3. Redirect the SMB customer to the linkUrl returned in the response.

  4. Using Link and QBO, the SMB customer connects their chosen bank accounts to QuickBooks Online.

🚧

Do not hardcode the linkUrl into your application code. It is unique to the originating customer and must not be shared with other users.

Retrieve data connections

Retrieve the data connections you created in the preceding task to view the following information:

  • Available bank accounts for the SMB customer to connect to QBO.
  • The connection status of the available bank accounts (either connected or pending).
  • The number of connected bank accounts for a particular data connection.

To view this information, use the Get connections and Get a single connection endpoints.

Add bank accounts to an existing data connection

It's possible to add new bank accounts to an existing data connection that already has one or more bank accounts connected to it. This is achieved by sending a request to the PATCH /connections/CONNECTION_ID endpoint, specifying the bank account properties you want to update in the request body.

A new linkURL is returned in the response body.

Your SMB Customer then has to take the following steps to connect the new bank account:

  1. Use the linkURL to open the QBO Bank Feeds Link site.
  2. Generate new credentials.
  3. In QBO, go to Transactions.
  4. Click Link Account and connect the new bank account with their new credentials (the same process as for any bank account).
    1. Navigate to one of the previously linked bank accounts.
    2. Select Edit sign in info.
    3. Enter their new credentials

All bank accounts are now connected and historic data remains intact.