Pular para o conteúdo principal
Toda organização Caratuva tem dois modos: teste e produção. Eles compartilham uma conta e um host de API, mas seus dados e seus trilhos de pagamento são totalmente isolados. Essa é a divisão teste/produção no estilo Stripe — desenvolva e demonstre no modo teste, movimente dinheiro real no modo produção.

​
O que cada modo faz

Modo teste

Executa o pipeline completo — KYB, KYC do comprador, pagamento, liquidação, webhooks — contra uma instância de pagamento sandbox. KYB e KYC do comprador são aprovados automaticamente, e nenhum dinheiro real é movimentado. Utilizável no momento em que você se cadastra, sem espera de compliance.

Modo produção

Executa contra a instância de pagamento de produção em trilhos reais. Desbloqueado por uma Solicitação de Acesso à Produção aprovada pela Caratuva; em seguida você conclui o KYB de produção antes de poder transacionar. É aqui que o BRL real é liquidado para a sua conta PIX.
O modo teste é um sandbox fiel, não um conjunto de fixtures prontas: ele exercita a instância de pagamento sandbox real, então as respostas, webhooks e transições de estado que você vê no modo teste são as mesmas que verá no modo produção. A diferença é que o sandbox aprova o compliance automaticamente e nunca toca em fundos reais.

​
As sessões começam no modo teste

Uma conta totalmente nova chega no modo teste. Você pode imediatamente executar um fluxo completo de ponta a ponta — fazer o onboarding (aprovado automaticamente), criar uma fatura e pagá-la pelo link do comprador — sem esperar por nada. Recomendamos executar seu primeiro fluxo no modo teste antes de mudar para o modo produção.

​
Trocando de modo

No painel, um indicador de modo fica no topo de cada tela; a troca é um único clique. Por trás dos panos, o painel chama POST /v1/auth/switch-mode, que reemite seu token de sessão com o novo modo. O modo produção só fica selecionável depois que a Caratuva aprova a Solicitação de Acesso à Produção da sua organização (enviada pela página Habilitar produção) — uma aprovação manual distinta do KYB. Depois de mudar para o modo produção, você conclui o KYB de produção na página de Repasses antes de poder transacionar. Pela API, você não troca — o modo é fixado pela chave que você apresenta. Uma chave pk_test_… é sempre teste; uma chave pk_live_… é sempre produção. (Chamar switch-mode com uma chave de API retorna ModeSwitchNotAllowed — emita uma chave do modo que você precisa.)

​
Isolamento de dados

Teste e produção mantêm conjuntos de dados totalmente separados:
  • Faturas são marcadas com o modo em que foram criadas. As listas e relatórios do painel sempre mostram apenas as faturas do modo ativo.
  • Compradores têm escopo por modo — um comprador que completou o KYC no modo teste não o fez no modo produção, e vice-versa. O mesmo e-mail pode existir de forma independente em cada modo.
  • Onboarding/ativação é rastreado por modo. O modo teste é ativado assim que seu KYB de sandbox passa (aprovado automaticamente); o modo produção só é ativado quando o KYB real é aprovado.
Nada criado no modo teste é jamais visível no modo produção, e nada no modo produção vaza para o modo teste.

​
Indo para produção: dois portões

O modo produção tem dois portões distintos, em ordem:
  1. Acesso à produção — uma Solicitação de Acesso à Produção aprovada pela Caratuva desbloqueia a capacidade de mudar para o modo produção (veja Trocando de modo).
  2. KYB de produção (+ destino PIX) — exigido, após a troca, antes que você possa de fato transacionar no modo produção. O modo teste fica aberto desde o cadastro e não exige nenhum dos dois.
Para verificar onde uma organização se encontra no modo ativo, o painel lê: 
GET /v1/onboarding/status

{
  "mode": "live",
  "needsOnboarding": true,
  "tosAccepted": false,
  "kybStatus": null
}
kybStatus é null até que um KYB seja enviado, e então passa a ser um de pending | submitted | verifying | approved | rejected. needsOnboarding é true até que o ambiente daquele modo esteja totalmente ativado. Quando é true, o painel encaminha você para o fluxo de onboarding (Termos → KYB → destino PIX). Veja Onboarding.

​
Mapeamento para chaves de API

As chaves de API carregam o modo em seu prefixo — pk_test_ ou pk_live_ — e o modo da chave determina qual instância de pagamento e conjunto de dados cada requisição acessa. Veja Autenticação e Chaves de API, e a página Ambientes da referência de API para os detalhes no nível de requisição.

​
Para onde ir agora

  • Cadastro — crie sua conta e chegue no modo teste.
  • Onboarding — acesso à produção + KYB para desbloquear e transacionar no modo produção.
  • Ambientes da API — como o modo é carregado na API.