Getting Started

import { BillerApi, BillerApiError } from 'billerapi';

export async function listBillers(
  apiKey: string,
  log: (line: string) => void = console.log,
): Promise<void> {
  const billerapi = new BillerApi(apiKey);
  try {
    for await (const biller of await billerapi.billers.list()) {
      log(`${biller.id} ${biller.name} ready_for_bills=${biller.ready_for_bills}`);
    }
  } catch (error) {
    if (error instanceof BillerApiError) {
      log(`${error.code} request_id=${error.requestId ?? "unknown"}`);
    }
    throw error;
  }
}

curl https://sandbox.api.billerapi.com/v1/billers \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

import { BillerApi } from 'billerapi';

export async function createLinkToken(apiKey: string) {
  const billerapi = new BillerApi(apiKey);
  return billerapi.links.createToken({
    client_user_id: 'user_123',
    biller_id: 'sb_utility',
    consents: ['bills:read'],
  });
}

// Send link_token to Connect. Keep link_token_id on your server.

curl -X POST https://sandbox.api.billerapi.com/v1/link-tokens \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_user_id": "user_123",
    "biller_id": "sb_utility",
    "consents": ["bills:read"]
  }'

import { BillerApi, type LinkTokenStatusResult } from 'billerapi';

export async function inspectLinkToken(
  apiKey: string,
  linkTokenId: string,
): Promise<LinkTokenStatusResult> {
  const billerapi = new BillerApi(apiKey);
  const continuation = await billerapi.links.retrieveTokenStatus(linkTokenId);

  if (continuation.next_action === 'RETRY' && !continuation.retryable) {
    throw new Error('Connect retry was not approved');
  }
  return continuation;
}

import { BillerApiElements } from 'billerapi-js';

export function openConnect(clientId: string, linkToken: string): void {
  const elements = new BillerApiElements({ clientId, environment: 'sandbox' });
  elements.connect({
    linkToken,
    onSuccess: async (publicToken, metadata) => {
      if (metadata.completion_mode === 'update') return;
      await fetch('/api/exchange-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ public_token: publicToken }),
      });
    },
    onExit: (error) => {
      if (error) {
        console.error(error.code, error.blocking_reason, error.next_action, error.retryable);
      }
    },
  }).open();
}

import { BillerApi } from 'billerapi';

export async function exchangeToken(apiKey: string, publicToken: string) {
  const billerapi = new BillerApi(apiKey);
  return billerapi.links.exchangeToken({ public_token: publicToken });
}

curl -X POST https://sandbox.api.billerapi.com/v1/link-tokens/public-sandbox-.../exchange \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import { BillerApi, type Bill } from 'billerapi';

export async function listBills(apiKey: string, linkId: string): Promise<Bill[]> {
  const billerapi = new BillerApi(apiKey);
  const bills: Bill[] = [];
  for await (const bill of await billerapi.bills.list({ account_link_id: linkId })) {
    bills.push(bill);
  }
  return bills;
}

curl "https://sandbox.api.billerapi.com/v1/bills?account_link_id=$LINK_ID" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

import { BillerApi } from 'billerapi';

export async function createWebhook(apiKey: string) {
  const billerapi = new BillerApi(apiKey);
  const endpoint = await billerapi.webhookEndpoints.create({
    url: 'https://your-server.com/webhooks/billerapi',
    events: ['connection.ready', 'bill.created', 'bill.updated'],
  });
  if (!endpoint.secret) throw new Error('Webhook signing secret was not returned');
  return { id: endpoint.id, secret: endpoint.secret };
}

import { BillerApi } from 'billerapi';

interface BillCreatedEvent {
  id: string;
  object: 'event';
  type: 'bill.created';
  api_version: string;
  created: number;
  data: { object: { id: string; object: 'bill'; user_id: string; biller_id: string } };
  request: { id: string | null; idempotency_key: string | null };
  producer_service: string;
  correlation_id: string | null;
}

export function verifyWebhook(
  apiKey: string,
  rawBody: string | Buffer,
  signatureHeader: string | undefined,
  webhookSecret: string,
): BillCreatedEvent {
  const billerapi = new BillerApi(apiKey);
  return billerapi.webhooks.constructEvent<BillCreatedEvent>(
    rawBody,
    signatureHeader,
    webhookSecret,
  );
}

# Authenticate the CLI with a sandbox key
billerapi login --env sandbox

# Forward live events to your local server (HMAC-signed)
billerapi listen --forward-to http://localhost:4242/webhooks

# In another terminal, fire a test event into the sandbox
billerapi trigger bill.created