Sage Bank Feeds

Back to Bank Feeds

Setting up a Sage Bank Feeds Workflow with Rutter

Introduction

Rutter API enables you to get listed as a financial institution in the Sage ecosystem. This allows your customers to sync bank or credit card transactions from the accounts they hold with you into their Sage systems, enabling easy, automated reconciliaton and financial automation.

With a single implementation, you gain access to the following Sage platforms:

• Sage Intacct
• Sage Business Cloud

No additional development work is required to support each individual Sage product.

The workflow involves three main steps:

1. Get listed as a financial institution within Sage's ecosystem.
2. Onboard your customers within their Sage products to establish a connection between their bank or card account and their Sage instance.
3. Continuously sync transaction data into Rutter's systems to enable your customers to pull it into their Sage products.

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 Sage products

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 Sage's "Connect Your Bank" flow.

To get listed, you will need to follow the steps below:

1. Set up your Sage Bank Feeds Configuration. Go to Rutter Dashboard > "Platforms" tab, then select "Bank Feeds" and click "Configure" for Sage.

2. Input your information into the “Bank Feeds Configuration” form.

• Name: Your organization's name that will appear in Sage's "Connect Your Bank" page. Include "(powered by Rutter)" at the end (Sage requirement). Rutter will automatically append this to your name if not included.

• Company Logo URL: Link to your logo for white-labeling the Rutter-powered authentication flow in Sage's setup process.

• Company Country Code: Your company's region.

• Redirect URL: 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). Read on for more instructions about how to implement this page.

After filling out the form, contact the Rutter Customer Success Team to continue onboarding. We will reach out to our Sage partner to complete your onboarding.

Your financial institution will start in a beta status, which means your customers will need to provide an access code to connect to your bank. You will be able to move out of beta after completing testing for your integration.

Implementation Steps

Connect to the Accounting System

First, your customers must successfully establish a Rutter Connection to their Sage instance.

Embed Rutter Link into your application and direct your customers through the flow in order to create a new Connection. This Connection contains an access_token used to read and write data for that instance.

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 > Sage Bank Feeds. Then click "Configure".

Please note: this webpage must not have a Cross-Origin-Opener-Policy header set, as this blocks Sage's ability to maintain state during the login flow.

Step 2: Rutter Redirects to Your Login URL

When your customer attempts to connect within their Sage Intacct or Sage Business Cloud instance, Rutter will redirect them to the login URL you provided (e.g., my-website.com/login).

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/sage_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 Sage 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.

Please note: Sage needs to maintain state during the login flow. For this reason, your login flow must use the same domain throughout the process (i.e., do not redirect users from one domain to another during the flow), and must not have a Cross-Origin-Opener-Policy header set.

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.

Populate Bank Feed Data

After the customer successfully logs in, follow these steps.

Step 1: Retrieve the Rutter Sage Connection

In order to use Sage Bank Feeds, your customer must have already gone through the Rutter Link flow in your product (see above) and created a connection.

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

Use the access token for the correct connection to make the API requests in the next several steps.

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 Sage Bank Feeds 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: Enable the Bank Feed Authentication Flow

After completing the steps above to create bank accounts, 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/sage_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 Sage 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 their Sage product (Sage Intacct or Sage Business Cloud).

Step 4: Sync Transaction Data

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

To check the authentication status of a Bank Feed Account, use GET /bank_feeds/accounts API. Once the transaction_ready field is true, transactions can start being synced for this account.

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
      "feed_status": "active",      
10
      // ...
11
    }
12
  }

To sync transaction data for a Bank Feed Account, use the POST /bank_feeds/transactions API.

When users link their account in Sage, they will be asked to choose the start date for the Bank Feed's transaction history. This will be reflected in the transaction_start_date field of the Bank Feed Account once they have completed this process. You should sync transactions from that date until the present.

After the initial set of transactions are sent, you should sync new transactions at least once every 24 hours. Only posted transactions should be synced.

1
{
2
    "bank_feed_transactions": {
3
      "bank_feed_account_id": "00000000-0000-0000-0000-000000000000",
4
      "transactions": [
5
        {
6
          "transaction_id": "ACRAF23DB3C4",
7
          "posted_at": "2023-02-02T02:34:56.000Z",
8
          "amount": -300,
9
          "description": "Office supplies",
10
          "transaction_type": "debit",
11
          "payee": "Office Depot"
12
        }
13
      ]
14
    }
15
  }

• If no transactions have been synced, use the transaction_start_date field to determine the date when transactions starts syncing from. You can fetch synced transactions with GET /bank_feeds/transactions API.

• If the Bank Feed Transaction input is valid, the response will include a job ID which can be used to check the status of the POST request using Fetch a Job API. Store this job ID for reference. You cannot post another batch until the previous job completes.

• If the job completes successfully, transactions have synced into the accounting system. You can now post the next batch, starting from the last transaction date in the previous batch.

• If the job fails, the transactions have not synced into the accounting system. You should retry the POST request after fixing the error described in the job response.

Transaction Syncing Rules

1. You can only submit transactions for one Bank Feed Account at a time.
2. You can only submit one batch of transactions at a time. You must wait for the previous batch to complete before submitting another batch.
3. You can only submit transactions for a Bank Feed Account that has been authenticated and set up through the Sage product (i.e. the feed_status field is active).
4. Only posted transactions should be submitted.
5. Transactions must be in chronological order.
6. You must provide at least one transaction per sync request, and at max 1000.
7. 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.