Sandbox Magic Numbers
Nine deterministic account_number values drive the link-flow scenarios in sandbox. Use them to integration-test every error path and edge case without ever touching a real biller.
Where to use these
account_number in POST /link/:link_token_id/submit-credentials and as the account_number query param on GET /bills. The sandbox returns the matching scenario every time, with the same data — your tests stay deterministic.4242424242successCredentials accepted on first try. Account discovery returns one residential account. Bills retrieve as a single PENDING bill due in 15 days.
discover_accounts4000000001auth_failuresubmit-credentials returns 200 with success: false. Use this to exercise your invalid-credentials UX.
INVALID_CREDENTIALS4000000002biller_unavailableSimulates a transient biller outage. submit-credentials and /bills both surface success: false with this code so you can confirm retry / backoff logic.
BILLER_UNAVAILABLE4000000003mfa_requiredsubmit-credentials returns status: mfa_required. Continue with POST /link/:id/submit-mfa using mfa_code "123456" (the only valid sandbox MFA code).
submit-mfa with code 1234564000000004account_lockedAccount is locked after too many failed attempts. Returned at the credentials step.
ACCOUNT_LOCKED4000000005past_dueCredentials accepted; /bills returns one OVERDUE bill dated 30 days in the past with a Late fee + Interest line item.
4000000006auto_payCredentials accepted; /bills returns one SCHEDULED bill with auto_pay_enabled: true and a due date 5 days out.
4000000007payment_planCredentials accepted; /bills returns THREE installment bills 30 days apart (one PENDING, two SCHEDULED), each labeled "Payment plan installment N of 3".
4000000008multiple_accountsdiscover-accounts returns THREE accounts (Primary, Vacation Home, Business) for the same set of credentials. Exercise the account-selection UX with N>1.
Programmatic discovery
GET https://sandbox.api.billerapi.com/sandbox/scenarios. Fetch it from a CI fixture if you want to seed tests automatically.Related
- Link a Biller Account — the flow that consumes these numbers.
- Set Up Webhooks — sandbox link completions trigger
link.completedwebhooks. - Go Live Checklist — what to do once your integration is working against these scenarios.