Getting Started

Go from zero to retrieving bills in 6 steps. This guide uses the sandbox environment with test data — no real accounts needed.

Create a Developer Account

Go to the Client Portal and click Sign Up
Verify your email address
Log in to access your developer dashboard

Get Sandbox Credentials

From your dashboard, navigate to API Keys and generate a sandbox client secret.

You'll need two values for all API calls:

X-Client-ID: your_client_id

X-Client-Secret: bb_test_xxxxxxxx

Note

Sandbox keys have the bb_test_ prefix. All sandbox requests go to https://sandbox.api.billerapi.com.

Make Your First API Call

Let's list available billers — the simplest endpoint to verify your credentials work.

List billers

const response = await fetch('https://sandbox.api.billerapi.com/billers', {
  headers: {
    'X-Client-ID': process.env.BILLERAPI_CLIENT_ID,
    'X-Client-Secret': process.env.BILLERAPI_CLIENT_SECRET,
  },
});
const data = await response.json();
console.log(data);
// Returns: Test Electric Company, Test Credit Card,
// Test Internet Provider, Test Insurance Co., Test Water Utility

Tip

In sandbox, you'll see 5 test billers: Test Electric Company, Test Credit Card, Test Internet Provider, Test Insurance Co., and Test Water Utility.

Link a Test Account

Use the Connect SDK to link a test biller account. This is a two-part flow: your server creates a link token, then the SDK handles the user experience.

Server: Create a link token

// Server-side: Create a link token
const response = await fetch('https://sandbox.api.billerapi.com/link/token/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-ID': process.env.BILLERAPI_CLIENT_ID,
    'X-Client-Secret': process.env.BILLERAPI_CLIENT_SECRET,
  },
  body: JSON.stringify({
    client_id: process.env.BILLERAPI_CLIENT_ID,
    client_user_id: 'user_123',
    biller_id: 'test_electric_company',
    consents: ['bills'],
  }),
});
const { link_token } = await response.json();
// Send link_token to your frontend

Client: Open the Connect SDK

JavaScript

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

const billbutler = new BillButler({
  clientId: 'your_client_id',
  environment: 'sandbox',
});

const handler = billbutler.create({
  linkToken: linkToken, // from your server
  onSuccess: async (publicToken, metadata) => {
    console.log('Account linked!', metadata.institutionName);

    // Exchange the public token on your server
    const res = await fetch('/api/exchange-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ publicToken }),
    });
    const { access_token } = await res.json();
    // Store access_token — you'll need it to fetch bills
  },
  onExit: (error) => {
    if (error) console.error('Error:', error.code);
  },
});

handler.open();

Sandbox test credentials

Use account number 4242424242 with any username and password. This always succeeds. See the sandbox reference table below for other test scenarios.

Server: Exchange the public token

// Server-side: Exchange public token for access token
const response = await fetch('https://sandbox.api.billerapi.com/link/token/exchange', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-ID': process.env.BILLERAPI_CLIENT_ID,
    'X-Client-Secret': process.env.BILLERAPI_CLIENT_SECRET,
  },
  body: JSON.stringify({
    public_token: publicToken,
    client_id: process.env.BILLERAPI_CLIENT_ID,
  }),
});
const { access_token, biller_id, link_id } = await response.json();
// Store access_token securely — use it to fetch bills

Retrieve Bills

Use the access token from Step 4 to fetch bills for the linked account.

Fetch bills

const response = await fetch(
  'https://sandbox.api.billerapi.com/bills/get?account_link_id=' + linkId,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);
const bills = await response.json();
console.log(bills);
// Sandbox returns: Test Electric Company bill
//   Amount: $127.50
//   Status: PENDING
//   Due: 15 days from now
//   Line items:
//     - Electricity usage (850 kWh): $102.00
//     - Distribution charge: $18.50
//     - Renewable energy surcharge: $7.00

Listen for Webhooks

Register your webhook endpoint

Authentication

Webhook registration uses the JWT token you receive when signing in to the Client Portal. Get your token from POST /iam/auth/signin with your email and password.

// First, get a JWT token by signing in
const authResponse = await fetch(
  'https://sandbox.api.billerapi.com/iam/auth/signin',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'your@email.com',
      password: 'your_password',
    }),
  }
);
const { token } = await authResponse.json();

// Then register your webhook
const response = await fetch(
  `https://sandbox.api.billerapi.com/iam/clients/${clientId}/webhooks`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify({
      environment: 'sandbox',
      url: 'https://your-server.com/webhooks/billerapi',
      events: ['bill.created', 'bill.updated', 'account-link.created'],
      secret: 'whsec_your_signing_secret',
    }),
  }
);

Test with sandbox

cURL

curl -X POST https://sandbox.api.billerapi.com/sandbox/trigger-event \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -d '{
    "event_type": "bill.created",
    "client_id": "your_client_id",
    "webhook_url": "https://your-server.com/webhooks/billerapi",
    "webhook_secret": "whsec_your_signing_secret"
  }'

Note

For full webhook documentation including signature verification, retry policy, and all 10 event types, see the Webhooks guide.

Sandbox Reference

Use these magic account numbers in the Connect flow to trigger specific scenarios.

Account Number	Scenario	Behavior
4242424242	Success	Always succeeds. Returns a $127.50 pending bill.
4000000001	Auth Failure	Returns INVALID_CREDENTIALS error.
4000000002	Unavailable	Returns BILLER_UNAVAILABLE error.
4000000003	MFA Required	Prompts for MFA. Use code `123456`.
4000000004	Locked	Returns ACCOUNT_LOCKED error.
4000000005	Past Due	Returns overdue bills ($245.00) with late fees.
4000000006	Auto-Pay	Returns a scheduled $89.99 bill with auto-pay enabled.
4000000007	Payment Plan	Returns 3 installments of $150.00 each.
4000000008	Multi-Account	Account discovery returns multiple accounts.

Test Billers

Biller ID	Name	Type
test_electric_company	Test Electric Company	Utility
test_credit_card	Test Credit Card	Financial
test_internet_provider	Test Internet Provider	Telecom
test_insurance_company	Test Insurance Co.	Insurance
test_water_utility	Test Water Utility	Utility

Next Steps

API Reference

Complete endpoint documentation

Connect SDK

Full SDK reference and options

Webhooks

Event types, signatures, and testing

Authentication

Security, rate limits, and best practices

Related API Reference

Billers API

Search and list billers

Link API

Token creation and exchange

Bills API

Retrieve and manage bills