Skip to main content
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.
Conta nova começa em teste, sempre. Enquanto o cadastro não passa pela aprovação de produção, 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.
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.

​
Pelo painel

1

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

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

Simule o pagamento

Na cobrança, Simular pagamento. Ela vira paid e o seu webhook recebe o evento charge.paid com simulado: true.
4

Volte para produção

O link Voltar para produção na faixa, ou o mesmo interruptor.
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.

​
Pela API

1

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

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

Simule o pagamento pela API

Em produção esta rota responde 403.

​
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:
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.
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.

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