> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test & live modes

> One account, two isolated environments — a working sandbox and production.

Every Caratuva organization has two modes: **test** and **live**. They share one
account and one API host, but their data and their payment rails are fully
isolated. This is the Stripe-style test/live split — develop and demo in test,
move real money in live.

## What each mode does

<CardGroup cols={2}>
  <Card title="Test mode" icon="flask">
    Runs the full pipeline — KYB, buyer KYC, payment, settlement, webhooks —
    against a **sandbox payment instance**. KYB and buyer KYC auto-approve, and
    no real money moves. Usable the moment you sign up, with no compliance wait.
  </Card>

  <Card title="Live mode" icon="building-columns">
    Runs against the **production payment instance** on real rails. Unlocked by a
    Caratuva-approved **Production Access Request**; you then complete live KYB
    before you can transact. This is where actual BRL settles to your PIX account.
  </Card>
</CardGroup>

Test mode is a faithful sandbox, not a set of canned fixtures: it exercises the
real sandbox payment instance, so the responses, webhooks, and state transitions
you see in test are the same ones you'll see in live. The difference is that the
sandbox auto-approves compliance and never touches real funds.

## Sessions start in test

A brand-new account lands in **test mode**. You can immediately run a full
end-to-end flow — onboard (auto-approved), create an invoice, and pay it through
the buyer link — without waiting on anything. We recommend running your first
flow in test before switching to live.

## Switching modes

**In the dashboard**, a mode indicator sits at the top of every screen; switching
is a single click. Behind the scenes the dashboard calls `POST /v1/auth/switch-mode`,
which re-mints your session token with the new mode. Live mode only becomes
selectable once Caratuva approves your organization's **Production Access Request**
(submitted from the **Enable production** page) — a manual approval distinct from
KYB. After you switch to live, you complete live KYB on the Payout page before you
can transact.

**Over the API**, you don't switch — the mode is fixed by the key you present.
A `pk_test_…` key is always test; a `pk_live_…` key is always live. (Calling
`switch-mode` with an API key returns `ModeSwitchNotAllowed` — issue a key of the
mode you need instead.)

## Data isolation

Test and live keep entirely separate datasets:

* **Invoices** are tagged with the mode they were created in. Dashboard lists and
  reports only ever show the active mode's invoices.
* **Buyers** are scoped per mode — a buyer that completed KYC in test has not
  done so in live, and vice versa. The same email can exist independently in each.
* **Onboarding/activation** is tracked per mode. Test activates as soon as its
  sandbox KYB clears (auto-approved); live activates only when real KYB is
  approved.

Nothing created in test is ever visible in live, and nothing in live leaks into
test.

## Going live: two gates

Live mode has two distinct gates, in order:

1. **Production access** — a Caratuva-approved Production Access Request unlocks the
   ability to switch into live (see [Switching modes](#switching-modes)).
2. **Live KYB (+ PIX destination)** — required, after switching, before you can
   actually transact in live. Test mode is open from signup and needs neither.

To check where an organization stands in the active mode, the dashboard reads:

```
GET /v1/onboarding/status
```

```json theme={null}
{
  "mode": "live",
  "needsOnboarding": true,
  "tosAccepted": false,
  "kybStatus": null
}
```

`kybStatus` is `null` until a KYB is submitted, then one of `pending` | `submitted`
\| `verifying` | `approved` | `rejected`. `needsOnboarding` is `true` until that
mode's environment is fully activated. When it's `true`, the dashboard routes you
into the onboarding flow (Terms → KYB → PIX destination). See [Onboarding](/onboarding).

## Mapping to API keys

API keys carry the mode in their prefix — `pk_test_` or `pk_live_` — and the key's
mode determines which payment instance and dataset every request touches. See
[Authentication](/api-reference/authentication) and
[API keys](/api-reference/api-keys), and the API-reference
[Environments](/api-reference/environments) page for the request-level details.

## Where to next

* [Sign up](/signup) — create your account and land in test mode.
* [Onboarding](/onboarding) — production access + KYB to unlock and transact in live.
* [API environments](/api-reference/environments) — how mode is carried on the API.