Live vs Test Mode

Preczn gives every platform two parallel environments: Test mode and Live mode. They share one API host and one dashboard — there is no separate sandbox URL to point at and no second integration to build. What changes is which records you can see and where your transactions actually go.

Every object you create belongs to exactly one mode and is invisible from the other: merchants, connections and their credentials, plans, routing rules, payment tokens, transactions, webhook subscriptions, and API keys. Your platform starts in Test mode, and Preczn enables Live mode for you when you are ready to process real money.

What is separated, and what is shared

Separated between modes	Shared across both modes
Merchants, their locations, owners, and documents	Your platform and portfolio
Connections and processor credentials	Dashboard users, roles, and passwords
Plans and routing rules	The activity log
Payment tokens
Transactions
Boarding forms and their templates
Webhook subscriptions and their delivery history
API keys

Because users are shared, the same login works in both modes — switching does not sign you out and there is no second account to create.

Because everything else is separated, a test-mode API key can never read or write a live-mode record, and a live-mode key can never see test data. There is no query, filter, or override that crosses the boundary.

Choosing a mode

Over the API

The key you authenticate with decides the mode. There is no mode header, no query parameter, and no alternate base URL — you call the same endpoints either way, and Preczn resolves the mode from the key in your x-api-key header.

Key prefix	Mode
`priv_test_`	Test
`pub_test_`	Test
`priv_`	Live
`pub_`	Live

A key's mode is fixed when the key is created and can never be changed. To move an integration from test to live, generate a live key and swap the credential — nothing else about your requests changes.

Object IDs carry the mode too, which makes it visible in your logs and your database: test-mode identifiers include a test_ segment after the type prefix, so mid_test_01h9kp… is a test merchant and mid_01h9kp… is a live one. See Object ID Prefixes.

For the full key model — public versus private, rotation, and authentication errors — see API Keys.

In the dashboard

A pill in the top navigation bar reads TEST or LIVE and shows which mode you are currently viewing. Select it to switch.

The choice applies globally. Every page you open afterwards — Merchants, Plans, Transactions, API Keys, Webhooks — shows only that mode's records until you switch back.

Switching in the two directions is deliberately asymmetric:

Live → Test takes one click.
Test → Live asks you to confirm first, because you are about to work against real transactions and real data.

📘
Check the pill before you go looking for missing data
An empty Merchants list or a transaction you cannot find is far more often the wrong mode than a missing record. Confirm which mode you are in first.

Moving to Live mode

Preczn enables Live mode for your platform; it is not a self-service setting. Until it is enabled, the mode pill is disabled and says that the platform is in test-only mode and that you should contact Preczn to enable live mode.

An individual user account can also be restricted to Test mode, independently of the platform. If your platform is live but one teammate cannot leave Test mode, it is that account-level restriction rather than the platform setting — an administrator can lift it from User Management.

Contact your Preczn representative when you are ready to enable Live mode for the platform. Expect the following to be true first:

Your integration authenticates with a test key and processes test transactions end to end.
Your plans and routing rules produce the routing you expect in Test mode.
You hold production credentials from each processor you intend to use.
Your webhook endpoint verifies signatures and handles the events you subscribe to.

Live mode does not inherit anything from Test mode. Once it is enabled you rebuild your configuration there: create live merchants and connections, add production processor credentials, recreate your plans and rules, generate live API keys, and create live webhook subscriptions.

Where test transactions go

A test transaction is real traffic to a real processor — it just lands in that processor's sandbox instead of production. Preczn applies your test-mode plan and routing rules exactly as it would in Live mode, selects a connection, and sends the request to that connection's sandbox environment.

This has one consequence worth planning for: your test-mode connections need sandbox credentials from each processor, not your production ones. Store the sandbox credentials on the connection in Test mode, and keep the production credentials on the matching connection in Live mode. See Connection Configuration and your processor's page under Supported Connections.

Because routing runs the same way in both modes, Test mode is where you prove out a plan before it touches real money — distribution splits, BIN rules, card-brand routing, and reject salvage all behave as they will in production. See Routing Rules.

Webhooks in Test mode

Webhooks fire in Test mode, and every subscription is scoped to a single mode. A test-mode subscription receives only test-mode events; a live-mode subscription receives only live-mode events. There is no crossover in either direction.

If you want the same notifications in both environments, create one subscription in each — and point the test one at a development endpoint, so test activity never reaches your production systems. See Webhooks.

Test payment values

Use Preczn's test values rather than real payment credentials. You submit one Preczn test card and Preczn translates it into whatever test value your configured connection expects, so the same number works no matter which processor the transaction routes to.

Test credit cards — approved, declined, and debit card numbers.
Test bank accounts — approved, declined, and error account and routing numbers.

Some processors also recognise their own sandbox triggers — specific amounts or values that force a particular outcome. Those are documented on each connection's page.

FAQ

Can I copy my test merchants, plans, or rules into Live mode?

No. The two modes are fully isolated, and there is no copy or promote operation between them. Anything you built in Test mode has to be created again in Live mode.

Treat that as a reason to capture your configuration in code or in a checklist while you build it in Test mode, so recreating it in Live mode is mechanical rather than archaeological.

Do test transactions ever move real money?

No. Test transactions are routed to the processor's sandbox environment, which does not reach the card networks or the ACH network. Nothing settles and no funds move.

Can one API key work in both modes?

No. Mode is fixed at key creation and cannot be changed afterward. Running in both environments means holding two keys, and the prefixes (priv_test_ versus priv_) tell you which is which.

Store them as two separate credentials in your configuration rather than editing one value in place. That is what stops a test key from reaching production, and a live key from being picked up by a test suite.

Why is my merchant, transaction, or key missing?

Almost always because you are in the other mode. A record created in Test mode is invisible in Live mode and vice versa, whether you are reading it in the dashboard or over the API.

Over the API, check the prefix of the key you authenticated with. In the dashboard, check the mode pill in the top navigation bar.

What happens if I use a test card with a live key?

The transaction reaches your processor's production environment, where the test card number is not a valid card, so it will be declined. Test card numbers only work against test-mode merchants and connections.

Do users and permissions have to be set up twice?

No. Dashboard users, their roles, and their permissions are shared across both modes, so a user you add once can work in either. The activity log is shared as well, so it records what your team did in both modes in one place. See User Management.