Connection flow fundamentals

Connection lifecycle

Five stages, in order. Stages 1 and 4 run on your server with your API key; stages 2 and 3 run in the browser; stage 5 is ongoing.

const response = await fetch('https://sandbox.api.billerapi.com/v1/link-tokens', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer $BILLERAPI_API_KEY',
  },
  body: JSON.stringify({
    client_user_id: 'user_123',
    biller_id: 'sb_utility',
    consents: ['bills:read'],
  }),
});
const { link_token } = await response.json();

import { BillerApiElements } from 'billerapi-js';

const elements = new BillerApiElements({
  clientId: 'your_client_id',
  environment: 'sandbox',
});

const handler = elements.connect({
  linkToken,
  onSuccess: async (publicToken, metadata) => {
    // send publicToken to your server for exchange
  },
  onExit: (error) => { if (error) console.error(error.code); },
});
handler.open();

const exchange = await fetch(
  `https://sandbox.api.billerapi.com/v1/link-tokens/${encodeURIComponent(publicToken)}/exchange`,
  { method: 'POST', headers: { Authorization: 'Bearer $BILLERAPI_API_KEY' } },
);
const { access_token, biller_id, account_link_id } = await exchange.json();

{
  "id": "ls_9f2c41d8a7b3",
  "object": "link_session",
  "client_user_id": "user_123",
  "biller_id": "sb_utility",
  "consents": ["bills:read"],
  "status": "succeeded",
  "account_link_id": "al_5e8d02c9f1a4",
  "expires_at": "2026-08-23T18:30:00Z"
}

GET /v1/bills?account_link_id=al_5e8d02c9f1a4
Authorization: Bearer $BILLERAPI_API_KEY

Inside the hosted flow

These are the steps your user moves through inside the Elements modal, in order. Steps adapt to the biller and to the session — only region-gated billers show the region step, a biller without MFA skips verification, a single-account biller skips account selection, and update or repair sessions skip consent.

Data permissions

Consent scopes decide what BillerAPI may read on a linked account. They are requested on the link token and shown to the user on the consent step.

Request only the scopes your use case needs. Users see the requested scopes on the consent step and must re-link to expand them.

How BillerAPI authenticates

Credentials are entered in the hosted flow only. Biller usernames and passwords are collected inside the Elements frame and never touch your servers — you never receive, proxy, or store them.

Region selection precedes the login, not the biller choice. A small number of billers serve several regions under one brand (Eversource CT/MA/NH, for example). For those, the hosted flow inserts a region step after consent and before credentials, because the region determines which login form the biller presents. Every other biller goes straight from consent to credentials.

MFA and security questions are handled inline. When a biller challenges the login with a one-time code or a security question, the hosted flow prompts the user in place and continues the session once it clears. No callback into your application is required.

Sandbox has a deterministic credential. Account number 4242424242 with any username and password always succeeds, so you can build and test the entire lifecycle before you have a real biller account.