Sandbox vs Production

The BILL API Platform capabilities (BILL v3 API and BILL Elements) are available in two distinct development environments: Sandbox and Production.

Each environment is purpose-built to support different phases of your application development, from early testing to live operations. In this section, we explain the operational, security, and functional differences between these environments.

Development environments

The BILL sandbox and production environments provide consistent interfaces for core BILL operations (such as creating a vendor and paying a vendor), but each environment serves different purposes.

Sandbox for testing

Optimized for iterative testing without financial impact (no money movement). Uses simulated data & mock workflows.

Production for live operations

Optimized for reliability, security, & transaction finality. Enforces strict data integrity & supports real money movement.

Platform services URLs

Sandbox

API base URL: https://gateway.stage.bill.com/connect
Webhooks API base URL: https://gateway.stage.bill.com/connect-events
Web app URL: https://login.stage.us.bill.com/neo/login

Production

API base URL: https://gateway.prod.bill.com/connect
Webhooks API base URL: https://gateway.prod.bill.com/connect-events
Web app URL: https://login.us.bill.com/neo/login

Service levels & reliability

Sandbox

No SLAs: Availability & performance may vary.
Disruptions: You may experience occasional errors or downtime.
Updates: Deployments occur at least 2 times a day (typically morning or afternoon PT).

Production

Supports live financial workflows with real money movement.

This environment is backed by SLAs that guarantee stability, uptime, & responsiveness.

Operational capabilities

Most BILL core capabilities work identically in both environments. BILL excludes specific capabilities from sandbox to preserve security and platform integrity.

Sandbox limitations

Money movement: You cannot process real transactions involving actual bank accounts.
Accounting system integrations: Connections to accounting system platforms (such as QuickBooks & NetSuite) are not supported.

Payment processing

Sandbox

System timers drive status changes to simulate the lifecycle. Status change timing may not exactly match the experience in production.

Production

Payment statuses are driven by real-world banking workflows, cutoffs, & clearing logic.

Webhook events

Sandbox

Webhooks use synthetic values & are not tied to real transactions.

Dynamic allowlisting is not supported.
You can use public testing tools (such as webhook.site or Pipedream) for local testing.

Production

Webhooks deliver live event notifications directly to your secure infrastructure. BILL coordinates an allowlist setup to ensure traffic is securely routed to your verified endpoints.

Verification workflows

The BILL verification workflows differ significantly between environments to enable rapid testing without the need to submit sensitive real-world data.

Sandbox

Risk decisions (APPROVED, REVIEW, or DECLINED) are simulated based on specific test inputs.

Production

BILL compliance infrastructure reviews organizations based on actual user data.

BILL Network vendor auto-connection

BILL Network vendor auto-connection behavior differs between environments.

Sandbox

In sandbox, BILL uses a smaller set of test vendors to simulate the connection process.

Production

In production, BILL uses the full BILL Network for real-time vendor matching.

NOTE: Use vendor connections in sandbox to test your integration logic, and not to replicate exact production behavior.

In both environments, vendor connections follow a specific timeline.

First connection: When a new organization attempts to connect with a vendor for the first time, the connection status is Pending for 3-days with an expected connection date.
Subsequent connections: After the first connection is established, future eligible vendors connect almost instantly.

Test data for sandbox integrations

In this section, we list data that you can use for testing your integrations in sandbox.

Organization risk status (KYC/KYB)

Use specific input to trigger an organization KYC/KYB risk outcome.

KYC/KYB workflow	Fields & values	SSN/EIN range (in the Onboarding Element) and status
KYC flow (Individual/Sole Proprietorship)	User name: Set user first name in the `MOCK{first_name}` format while creating the user. For example, `MOCKJohn`. City: Set user city in the `MOCK{status}` format. For example, `MOCKdecline` to simulate a `DECLINED` status)	SSN range From `676543100` To `676543200` (`APPROVED`) From `676544100` To `676544200` (`REVIEW`) From `676545100` To `676545200` (`DECLINED`)
KYB flow (All other business types)	Business name: Prefix with `MOCK`. City: Set user city in the `MOCK{status}` format. For example, `MOCKdecline` to simulate a `DECLINED` status)	EIN range From `676543300` To `676543400` (`APPROVED`) From `676544300` To `676544400` (`REVIEW`) From `676545300` To `676545400` (`DECLINED`)

KYC/KYB workflow

Fields & values

SSN/EIN range (in the Onboarding Element) and status

KYC flow (Individual/Sole Proprietorship)

User name: Set user first name in the MOCK{first_name} format while creating the user. For example, MOCKJohn.

City: Set user city in the MOCK{status} format. For example, MOCKdecline to simulate a DECLINED status)

SSN range

From 676543100 To 676543200 (APPROVED)

From 676544100 To 676544200 (REVIEW)

From 676545100 To 676545200 (DECLINED)

KYB flow (All other business types)

Business name: Prefix with MOCK.

City: Set user city in the MOCK{status} format. For example, MOCKdecline to simulate a DECLINED status)

EIN range

From 676543300 To 676543400 (APPROVED)

From 676544300 To 676544400 (REVIEW)

From 676545300 To 676545400 (DECLINED)

BILL Network connection test scenarios

Use specific data to trigger different BILL Network connection scenarios in sandbox.

Vendor auto-connection with the BILL v3 API

Create a vendor record with with POST /v3/vendors. In your request, set the specified name and address information. The created test vendor is auto-connected in the BILL Network. You can view the connected vendor in the BILL Web app.

See Create a vendor in the API reference for more information.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/vendors' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "name": "BPBRstage1 new",
  "address": {
    "line1": "113 Salinas Court",
    "city": "Palo Alto",
    "stateOrProvince": "TX",
    "zipOrPostalCode": "75013",
    "country": "US"
    }
}'

Search for a Basic Receivables vendor

Search for the vendor in the BILL Network with GET /v3/network. In your request, set the specified vendor name. From the response, use the Payment Network ID (PNI) id based on the specified address. Use the same vendor name to search with the Vendor setup Element.

See Search for an organization in the BILL Network in the API reference for more information.

"name": "BPBRstage1 new"
"city": "Antonetteport"
"country": "United States"
"line1": "74006 Jaylen Hill"
"stateOrProvince": "CO"
"zipOrPostalCode": "60406-7362"

Search for a vendor set up to issue invoices & receive payments

"name": "BPBRstage1 new"
"city": "Erichside"
"country": "United States"
"line1": "96412 Pollich Centers"
"stateOrProvince": "WV"
"zipOrPostalCode": "02958-7168"

Search for a verified national vendor (Mastercard bill pay network)

Verified national vendors (Large billers) include water, power, cable, and phone companies and are part of the BILL verified national vendor network.

Search for the vendor in the BILL Network with GET /v3/network. In your request, set the specified vendor name and accountNumber. From the response, use the Payment Network ID (PNI) id. Use the same vendor name to search with the Vendor setup Element.

"name": "A T C Communications"
"accountNumber": 123456

Virtual card (VCard) vendor

"name": vdbr5
"line1": vdbr5
"line2": test vdbr5
"city": santa clara
"stateOrProvince": CA
"zipOrPostalCode": 94087