Intuit Bank Feeds (QuickBooks)

Back to Bank Feeds

Setting up an Intuit Bank Feeds Workflow with Rutter

Introduction

Rutter API enables you to support setting up bank feeds for your customers' accounting instances. This allows you to sync bank transaction data into the instance to enable reconciliation for an accountant which ensures the accuracy and validity of your customers' books.

1. Get listed as a bank within Intuit's QuickBooks Online.
2. Onboard your customers to Intuit Bank Feeds to establish a connection between their bank account and their accounting instance.
3. Continuously sync transaction data into the accounting instance to enable reconciliation.

Our Intuit Bank Feeds API supports QuickBooks Online.

End User Setup Process

Platform Setup

Data Sync Configuration

Make sure to include these Rutter Objects in your Data Sync Configuration through the Rutter dashboard.

• Bank Feed Account
• Bank Feed Transaction

Get listed as a bank within QuickBooks Online

When your customer wants to set up a Bank Feed between their accounting instance and their bank account, they will need to select you from a list of banks within QuickBooks' "Link Account" flow.

To get listed, please contact your Rutter customer support representative.

Prerequisites

In order to proceed, you will need to create two Rutter organizations, one for production and one for staging/testing. This allows you to better separate those environments, as well as allowing Intuit to create separate staging and production banks for your use. Your Rutter staging environment will connect to your Intuit test bank, and your production environment will connect to your official listing with Intuit.

To set up your second Rutter instance, just head to Rutter's Sign up page. You'll need to use a different email than on your primary Rutter organization. For example, if you used john.doe@rutterapi.com to sign up for your primary Rutter organization, you could create a new staging organization using the email john.doe+staging@rutterapi.com.

Once done, reach out to your Rutter Success Manager to guide you through the rest of the process.

Implementation Steps

Redirect Customers to Your Login Flow

Step 1: Provide a Redirect URL to Rutter

You need to supply Rutter with a redirect URL that points to a user-facing login page on your platform (e.g., my-website.com/login). This URL should be a webpage, not an API endpoint.

To supply Rutter with this URL, in your Rutter Dashboard, head to Platforms > Bank Feeds > Intuit Bank Feeds. Then click “Configure”.

Step 2: Rutter Redirects to Your Login URL

When your customer attempts to connect within QuickBooks Online (QBO), Rutter will redirect them to the login URL you provided (e.g., my-website.com/login). This will appear as a pop-up screen within the QBO interface.

Step 3: Handling the Redirect URI

When Rutter redirects to the login URL you provide, Rutter will append a redirect_uri parameter to the login URL. After your customer successfully logs in, you will need to redirect to this URL.

For example, if your login URL is my-website.com/login , Rutter would redirect your user to that URL to log in, and append query parameters to it like this: my-website.com/login?challenge=f0208784-584e-4419-be3e-f34a743a9904&redirect_uri=https://link.rutterapi.com/ibf_redirect?challenge=f0208784-584e-4419-be3e-f34a743a9904

Appended to Rutter’s redirect_uri is a challenge parameter. You do not need to store or use the challenge parameter beyond passing it back to Rutter as part of the redirect URI. The challenge parameter uniquely identifies the connection between your customer's QBO account and Rutter. The redirect URI and associated challenge expire after 10 minutes.

For additional security, we recommend you implement validation on your side to ensure the redirect_uri belongs to the domain link.rutterapi.com.

Alternatively, for a more secure option, you can use the redirect_uri returned as part of the POST /bank_feeds/otp response (see step Enable the Bank Feed Authentication Flow below.) In this case you will need to temporarily store the challenge passed from the Rutter redirect, and append this to the redirect_uri as a query parameter along with the OTP when directing back to Rutter.

Step 4: Customer Login

Your customers will log in through your flow (hosted at, e.g. my-website.com/login), during which you can handle any two-factor authentication (2FA) or other security requirements. Rutter does not have visibility into, or requirements for, the specifics of your login flow. All that is needed is for you to redirect to the correct URL with the appropriate parameters after a successful login.

Link a Rutter Intuit Bank Feeds Connection to Your Customer’s QuickBooks Account

After the customer successfully logs in, follow these steps. These steps are identical to Rutter's Sage and Xero bank feeds flow. (The same flow applies for NetSuite bank feeds too, though NetSuite does not require OTP generation.)

Step 1: Create or Retrieve a Rutter IBF Connection

Create a new Intuit Bank Feeds connection (if one does not already exist for this customer) by calling our Create Connection API with this JSON body:

1
{
2
    "platform": "INTUIT_BANK_FEEDS"
3
}

You must track which IBF connections belong to which users on your end. For example, you might maintain a table that maps your customers to Rutter connection IDs:

• If a connection already exists, move to the next step.

Use the access token returned from the API to make the API requests in the next several steps.

1
{
2
  "connection": {
3
    "id": "00000000-0000-0000-0000-000000000000",
4
    "access_token": "00000000-0000-0000-0000-000000000000",
5
    "link_url": "https://link.rutterapi.com/connection/00000000-0000-0000-0000-000000000000",
6
    "name": "Example Connection"
7
  }
8
}

Step 2: Create Bank Feed Accounts

Use Rutter’s POST /bank_feeds/accounts API endpoint to supply the bank accounts your customer would like to set up with a Bank Feed. Your customer will be able to select any of the accounts you supply through this endpoint during the Intuit Bank Feed authentication flow.

1
{
2
    "bank_feed_account": {
3
      "account_id": "00000000-0000-0000-0000-000000000000",
4
      "internal_bank_account_id": "0674101002388",
5
      "parent_bank_feed_account_id": "00000000-0000-0000-0000-000000000000",
6
      "transaction_start_date": "2023-02-02T00:00:00.000Z",
7
      "bank_account_type": "bank",
8
      "currency_code": "USD",
9
      "name": "Regan's Bank Account",
10
      "available_balance": 1546.23,
11
      "bank_account_number": "182237382",
12
      "current_balance": 1833.21,
13
      "line_of_business": "small business",
14
      "routing_number": "123456789",
15
      "additional_fields": {
16
        "override_existing": true
17
      }
18
    }
19
}

1
{
2
    "bank_feed_account": {
3
      "id": "00000000-0000-0000-0000-000000000000",
4
      "account_id": "00000000-0000-0000-0000-000000000000",
5
      "internal_bank_account_id": "0674101002388",
6
      "parent_bank_feed_account_id": "00000000-0000-0000-0000-000000000000",
7
      "last_statement_date": null,
8
      "next_payment_date": null,
9
      "transaction_start_date": "2023-02-02T00:00:00.000Z",
10
      "bank_account_type": "bank",
11
      "feed_status": "inactive",
12
      "available_balance": 1546.23,
13
      "available_credit": null,
14
      "bank_account_number": "182237382",
15
      "credit_limit": null,
16
      "currency_code": "USD",
17
      "current_balance": 1833.21,
18
      "finance_charges": null,
19
      "last_statement_balance": null,
20
      "line_of_business": "small business",
21
      "minimum_payment_amount": null,
22
      "name": "Regan's Bank Account",
23
      "next_payment_amount": null,
24
      "past_due_amount": null,
25
      "purchases_apr": null,
26
      "routing_number": "123456789",
27
      "last_synced_at": "2023-01-02T02:34:56.000Z",
28
      // ...
29
    }
30
  }

Step 3: Sync Bank Feed Transaction Data

In order for you to start syncing transaction data for a Bank Feed Account, your customer must have authenticated and set up the Bank Feed through their Intuit product.

To check the authentication status of a Bank Feed Account, use GET /bank_feeds/accounts API, and check that "transaction_ready" is set to "true".

For Intuit, this will always be true as soon as the bank feed account is successfully created. However, having your code check for "transaction_ready": true before sending over transactions ensures cross-platform compatibility if you build out additional bank feed integrations with Rutter.

The "feed_status" field will be "inactive" until the user completes the authentication flow and Intuit has begun syncing transactions for this account from Rutter.

1
{
2
    "bank_feed_account": {
3
      "id": "00000000-0000-0000-0000-000000000000",
4
      "account_id": "00000000-0000-0000-0000-000000000000",
5
      "internal_bank_account_id": "0674101002388",
6
      "parent_bank_feed_account_id": "00000000-0000-0000-0000-000000000000",      
7
      "transaction_start_date": "2023-02-02T00:00:00.000Z",
8
      "bank_account_type": "bank",
9
      "transaction_ready": "true",
10
      "feed_status": "active",      
11
      // ...
12
    }
13
  }

To sync transaction data for a Bank Feed Account, use POST /bank_feeds/transactions API. We suggest syncing transactions in real time, once they've posted to the account. If current_balance is provided, the current_balance on the account will be updated. If not provided, it will not be updated automatically.

1
{
2
    "bank_feed_transactions": {
3
      "bank_feed_account_id": "00000000-0000-0000-0000-000000000000",
4
      "current_balance": 1234.56,
5
      "transactions": [
6
        {
7
          "transaction_id": "ACRAF23DB3C4",
8
          "posted_at": "2023-02-02T02:34:56.000Z",
9
          "transaction_date": "2023-02-02T02:34:56.000Z",
10
          "amount": -300,
11
          "description": "Office supplies",
12
          "memo": "Staples",
13
          "transaction_type": "debit",
14
          "debit_credit_memo": "DEBIT",
15
        }
16
      ]
17
    }
18
  }

• If the Bank Feed Transaction input is valid, transactions will be synced to the accounting system the next time the end user requests updated transactions for this account in QuickBooks by opening the bank account's feed page.

• If response_mode=async is specified in the request, the response will include a job ID which can be used to check the status of the POST request using Fetch a Job API. If the job completes successfully, your input was valid and the response will show transactions with platform_ingested: false, meaning the transactions have not yet been ingested by Intuit (thus will not yet appear in the accounting instance). You can check the platform_ingested status of the transactions through GET /bank_feeds/transactions to confirm whether the transactions have synced into the accounting instance or not. If a Bank Feed Account is feed_status: active, the last_synced_at corresponds with the last time Intuit synced transactions for this account.

If the job fails, you should retry the POST request after fixing the error described in the job response.

Step 4: Enable the Bank Feed Authentication Flow

After completing the steps above to create bank accounts and sync transaction data to them, finish redirecting to the Rutter-provided redirect URL. To authenticate the connection, you'll need to generate an OTP and append that to the redirect URL as an additional parameter. The redirect URL already includes a challenge ID as a query parameter. All you need to do is add one more query parameter with the OTP (&otp=OTP_GOES_HERE). For example:

1
https://link.rutterapi.com/ibf_redirect?challenge=f0208784-584e-4419-be3e-f34a743a9904&otp=123456789

The OTP should not be displayed to the user. It is passed back to Rutter so Rutter can link the correct user’s QBO account to the correct Rutter connection.

To generate the OTP, use Rutter’s POST /bank_feeds/otp API. This endpoint will also return a redirect_uri which can be used in place of the original redirect_uri passed from Rutter. Note that if the redirect_uri from the POST /bank_feeds_otp response is used, the challenge passed from Rutter will need to be appended as a query parameter.

1
{
2
    "bank_feed_otp": {
3
      "expires_at": "2023-01-10T00:00:00.000Z",
4
      "otp": "00000000-0000-0000-0000-000000000000"
5
    }
6
}

Once you redirect to Rutter, your customer will be able to finish linking their bank accounts within QuickBooks.

Transaction Syncing Rules

1. You must provide at least one transaction per sync request
2. Only posted transactions should be submitted.
3. Each transaction must have a unique identifier (transaction_id). The identifier for a transaction must never change. The same transaction identifier should not occur more than one time for a Bank Feed Account.