Teller Connect Integration Guide

Get access to your user's financial accounts with just a few lines of code. Connect is a Teller-hosted authorization flow that works seamlessly across browsers & devices to make gaining access to your user's accounts as easy as possible.

The high-level flow:

Connect is installed in your application via the use of our JavaScript client library; you simply include our CDN-hosted script, pass it some basic configuration and tell it on which actions it should launch.

The integration process has 4 core steps:

  1. Include the client library
  2. Initialize & configure the client library
  3. Handle a successful enrollment
  4. Hook user actions to start Teller Connect

A complete integration may look similar to the following:

<html>
  <head></head>
  <body>
    <!-- When element is clicked, Teller Connect will open -->
    <button id="teller-connect">Connect to your bank</button>

    <!-- Body of your page... -->

    <!-- Part 1. Include the client library -->
    <script src="https://cdn.teller.io/connect/connect.js"></script>
    <script>
      // Part 2. Initialize & configure the client library
      document.addEventListener("DOMContentLoaded", function() {
        var tellerConnect = TellerConnect.setup({
          applicationId: "Your application ID e.g app_xxxxxx",
          onInit: function() {
            console.log("Teller Connect has initialized");
          },
          // Part 3. Handle a successful enrollment's accessToken
          onSuccess: function(enrollment) {
            console.log("User enrolled successfully", enrollment.accessToken);
          },
          onExit: function() {
            console.log("User closed Teller Connect");
          }
        });

        // Part 4. Hook user actions to start Teller Connect
        var el = document.getElementById("teller-connect");
        el.addEventListener("click", function() {
          tellerConnect.open();
        });
      });
    </script>
  </body>
</html>

Part 1. Include the client library

Start by including the Teller Connect script at the base of the in the HTML of the page where you wish to give user's the ability to authorize access to an institution.

<script src="https://cdn.teller.io/connect/connect.js">

We recommend including the script at the base of the body element so that it doesn't block rendering of your page; but it can run anywhere you choose to include it. However, the async attribute should be avoided for now as the inline code relies on the library being available; and the defer attribute should also not be used as we cannot rely on the DOMContentLoaded event firing after the library has been executed (currently some browsers will fire it before).

Part 2. Initialize & configure the client library

The next step, as detailed in the above example, is to attach a DOMContentLoaded event listener and within that run TellerConnect.setup, passing it a single JavaScript object representing the following configuration options:

Setup Options

applicationId (string, required)

A string representing your Application ID, which can be found inside the Teller Dashboard. Simply pass the value here, then we'll know who you are.

onInit (function, optional)

An optional no-arguments callback, this option accepts a function which is called when the client library has finished initializing. In most scenarios this will go unused but in the special case where you wish to execute some code after the library has been executed, then this is the place to put it.

onSuccess (function, required)

A required callback, this function accepts one parameter: the Teller Connect Enrollment object. This callback is called when your user has successfully completed enrollment with their selected institution. See Part 3. for more information.

onExit (function, optional)

An optional no-arguments callback, this option accepts a function which is called when your user leaves the Teller Connect flow by closing it. This callback only fires when a successful enrollment did not occur and can be used to execute code which reacts to a user leaving the flow.

Part 3. Handle a successful enrollment

When a user completes the enrollment flow successfully, the library will call the onEnrollment callback function that you passed to it during setup (see Part 2).

When called it is passed a single argument, the Enrollment object:

{
  // An access token you can use together with your
  // client certificate to access this user's accounts.
  "accessToken": "fdF5FXnVc",
  "user": {
    // A user ID you can use to later add more enrollments to the same user
    "id": "usr_xxx"
  },
  "enrollment": {
    // The enrollment ID used to initialise Connect in update mode, i.e. if it becomes disconnected.
    "id": "enr_xxx",
    "institution": {
      "name": "Example Bank"
    }
  }
}

The crucial part of this payload is the accessToken value; which you must store securely as it is the token that is required for future access to the user's accounts via the Teller API.

Part 4. Hook user actions to start Teller Connect

Now that we have the returned handler from TellerConnect.setup; we can bind user events to call its .open() function which accepts no arguments.

For example, the following code binds a function to the click event handler of a button with the ID #teller-connect, so that when clicked tellerConnect.open() is executed.

<button class="teller-connect">
  <script>
    var tellerConnect = TellerConnect.setup(options);
    var el = document.getElementById("teller-connect");
    el.addEventListener("click", function() {
      tellerConnect.open();
    });
  </script>
</button>

Teller Connect does not have a preference as to how you bind the opening event, it may be done on any event, provided that the handler's open function is called.