Connect SDK

The Connect SDK opens a secure iframe for users to link their biller accounts. Credentials never touch your code.

Installation

npm install @billerapi/connect-sdk

yarn add @billerapi/connect-sdk

pnpm add @billerapi/connect-sdk

Quick Start

Initialize the SDK with your client ID, create a connect handler with a link token, and call open().

import { BillButler } from '@billerapi/connect-sdk';

// 1. Initialize with your client ID
const billbutler = new BillButler({
  clientId: 'your_client_id',
  environment: 'sandbox',
});

// 2. Create a handler with the link token from your server
const handler = billbutler.create({
  linkToken: 'lt_xxx', // from POST /link/token/create
  onSuccess: (publicToken, metadata) => {
    // Send publicToken to your server to exchange for an access token
    console.log('Linked!', metadata.accountId, metadata.institutionName);
    fetch('/api/exchange-token', {
      method: 'POST',
      body: JSON.stringify({ publicToken }),
    });
  },
  onExit: (error) => {
    if (error) {
      console.error('Connect error:', error.code, error.message);
    } else {
      console.log('User closed the modal');
    }
  },
  onEvent: (eventName, metadata) => {
    console.log('Connect event:', eventName, metadata);
  },
});

// 3. Open the Connect modal
handler.open();

Server-side setup

Before opening the SDK, your server must create a link token via POST /link/token/create with your client credentials. See the Getting Started guide.

Configuration

Pass a BillButlerConfig object to the constructor.

Property	Type	Required	Description
clientId	string	Yes	Your BillerAPI client ID
environment	'development' \| 'sandbox' \| 'production'	No	Target environment (auto-detected if omitted)
baseUrl	string	No	Custom base URL (used to derive connect URL)
apiUrl	string	No	Custom API URL (overrides environment default)
connectUrl	string	No	Explicit connect app URL (overrides baseUrl derivation)

Connect Options

Pass ConnectOptions to billbutler.create().

Property	Type	Required	Description
linkToken	string	Yes	Token from `POST /link/token/create`
onSuccess	(publicToken, metadata) => void	Yes	Called when user completes linking
onExit	(error?) => void	No	Called when user exits or an error occurs
onLoad	() => void	No	Called when the modal iframe is loaded
onEvent	(eventName, metadata) => void	No	Called for flow events (analytics)
theme	'light' \| 'dark'	No	Modal theme (defaults to light)

Handler Methods

billbutler.create() returns a ConnectHandler.

open(): Promise<void>

Opens the Connect modal iframe. No-op if already open.

close(): void

Closes the modal and cleans up. No-op if already closed.

isOpen(): boolean

Returns whether the modal is currently open.

Callback Data Types

ConnectMetadata (onSuccess)

Field	Type	Description
accountId	string	Unique ID for the connected account
accountName	string?	Account display name
accountType	string?	e.g., 'checking', 'savings'
institutionName	string?	Biller/institution name
selected_accounts	string[]?	IDs of selected accounts
consents	{ accounts, bills }	Granted consent scopes

ConnectError (onExit)

Field	Type	Description
code	string	Error code (e.g., MODAL_OPEN_ERROR)
message	string	Human-readable error message
details	any?	Additional error context

Integration Flow

The complete flow from creating a link token to retrieving bills.

Server: Create link token

POST /link/token/create with client credentials. Returns a link_token.

Client: Initialize SDK

new BillButler({ clientId, environment }) then billbutler.create({ linkToken, onSuccess, onExit })

Client: Open Connect modal

handler.open() — opens a secure iframe hosted by BillerAPI

User: Complete linking flow

Select biller → enter credentials → complete MFA → select accounts

Client: Receive public token

onSuccess(publicToken, metadata) fires. Send publicToken to your server.

Server: Exchange for access token

POST /link/token/exchange with public_token. Returns access_token, biller_id, link_id.

Server: Fetch bills

GET /bills/get with Authorization: Bearer <access_token>

Theming

The Connect modal supports light and dark themes via the theme option.

JavaScript

const handler = billbutler.create({
  linkToken: 'lt_xxx',
  theme: 'dark', // 'light' (default) or 'dark'
  onSuccess: (publicToken, metadata) => { /* ... */ },
});

Cleanup

Call destroy() when you're done with the SDK instance to close the modal and clean up event listeners.

JavaScript

// Clean up when component unmounts or SDK is no longer needed
billbutler.destroy();

Tip

In React, call billbutler.destroy() in a useEffect cleanup function to avoid memory leaks.

Link API Reference

Token create and exchange endpoints

Getting Started

End-to-end integration walkthrough

Authentication Guide

Client credentials and access tokens

Webhooks Guide

Listen for account link events