API Version

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>

You can find a working example of Teller Connect in our demo application here.

Part 1. Include the client library

Start by including the Teller Connect script 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

environment (string, optional)

The environment to use for enrolling the user's accounts. Valid values are "sandbox", "development" and "production". The "sandbox" enviroment never communicates with a real institution, it is used to create sandbox enrollments, accounts and tokens. The "development" environment is the same as "production" but is not billed and has a hard limit of 100 connected accounts.

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.

institution (string, optional)

An optional string representing the institution id. If set, Teller Connect will skip the institution picker and and load the first step for the corresponding institution.

selectAccount (string, optional)

An optional string which can be set to one of:

  • disabled - automatically connect all the supported financial accounts associated with this user's account at the institution (default)
  • single - the user will see a list of supported financial accounts and will need to select one to connect
  • multiple - the user will see a list of supported financial accounts and will need to select one or more to connect

enrollmentId (string, optional)

An optional string representing the Enrollment ID of the Teller enrollment you want to update if it has become disconnected.

userId (string, optional)

An optional string representing the User ID of the Teller user you want to add more enrollments to.

connectToken (string, optional)

An optional string representing the Connect Token returned by one of Teller API's endpoints and used to initialize Teller Connect to perform a particular task (e.g. as completing a payment requiring multi-factor authentication).

nonce (string, optional)

An optional string to be used when signing the enrollment tokens. If set, Teller Connect will include a signature in the success payload which you can verify to prevent token reuse attacks. This value must be randomly generated and unique to the current session. More information on signature verification can be found below.

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 called when the user successfully completed the flow. This function accepts one parameter:

  • enrollment - contains a user's enrollment data (see Part 3. for more information)
  • payment - contains payment data when a user was required to complete MFA
  • payee - contains payee data when a user was required to complete MFA

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.

onFailure (function, optional)

An optional callback called when payee or payment creation fails. This function accepts one parameter: a failure object, which contains:

  • type - the type of the failure. Possible values: payee, payment
  • code - a machine readable failure code. Possible values: timeout, error
  • message - a human readable failure message

Example:

{
  "type": "payment",
  "code": "error",
  "message": "We were unable to complete the payment."
}

Part 3. Handle a successful enrollment

When a user completes the enrollment flow successfully, the library will call the onSuccess 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": "token_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"
    }
  },
  // Signatures of the payload that can be used for verification.
  "signatures": [
    "xxx"
  ]
}

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.

If a nonce was specified when initializing Teller Connect, the Enrollment object will include a signatures element with a list of signatures that can be used to prevent token reuse attacks by verifying that the accessToken was indeed generated by Teller Connect during the current session.

The signatures are ED25519 with a SHA-256 digest and contain the following values concatenated with a dot: nonce.accessToken.userId.enrollmentId.environment. Please use the Token Signing Key from your application's Teller dashboard for verification. Note that the signatures element may contain multiple signatures to account for situations when we need to rotate our private keys. In such case you should be able to verify at least one of the signatures with the public key from your application's dashboard.

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.