Ambiente Sandbox

Como usar o ambiente de testes da Chargefy para desenvolver e testar integrações

O ambiente Sandbox da Chargefy permite testar integrações completas sem processar pagamentos reais. Todas as funcionalidades da API estão disponíveis, incluindo PIX, Cartão de Crédito e Boleto simulados.

​

URLs

Ambiente	URL Base	Dashboard
Sandbox	https://sandbox-api.chargefy.io	https://sandbox.chargefy.io
Produção	https://api.chargefy.io	https://chargefy.io

Tokens de sandbox não funcionam em produção e vice-versa. Cada ambiente tem seus próprios tokens, produtos, clientes e configurações.

​

Configuração

​

1. Criar conta no Sandbox

Acesse sandbox.chargefy.io e crie sua conta de desenvolvimento. O cadastro é independente da conta de produção.

​

2. Gerar token de acesso

No dashboard sandbox, faça login via Supabase Auth para obter um JWT com os escopos necessários.

​

3. Configurar variáveis de ambiente

.env.development

CHARGEFY_API_URL=https://sandbox-api.chargefy.io
CHARGEFY_ACCESS_TOKEN=<supabase_jwt>

.env.production

CHARGEFY_API_URL=https://api.chargefy.io
CHARGEFY_ACCESS_TOKEN=<supabase_jwt>

​

4. Usar no código

import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
  server: process.env.CHARGEFY_API_URL === 'https://api.chargefy.io'
    ? 'production'
    : 'sandbox',
});

​

Dados de Teste

​

Cartão de Crédito

Use estes números de cartão para simular diferentes cenários:

Cartão	Número	Resultado
Visa (aprovado)	4111 1111 1111 1111	Pagamento aprovado
Mastercard (aprovado)	5500 0000 0000 0004	Pagamento aprovado
Visa (recusado)	4000 0000 0000 0002	Pagamento recusado
Visa (insuficiente)	4000 0000 0000 9995	Saldo insuficiente
Visa (erro de processamento)	4000 0000 0000 0119	Erro no processador

Para todos os cartões de teste:

• Nome do titular: qualquer nome
• Validade: qualquer data futura (ex: 12/30)
• CVV: qualquer 3 dígitos (ex: 123)

​

PIX

No sandbox, o PIX é simulado automaticamente:

1. Crie um checkout com método PIX
2. O QR Code é gerado normalmente
3. A confirmação é automática após 5 segundos (sem necessidade de pagamento real)
4. O webhook checkout.updated é disparado com status succeeded

No sandbox, você pode forçar a confirmação do PIX manualmente via API para testes mais rápidos.

​

Boleto

No sandbox, boletos seguem um fluxo simulado:

1. Crie um checkout com método Boleto
2. O código de barras e linha digitável são gerados
3. A compensação é simulada automaticamente após 1 minuto
4. O webhook checkout.updated é disparado com status succeeded

Cenário	Data de Vencimento
Boleto aprovado	Qualquer data futura
Boleto vencido	Data no passado (gera erro 400)

​

Webhooks no Sandbox

Webhooks funcionam normalmente no sandbox. Para testar localmente:

​

Usando ngrok ou similar

# Inicie um tunnel para sua aplicação local
ngrok http 3000

Configure o URL do tunnel como endpoint de webhook no dashboard sandbox:

https://abc123.ngrok.io/api/webhooks/chargefy

​

Verificar entregas

No dashboard sandbox, vá em Configurações → Webhooks e clique no endpoint para ver o histórico de entregas, incluindo payloads e status de resposta.

​

Limitações do Sandbox

Funcionalidade	Sandbox	Produção
Processamento real de pagamento	Simulado	Real
Split e liquidação Zoop	Simulado	Real
KYC/Verificação	Simplificado	Completo
Rate limits	100 req/min	1.000 req/min
Retenção de dados	30 dias	Permanente
Webhooks	Funcionais	Funcionais
Emails transacionais	Não enviados	Enviados

​

Checklist para ir para Produção

Antes de migrar para produção, verifique:

1. Trocar URLs

   Atualize CHARGEFY_API_URL de sandbox para produção em todas as variáveis de ambiente.

2. Trocar tokens

   Gere novos JWTs no dashboard de produção e substitua os tokens sandbox.

3. Atualizar webhooks

   Configure os mesmos endpoints de webhook no ambiente de produção com URLs reais (não ngrok).

4. Completar KYC

   Finalize o processo de verificação de identidade (KYC) no dashboard de produção para habilitar pagamentos reais.

5. Testar end-to-end

   Faça uma transação real de baixo valor (ex: R$ 1,00) para validar todo o fluxo.

6. Monitoramento

   Configure alertas e monitore os primeiros pagamentos de perto.