Xero Bank Feeds

Back to Bank Feeds

Setting up a Xero 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. Join Xero's Financial Services Partnership program to gain access to the Xero Bank Feeds API.
2. Onboard your customers to Xero 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.

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

Set up your Xero Developer App

Follow our Xero Guide to get your Xero Developer App set up.

Join Xero's Financial Services Partnership Program

Submit a Xero Financial Services Partnership Program application. Joining this program will allow your developer app to be provisioned with the permissions required to access Xero's Bank Feeds API's. It will go to one of Xero's Financial Services Partner Managers who will take you through the process. If you are happy with the Xero default agreement, then it won't take long for you to get access.

To tell whether a connection has the required permissions, use the Fetch a Connection API and check the unavailable_objects field. If this field value is a list that contains the two objects bank_feed_accounts and bank_feed_transactions, the connection does not have the required permissions. If it is empty, it does.

Connect to the Accounting System

Embed Rutter Link into your application and walk through an end to end business authentication flow in order to create a new Connection. This Connection represents the business accounting system and contains an access_token used to read and write data for that instance.

Implementation Steps

Step 1: Create a Bank Feed Account

Use Rutter’s POST /bank_feeds/accounts API endpoint to set up Bank Feeds within Xero. No accountant action is required within Xero, only your interaction with Rutter's API.

• If you would like to create a Bank Feed for an existing GL account, you can find the id of the account through the GET /accounts API endpoint, and pass it into the account_id input field.
• If you would like to create a new Xero GL account and a Bank Feed at the same time, you can omit the account_id field. The newly created Xero GL account_id will be in the response.

Bank Feed Account Creation Rules

1. Only one Bank Feed Account can be created per GL account.
2. If you provide an account_id field, you must ensure the type of this GL account matches the bank_account_type field in your request body.

1
{
2
    "bank_feed_account": {
3
      "account_id": "00000000-0000-0000-0000-000000000000",
4
      "internal_bank_account_id": "0674101002388",
5
      "bank_account_type": "bank",
6
      "currency_code": "USD",
7
      "name": "Regan's Bank Account",
8
    }
9
}

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": null,
10
      "bank_account_type": "bank",
11
      "feed_status": "active",
12
      "available_balance": null,
13
      "available_credit": null,
14
      "bank_account_number": "182237382",
15
      "credit_limit": null,
16
      "currency_code": "USD",
17
      "current_balance": null,
18
      "finance_charges": null,
19
      "last_statement_balance": null,
20
      "line_of_business": null
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": null,
27
      "last_synced_at": "2023-01-02T02:34:56.000Z",
28
      // ...
29
    }
30
  }

Step 2: Account Mapping

Rutter offers pre-built UI components to assist your customers in mapping their bank or card accounts to their GL accounts.

Use the POST /accounting/bank_feeds/accounts/mapping_link API endpoint to generate a secure link that provides your customers with an intuitive interface for selecting an account, mapping it back to a general ledger, and configuring a date range to pull transactions from.

1
{
2
  "bank_feed_account_mapping_link": {
3
    "expires_at": "2023-01-10T00:00:00.000Z",
4
    "url": "https://link.rutterapi.com/bank_feeds_link?token=00000000-0000-0000-0000-000000000000"
5

6
  }
7
}

The generated link will redirect your customers to Rutter's hosted UI where they can review and manage their linked and unlinked accounts, and create new GL accounts as needed. Once completed, they'll be redirected back to your application with the mapping details. Each link is valid for 10 minutes.

Step 3: Sync Transaction Data

Transactions can start being synced as soon as the bank feed account is created. 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. The transaction_ready status indicates when Rutter is able to accept new transactions for a bank feed account. For Xero, this will always be true after a bank feed account has successfully been created.

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
          "transaction_type": "debit",
13
          "debit_credit_memo": "DEBIT",
14
          "payee": "Office Depot"
15
        }
16
      ]
17
    }
18
  }

• If the Bank Feed Transaction input is valid and the call succeeds, transactions will be synced to the accounting system. The end user can see the synced transactions 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: true, meaning the transactions have been ingested by Xero (thus will appear in the accounting instance).

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

Deleting Bank Feed Accounts

If a Xero user would like their Bank Feed Account connection to be deleted, you can do so through Rutter's DELETE /bank_feeds/accounts API. It's not possible to recover a Bank Feed Account once it's been deleted.

What happens when you call the DELETE endpoint:

• Removes the bank feed account entity in Rutter
• Removes the "feed" in Xero (end user will no longer receive transaction updates)
• Does NOT remove the GL account linked to the bank feed in Xero

Connection Deletion Behavior

When you delete a Rutter connection, bank feed accounts behave as follows:

Bank feed accounts that have been created in Xero: These are accounts where either account_id or bank_account_number have been set (meaning the account has been ingested by Xero).

• Will continue to exist in Xero after the connection is deleted
• Will no longer receive transaction updates (feed becomes inactive)
• If you reconnect to the same Xero instance, these accounts will be automatically synced back to Rutter and available under GET /bank_feeds/accounts

Bank feed accounts that have NOT been created in Xero: These are accounts where neither account_id nor bank_account_number have been set (meaning the account hasn't been linked to a GL account yet):

• Only exist in Rutter and will be automatically deleted when the connection is deleted
• Will not be automatically recreated if the connection is deleted and later reconnected

There are no negative consequences for not deleting bank feed accounts before deleting a connection. The only result is having unused bank feed accounts in your end user's Xero instance that will no longer receive updates.

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.
4. current_balance field is required
5. debit_credit_memo field is required

Reconciliation with the Accounting System

Your user will now be able to see the transactions you have synced within the accounting system and be able to perform reconciliation with these transactions.

They will be able to see the transactions by going to "Accounting" > "Bank Accounts", selecting the account you have synced transactions to, and clicking on the "Bank Statements" tab.