Environments

BillerAPI provides separate sandbox and production environments so you can develop and test without affecting real data.

Sandbox vs Production

Every BillerAPI account has access to both environments. Sandbox uses test data and test billers — no real credentials are ever processed. Production connects to real biller sites and returns real bill data.

	Sandbox	Production
Base URL	https://sandbox.api.billerapi.com	https://api.billerapi.com
API key prefix	bb_test_	bb_live_
Billers	5 test billers (see below)	Real biller integrations
Data	Synthetic test data, deterministic responses	Real bills and account data
Rate limits	Same as production	100 req/min (most endpoints)
Webhooks	Sandbox events only	Real-time events

There is also a staging environment at https://api.staging.billerapi.com used for internal testing. This is not available to external developers.

The `environment` field on webhooks

Every webhook delivery carries an environment field at the top level of the envelope. It is one of three string values: dev, staging, or prod. Use it to route deliveries to the right downstream system — for example, write sandbox events to a dev-only projection, prod events to the production projection.

BillerAPI uses a three-mode environment string rather than a two-mode boolean. staging is internal-only today; webhooks for external clients arrive with prod (live billers) or dev (sandbox).

Webhook envelope with environment

{
  "id": "evt_01HX9K7MZQR4F3X5V2W8N1B2C3",
  "object": "event",
  "type": "bill.created",
  "api_version": "2026-04-29",
  "created": 1714387200,
  "environment": "dev",
  "data": {
    "object": {
      "id": "bill_01HX...",
      "object": "bill",
      "link_id": "link_01HX...",
      "biller_id": "biller_01HX..."
    }
  },
  "request": { "id": "req_01HX...", "idempotency_key": null }
}

`livemode` / `mode` on API responses

Every top-level JSON object returned by a client-authenticated REST call carries two additive fields so you can see, on the wire, which environment served the request:

livemode — a boolean, true in production and false in sandbox. This mirrors the Stripe-style field integrators expect.
mode — the same signal as an explicit string, "sandbox" or "production".

For a paginated response, the indicator is added once at the top level of the envelope (alongside has_more / next_cursor) — never repeated inside each row. Bare-array responses, streamed (SSE) responses, and error envelopes do not carry it. Both fields are additive, so existing integrations that ignore them keep working unchanged.

Note this is a two-mode indicator (sandbox vs production) scoped to API responses. It is not the three-mode environment field on webhook envelopes described above — webhooks keep dev / staging / prod.

Object response with livemode / mode

{
  "id": "bill_01HX...",
  "object": "bill",
  "amount_due": 12750,
  "livemode": false,
  "mode": "sandbox"
}

Switching Environments

To move from sandbox to production, change two things: the base URL and the API keys. All endpoint paths, request bodies, and response shapes stay the same.

Environment configuration

// Sandbox
const BASE_URL = 'https://sandbox.api.billerapi.com';
const CLIENT_SECRET = 'bb_test_xxxxxxxx';

// Production — just swap these two values
const BASE_URL = 'https://api.billerapi.com';
const CLIENT_SECRET = 'bb_live_xxxxxxxx';

Sandbox Test Billers

The sandbox environment includes five test billers that simulate different biller types. These are always available and return deterministic test data.

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

Use account number 4242424242 with any username and password to simulate a successful account link. See the Getting Started guide for the full list of test account numbers and scenarios.

Go Live Guide — checklist for moving from sandbox to production
Getting Started — first integration walkthrough using sandbox
Authentication — API key management and security
Webhooks — full envelope shape and signature verification

Was this page helpful?