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

# Ambiente de testes

> Teste a integração inteira sem mover dinheiro: um interruptor no painel, ou uma chave de API de teste.

O V4 Pay tem dois ambientes, **teste** e **produção**, e eles vivem no mesmo lugar.
O que decide qual você está usando é a **credencial** — nunca uma configuração no
navegador, que qualquer um poderia alterar.

<Info>
  **Conta nova começa em teste, sempre.** Enquanto o cadastro não passa pela
  [aprovação de produção](/aprovacao-de-producao), o modo teste é o único disponível — e
  ele é completo: chave de teste, cobrança simulada, checkout, webhooks. Integre tudo por
  aqui e mude para produção depois de aprovado.
</Info>

| Como você entra | Como o ambiente viaja                                 |
| --------------- | ----------------------------------------------------- |
| Pelo painel     | no token da sessão (`env`)                            |
| Pela API        | no prefixo da chave: `v4pay_test_…` ou `v4pay_live_…` |

<Info>
  Dados de teste e de produção ficam nas mesmas tabelas, com uma coluna `environment`.
  O filtro é automático: uma requisição de teste **não enxerga** nada de produção, e
  vice-versa. A única exceção são as chaves de API, que aparecem juntas — você precisa
  conseguir revogar uma chave de teste estando em produção.
</Info>

## Pelo painel

<Steps>
  <Step title="Ligue o Modo teste">
    Na barra lateral, o interruptor **Modo teste**. O painel recarrega e passa a mostrar
    uma faixa amarela no topo: tudo o que você vê e cria ali é de teste.
  </Step>

  <Step title="Crie cobranças normalmente">
    Elas não vão ao banco. O código "copia e cola" começa com
    `V4PAY-MODO-TESTE-NAO-PAGAVEL` — um app de banco recusa na hora, de propósito.
  </Step>

  <Step title="Simule o pagamento">
    Na cobrança, **Simular pagamento**. Ela vira `paid` e o seu webhook recebe o evento
    `charge.paid` com `simulado: true`.
  </Step>

  <Step title="Volte para produção">
    O link **Voltar para produção** na faixa, ou o mesmo interruptor.
  </Step>
</Steps>

<Note>
  Não confunda com **Dados de exemplo**, o outro interruptor logo abaixo. Aquele só troca
  o que o navegador mostra, para você conhecer as telas sem ter dados — não fala com a
  API. O **Modo teste** é o ambiente de verdade, do lado do servidor.
</Note>

## Pela API

<Steps>
  <Step title="Crie uma chave de teste">
    Em `POST /api-keys`, informe `"environment": "test"`. A chave nasce com o prefixo
    `v4pay_test_` — dá para ver o ambiente só de olhar.

    ```bash theme={null}
    curl -X POST https://v4pay-api.vercel.app/api-keys \
      -H "Authorization: Bearer SEU_JWT" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Integração em desenvolvimento", "environment": "test" }'
    ```

    Sem `environment`, a chave é de produção (`v4pay_live_`) — e chave de produção só
    existe para conta aprovada: antes disso, o pedido responde `409` com
    `codigo: PRODUCAO_NAO_LIBERADA`. Chaves antigas, sem marca no prefixo, valem como
    produção.
  </Step>

  <Step title="Use como qualquer chave">
    Mesmas rotas, mesmo header. O que muda é o que ela alcança: só dados de teste, e
    cobranças que nunca vão ao banco.
  </Step>

  <Step title="Simule o pagamento pela API">
    ```bash theme={null}
    curl -X POST https://v4pay-api.vercel.app/pix/simulate-payment \
      -H "Authorization: Bearer v4pay_test_SUA_CHAVE" \
      -H "Content-Type: application/json" \
      -d '{ "txid": "9f3a1c2b4d5e6f70…" }'
    ```

    Em produção esta rota responde `403`.
  </Step>
</Steps>

## Trocar o ambiente de uma sessão (JWT)

O painel usa `POST /auth/environment`. Você pode usar também, se estiver integrando
com o token de sessão em vez de chave:

```bash theme={null}
curl -X POST https://v4pay-api.vercel.app/auth/environment \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "test" }'
```

A resposta traz um `accessToken` **novo**, já marcado. Guarde-o no lugar do anterior.
`GET /auth/me` devolve `environment` para você conferir em que modo está, e
`POST /auth/refresh` **preserva** o ambiente ao renovar.

<Warning>
  Para conta **aprovada**, o login começa em produção e entrar em teste é uma escolha
  explícita — de propósito, para ninguém achar que está testando quando não está. Para
  conta **não aprovada**, é o contrário: toda sessão nasce em teste, e pedir
  `environment: live` responde `409` com `codigo: PRODUCAO_NAO_LIBERADA` — veja
  [Aprovação de produção](/aprovacao-de-producao).
</Warning>

## Ambiente de testes do motor de pagamentos

Por padrão, o modo teste usa um emissor interno que não fala com banco nenhum. O
servidor pode ser configurado para apontar o modo teste ao **ambiente de testes do motor de
pagamentos**: aí o QR code é real (só não move dinheiro) e o webhook é entregue pelo
próprio motor. É uma escolha de quem opera o servidor, não do lojista.

## Testar o checkout de ponta a ponta

Um link de pagamento criado em modo teste abre um checkout de teste: a página avisa que nada
ali move dinheiro, e a cobrança emitida nasce no mesmo ambiente do link. No fim, em vez de
pagar o QR, use o botão **Simular pagamento** (ou `POST /checkout/{txid}/simular-pagamento`).
O ambiente de testes dá a cobrança como paga e, dali em diante, tudo acontece como em produção:
o webhook chega, a cobrança vira `paid`, o seu webhook recebe `charge.paid` e a página confirma
sozinha. Em cobrança de produção esse botão não existe e a rota recusa.