Ambiente de Testes (Sandbox)

O Ambiente de Testes (sandbox) permite homologar sua integração sem movimentar dinheiro real e sem envolver o banco. Você usa a mesma API, os mesmos endpoints e o mesmo formato de request/response de produção — a única diferença é a credencial com a qual você se autentica.

Uma cobrança criada no sandbox é roteada para um banco simulado: nenhum PIX ou boleto real é registrado, nenhum valor é movimentado. Você marca a cobrança como paga por conta própria (via simulate-payment) e recebe os mesmos webhooks que receberia em produção — só que carimbados com test: true.

Mesma API, credencial diferente

Não há URL, host ou versão separada para o sandbox. O modo (teste ou produção) é definido pela credencial que emite o access_token. Um token de teste só enxerga/cria dados de teste; um token de produção só enxerga/cria dados de produção. Os dois nunca se cruzam.

1. O que é o sandbox

• Mesma API: https://api.vmixpay.com.br, mesmos endpoints (/v1/charges/boleto, …), mesmo shape de request/response.
• Sem dinheiro real: cobranças de teste vão para um banco simulado. Nenhuma cobrança real é emitida, nenhum valor entra ou sai.
• Isolamento total (in-band): uma credencial de teste jamais lê ou altera dados de produção — e vice-versa. Um acesso cruzado (ler uma cobrança do outro modo) retorna 404 genérico, como se o recurso não existisse.
• Mesma conta/empresa: a credencial de teste pertence à mesma empresa e conta da sua credencial de produção — não é um cadastro à parte.

2. Criar uma credencial de teste

No painel, em /painel/tokens, na seção Ambiente Teste, gere uma credencial de teste. Ela é separada da credencial de produção (mesma empresa/conta) e vem com um client_id/client_secret próprios.

A troca por access_token é idêntica à de produção (OAuth2 client_credentials em POST /v1/oauth/token) — veja Autenticação. O token emitido a partir dessa credencial carrega internamente mode=test e, por isso, opera sempre no sandbox.

Guarde o client_secret de teste como um segredo

Assim como em produção, o client_secret de teste é exibido uma única vez (render-once). Trate-o com o mesmo cuidado — não o exponha em código client-side.

3. Criar uma cobrança de teste

Com o access_token de teste, você cria cobranças exatamente como em produção — os endpoints, headers e corpos são os mesmos descritos em Emitir boleto. Não há parâmetro extra: o modo vem do token.

Criar a cobrança de teste (boleto híbrido)

Cobranças de teste funcionam igual à produção, incluindo os 2 tipos (boleto, boleto_hibrido) — veja Emitir boleto:

curl -X POST https://api.vmixpay.com.br/v1/charges/boleto \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN_DE_TESTE" \
  -H "Idempotency-Key: 7d8e9f0a-1b2c-4d3e-8f9a-0b1c2d3e4f5a" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "boleto_hibrido",
    "valorCents": "199.90",
    "dataVencimento": "2026-07-15",
    "descricao": "Boleto de homologação",
    "pagador": {
      "nome": "Cliente de Teste",
      "documento": "00000000000",
      "tipoPessoa": "PESSOA_FISICA",
      "cep": "85000000",
      "cidade": "Guarapuava",
      "logradouro": "Rua Exemplo",
      "numero": "123",
      "uf": "PR"
    }
  }'

O QR Code de teste não paga de verdade

O qr_code do boleto híbrido de teste é gerado pelo banco simulado — ler esse QR no app de um banco real não paga a cobrança. Para marcá-la como paga, use o simulate-payment abaixo.

4. Simular o pagamento

Como não há pagador real, você marca a cobrança de teste como paga chamando o endpoint de simulação:

POST /v1/charges/{charge_id}/simulate-payment — dispara o mesmo fluxo de pagamento de uma cobrança paga de verdade: a carteira (de teste) é creditada e os webhooks são entregues.

curl -X POST \
  https://api.vmixpay.com.br/v1/charges/9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c/simulate-payment \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN_DE_TESTE"

Depois disso, a cobrança passa a paid (consulte com GET /v1/charges/{charge_id}) e o evento payment.received é enviado aos seus webhooks — com test: true (veja abaixo).

simulate-payment é exclusivo do sandbox

Este endpoint só existe para o modo teste. Chamá-lo sobre uma cobrança de produção (ou com um token de produção) retorna 403 SANDBOX_ONLY. Não há como marcar uma cobrança real como paga por API — isso só acontece com um pagamento real.

5. Webhooks de teste

Eventos de teste são entregues aos mesmos endpoints de webhook que você configurou em /painel/webhooks — não há URL separada para o sandbox. A entrega é assinada com HMAC-SHA256 exatamente como em produção (mesmos headers, mesma verificação — veja Webhooks).

A diferença está no corpo: todo payload carrega um campo booleano test:

• test: true — evento originado no sandbox (uma cobrança de teste).
• test: false — evento real, de produção.

{
  "event": "payment.received",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "charge_id": "9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "account_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "status": "paid",
  "amount": "199.90",
  "test": true,
  "paid_at": "2026-07-04T12:00:00.000Z"
}

Seu consumidor de PRODUÇÃO precisa respeitar o campo test

Como os webhooks de teste chegam no mesmo endpoint dos de produção, o seu consumidor de produção precisa checar o campo test e ignorar (ou tratar em um ramo separado) tudo que vier com test: true.

Se você não fizer isso, uma cobrança simulada vai disparar o seu fluxo real de fulfillment — liberar acesso, dar baixa em pedido, emitir nota — como se fosse um pagamento verdadeiro. Sempre ramifique pelo test antes de processar o evento.

// No handler de webhook, DEPOIS de validar a assinatura HMAC:
if (payload.test === true) {
  // Evento de sandbox: não acione o fulfillment real.
  return res.sendStatus(200);
}
// Somente eventos com test === false seguem para o fluxo de produção.

6. Limitações do sandbox v1

Nem toda a plataforma está disponível em modo teste. As operações abaixo não funcionam com uma credencial de teste — elas retornam 403 SANDBOX_ONLY:

Operação	No sandbox v1
Saque / withdrawal (money-out)	Indisponível — 403 SANDBOX_ONLY.
Carnê / agendamento (charge schedules)	Indisponível — 403 SANDBOX_ONLY.
Envio/reenvio de cobrança por e-mail ao pagador (POST /v1/portal/charges/:id/send-email)	Indisponível — 403 SANDBOX_ONLY.

Além disso:

• E-mails ao pagador não são enviados para cobranças de teste. Uma cobrança de teste criada com send_email: true é criada normalmente, mas o e-mail ao pagador é omitido — o sandbox nunca dispara e-mail a um terceiro real (o pagador não optou por homologação). O mesmo vale para o lembrete de vencimento automático. Para validar o fluxo de notificação, use os webhooks (que chegam com test: true no seu próprio endpoint). Um aviso de falha de webhook de um evento de teste vem marcado com [TESTE/SANDBOX] no tipo do evento.
• O saldo exibido no painel e os relatórios administrativos refletem apenas produção (live) — os créditos de teste não aparecem neles. A carteira de teste é isolada e serve só para validar o fluxo de crédito via webhook/consulta.

Pronto para produção

Quando a homologação terminar, troque a credencial de teste pela de produção (o mesmo código, apenas outro client_id/client_secret). Nada mais muda no seu integrador — só o token deixa de carregar mode=test.