Skip to main content
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

Test mode

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.

Live mode

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.
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).
  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

{
  "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.

​
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 and API keys, and the API-reference Environments page for the request-level details.

​
Where to next

  • Sign up — create your account and land in test mode.
  • Onboarding — production access + KYB to unlock and transact in live.
  • API environments — how mode is carried on the API.