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",
          // Teller's products that you would like to use, e.g. "verify"
          products: ["verify", ...],
          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 and React. For instructions on how to integrate Teller Connect for those platforms, please consult each respective project's README.

Configuration Options

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

  • 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
    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
    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
    products
    Type
    array, required
    Description

    List of Teller's products that you would like to use. The choice of products may determine which steps the user has to complete during enrollment. Valid values are:

    • "verify" - account numbers and routing numbers (that are either available right after enrollment or require additional Teller Connect flows)
    • "verify.instant" - account numbers and routing numbers that are available right after enrollment (see 'Verify Account Details via Microdeposit')
    • "balance" - real-time account balances
    • "transactions" - categorised transaction data
    • "identity" - account-holder data
    • "payments" (BETA) - send payments on behalf of your users
  • 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

    Your application must choose an arbitrary string to allow for the cryptographic signing of the enrollment object passed to the onSuccess callback. This prevents token reuse attacks. The value must be randomly generated on the server and unique to the current session. If generated client-side, an attacker could reuse the nonce together with the enrollment object from another session to impersonate the victim.

  • 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
    onInit
    Type
    function, optional
    Description

    An optional callback that if supplied is invoked when Teller Connect finishes loading

  • 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."
}