Getting Started

import { BillerApi } from 'billerapi';

// The SDK reads bak_test_ vs bak_live_ from the key and targets the
// matching environment automatically — no base URL required.
const billerapi = new BillerApi(process.env.BILLERAPI_API_KEY);

// List billers — the SDK auto-paginates, so you can iterate every page.
const billers = await billerapi.billers.list();
for await (const biller of billers) {
  console.log(biller.id, biller.name);
}
// In sandbox you'll see 6 test billers: Sandbox Utility, Sandbox Power,
// Sandbox Gas, Sandbox Water, Sandbox Electric, Sandbox Telecom

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

// Server-side: create a link token for one of your users.
// client_id is inferred from your API key.
const { link_token } = await billerapi.links.createToken({
  client_user_id: 'user_123',
  biller_id: 'sb_electric',
  consents: ['bills'],
});
// Send link_token to your frontend.

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

import { BillerApiElements } from 'billerapi-js';

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

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

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

handler.open();

// Server-side: exchange the public token for a durable link.
const { access_token, link_id, biller_id } = await billerapi.links.exchangeToken({
  public_token: publicToken,
});
// Store access_token securely. Use link_id to fetch bills (next step).

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

// Bills are scoped to your API key and filtered by the account link.
const bills = await billerapi.bills.list({ account_link_id: linkId });
for await (const bill of bills) {
  console.log(bill.id, bill.merchant_name, bill.amount, bill.status);
}
// Sandbox returns a Sandbox Electric bill:
//   Amount: $127.50 · Status: PENDING · Due: 15 days from now

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

const endpoint = await billerapi.webhookEndpoints.create({
  url: 'https://your-server.com/webhooks/billerapi',
  events: ['bill.created', 'bill.updated'],
});
// endpoint.secret (whsec_...) is shown ONCE — store it now.
console.log(endpoint.id, endpoint.secret);

// rawBody must be the raw request body string (not a parsed object).
try {
  const event = billerapi.webhooks.constructEvent(
    rawBody,
    signatureHeader,               // the signature header value from the request
    process.env.BILLERAPI_WEBHOOK_SECRET,
  );
  if (event.type === 'bill.created') {
    // handle the new bill
  }
} catch {
  // reject with 400 — signature or timestamp failed
}

# 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