Sandbox & Production

Build and test against a Sandbox company instance, and keep it fully separate from Production.

You build and test your integration against a Sandbox company instance, then run it for real against a Production instance. Sandbox is a property of a company instance, not a separate copy of Everee. Your Sandbox and Production instances are separate Company instances (see Company instances & multiple EINs), so nothing you create in Sandbox appears in Production, and the other way around.

📘

Payroll Infrastructure

In Payroll Infrastructure, Sandbox is a testing tool for you, the partner. The partner key you call with decides the environment. A test key (zk_test_) creates Sandbox companies: each company's API key begins with tsk_test_, no real money moves, and nothing it does is real. A production key (zk_prod_) creates Production companies, with tsk_prod_ keys. Everee issues your production key after it reviews and approves your integration; until then, only the test key works for creating companies. You keep your test key after approval, so you can keep creating Sandbox companies to test with. Each key reaches only its own environment, so a request for a company in the other environment returns 404. A Sandbox company stays a Sandbox company and can't be converted: create a new company instead. You can retire a Sandbox company you no longer need, and there are limits on how many you create and on what each can use. Customers have no admin portal, so the portal steps below apply to hosted payroll only.


What's the same, and what's separate

Both environments use the same API domain, https://api.everee.com, for every request. That includes creating embedded experience URLs. Nothing in a URL selects the environment. The API token and tenant ID you send on each request decide which instance the request acts on.

Everything else is separate for each environment:

SandboxProduction
API domainhttps://api.everee.comhttps://api.everee.com
Company tenant IDIts ownIts own
API tokenIts ownIts own
API token begins withtsk_test_tsk_prod_
Webhook endpoints and signing keysIts ownIts own
Workers, payments, and other dataIts ownIts own

An API token works only with the instance it was created in. If you send a token with the other environment's tenant ID, the request fails.


Set up your Sandbox

  1. Get your Sandbox tenant ID. In Payroll Infrastructure, a Sandbox company's tenant ID is its id, returned when you create the company. In hosted payroll, ask your Everee contact or [email protected] which tenant ID is your Sandbox, and make a note of it.
  2. Create a Sandbox API token. In Payroll Infrastructure, the token is returned when you create a company through the Partner Company API with your test key: that company is a Sandbox company. In hosted payroll, sign in to the admin portal at https://app.everee.com with access to the Sandbox instance. Open Integrations Hub, find Everee API, and create a token. Confirm the "Company tenant ID" shown there is your Sandbox tenant ID, and that the new token begins with tsk_test_. See Authentication & API tokens.
  3. Create a Sandbox webhook endpoint. Create it with the Webhook Endpoints API using the Sandbox company's API key (in Payroll Infrastructure, the first can also be set at company creation), or in hosted payroll add it in the same Everee API section. Each instance can have up to three endpoints, and Everee generates a separate signing key for each. See Authenticating events.
  4. Store each environment's credentials separately. Keep the tenant ID, API token, webhook endpoint, and signing key together as one set per environment, and select the set by configuration, not in code. Never reuse any of them across environments.

Avoid mixing environments

  • Check the tenant ID before you test. A request acts on whichever instance its tenant ID and token belong to. If you send your Production values, you create real workers and real payroll activity. New tokens show their environment in the prefix: tsk_test_ is Sandbox and tsk_prod_ is Production.
  • Check the company's environment. In Payroll Infrastructure, the company responses include environment, which is SANDBOX or PRODUCTION.
  • Check where an event came from. Every webhook event includes the companyId of the instance that sent it. Use it to reject events from an unexpected instance.
  • Expect configuration to differ. Features and company settings are enabled for each instance separately, so Sandbox and Production can differ. If something works in one and not the other, contact support.
  • Remove test data from Production. If you created test workers in Production by mistake, contact support and we'll help you clean them up.

Test data and payments in Sandbox

  • Test worker data. Sandbox accepts made-up values. It doesn't check the format of a Social Security number, and a bank routing number doesn't need to exist in the bank directory. Use a nine-digit routing number and any account number.
  • TIN verification always fails. In Sandbox, a worker's taxpayer identifier verification always ends in VERIFICATION_FAILED, so worker.tin-verification-status-changed reports a failure. It doesn't block payroll or payment: the check supports tax filing, not paying the worker. Don't treat it as a bug, and don't look for a test SSN that passes.
  • No real money moves. A payment in Sandbox never sends funds.
  • Payments reach Paid only after approval. Every payment waits for approval: by a payroll admin in hosted payroll, or by approving its payroll run in Payroll Infrastructure. In hosted payroll only, payments can progress to Paid on their own if auto-approval is turned on for the Sandbox instance. Auto-approval is off by default; ask your Everee contact to turn it on.

Moving to Production

Your code needs no changes to its URLs. Switch to the Production tenant ID, API token, webhook endpoint, and signing key, and test again. If you're building an integration for multiple Everee customers, Everee reviews it before it's approved for live customers.

Pre-live review

Before a company goes live, Everee verifies each of these areas: company onboarding, company setup, worker creation, worker profile management, payroll processing, and GL and reporting. Build and test each of these in Sandbox first.


Did this page help you?