Teller Connect

How to link your users' financial accounts to your application using Teller Connect

Introduction

Teller Connect is the client-side UI component that your users will use to connect their accounts to your application.

Teller Connect handles credential validation, multi-factor authentication, account selection, and error handling for every institution accessible using Teller.

Flow Overview

Enrolling an end-user account using Teller Connect is very simple, and involves just three steps:

The end-user opens Teller Connect from within your application
The end-user selects their institution, authenticates with the financial institution and selects the accounts they want to share with your application
Teller Connect hands control back to your application with an access token you can use to access the end-user's accounts with the Teller API

Integrating for the Web

Start by including the Teller Connect script in the HTML of your application.

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

Including the script at the base of the body element is recommended so that it doesn't block rendering of your page, but it can run anywhere you choose to include it. 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).

Next, setup Teller Connect by calling TellerConnect.setup with a valid configuration object. The bare minimum configuration is shown below, you can find a full list of supported properties later in this document.

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

This code does three things:

Loads the Teller Connect loader in your page.
Initializes Teller Connect with a bare-bones configuration
Installs an event listener to present Teller Connect on a button click.

Handling a Successful Enrollment

Once the user has enrolled Teller Connect will dismiss itself and return control to your application by invoking the onSuccess callback with a single parameter: the enrollment object.

{
  "accessToken": "token_xxxxxxxxxxxxx",
  "user": {
    "id": "usr_xxxxxxxxxxxxx"
  },
  "enrollment": {
    "id": "enr_xxxxxxxxxxxxx",
    "institution": {
      "name": "Example Bank"
    }
  },
  "signatures": [
    "xxxxxxxxxxxxx"
  ]
}

The most important part of this payload is the accessToken, which you will use to access the end-user's accounts using the Teller API.

Verifying Enrollment Object Signature

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 generated by Teller 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, and environment. Use the Token Signing Key from your application's Teller dashboard for verification.

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.

Integrating for Other Platforms

Teller offers first-party support for other platforms including Apple, Android, React, and React Native. For instructions on how to integrate Teller Connect for those platforms, please consult each respective project's README.

Configuration Options

The following properties are support in the Teller Connect configuration object:

Name
environment
Type
string, optional
Description
The environment to use for enrolling the user's accounts. Valid values are "sandbox", "development" and "production". The "sandbox" environment 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 enrollments.
Name
applicationId
Type
string, required
Description
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
Name
institution
Type
string, optional
Description
When set to a valid institution id Teller Connect will skip its institution picker and load the first step for the corresponding institution. Use this to build your own picker experience.
Name
selectAccount
Type
string, optional
Description
- "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 select only one to share with your application
- "multiple" - the user will see a list of supported financial accounts and will select one or more to share with your application
Name
enrollmentId
Type
string, optional
Description
An id of a previously created enrollment. Use to initialize Teller Connect in update mode to repair a disconnected enrollment.
Name
connectToken
Type
string, optional
Description
A connect token is returned in a Teller API response when user interaction is required to complete the transaction, e.g. when multi-factor authentication is required to complete a payment. When initialized with a connectToken Teller Connect will guide the user through completing the transaction.
Name
nonce
Type
string, optional
Description
An arbitrary string chosen by your application to allow for the cryptographic signing of the enrollment object passed to the onSuccess callback. This value must be randomly generated and unique to the current session.
Name
onInit
Type
function, optional
Description
An optional callback that if supplied is invoked when Teller Connect finishes loading
Name
onSuccess
Type
function, required
Description
Invoked with a single argument when the end-user has completed the flow. The argument is context dependent:
- An enrollment object upon successful enrollment
- A payment object when MFA was required to complete a payment
- A payee object when MFA was required to create a payee
For more information about the format of payment and payee consult the Zelle guide.
Name
onExit
Type
function, optional
Description
Fired when the end-user dismisses Teller Connect without enrolling an account.
Name
onFailure
Type
function, optional
Description
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." }