> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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` |

> [!WARNING]
>
> 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](https://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

```bash .env.development theme={null}
CHARGEFY_API_URL=https://sandbox-api.chargefy.io
CHARGEFY_ACCESS_TOKEN=<supabase_jwt>
```

```bash .env.production theme={null}
CHARGEFY_API_URL=https://api.chargefy.io
CHARGEFY_ACCESS_TOKEN=<supabase_jwt>
```

### 4. Usar no código

```typescript theme={null}
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`

> [!TIP]
>
> 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

```bash theme={null}
# 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.