Skip to main content
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

AmbienteURL BaseDashboard
Sandboxhttps://sandbox-api.chargefy.iohttps://sandbox.chargefy.io
Produçãohttps://api.chargefy.iohttps://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ãoNúmeroResultado
Visa (aprovado)4111 1111 1111 1111Pagamento aprovado
Mastercard (aprovado)5500 0000 0000 0004Pagamento aprovado
Visa (recusado)4000 0000 0000 0002Pagamento recusado
Visa (insuficiente)4000 0000 0000 9995Saldo insuficiente
Visa (erro de processamento)4000 0000 0000 0119Erro 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árioData de Vencimento
Boleto aprovadoQualquer data futura
Boleto vencidoData 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

FuncionalidadeSandboxProdução
Processamento real de pagamentoSimuladoReal
Transferências/PayoutsSimuladoReal
KYC/VerificaçãoSimplificadoCompleto
Rate limits100 req/min1.000 req/min
Retenção de dados30 diasPermanente
WebhooksFuncionaisFuncionais
Emails transacionaisNão enviadosEnviados

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