> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flarepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Ambiente de testes para integrar com a API da Flare Payments sem impactar dados reais

## Visão Geral

A Flare Payments oferece um ambiente **Sandbox** para que você possa testar sua integração de forma segura, sem gerar transações reais ou movimentar saldo.

O Sandbox replica o comportamento da API de produção com algumas diferenças importantes:

| Característica        | Produção                   | Sandbox                        |
| --------------------- | -------------------------- | ------------------------------ |
| Base URL              | `api.flarepayments.com/v1` | `sandbox.flarepayments.com/v1` |
| Prefixo da Secret Key | `sk_live_`                 | `sk_live_test_`                |
| Transações reais      | Sim                        | Não                            |
| Webhooks              | Sim                        | Sim                            |
| Rate limits           | 120 req/min                | 60 req/min                     |

***

## Base URL

```
https://sandbox.flarepayments.com/v1
```

***

## Autenticação

Use sua **API Key de teste** — disponível em **Dashboard > Configurações > API Keys > Ambiente de Teste**.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Chaves de teste (`sk_live_test_`) são rejeitadas em produção. Chaves de produção (`sk_live_`) são rejeitadas no Sandbox.
</Warning>

***

## Simulando Pagamentos

No Sandbox, cobranças PIX são **automaticamente confirmadas** após um intervalo configurável para facilitar os testes.

### Comportamento padrão

| Cenário                      | Comportamento                                   |
| ---------------------------- | ----------------------------------------------- |
| Cobrança criada              | Status `pending` por 10 segundos, depois `paid` |
| `amount: 1` (R\$ 0,01)       | Simula pagamento **instantâneo**                |
| `amount: 99999` (R\$ 999,99) | Simula cobrança que **expira**                  |
| `amount: 66600` (R\$ 666,00) | Simula **falha** no processamento               |

### Exemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sandbox.flarepayments.com/v1/charges \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 1,
      "description": "Teste instantâneo"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://sandbox.flarepayments.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 1,
      description: 'Teste instantâneo'
    })
  });

  const charge = await response.json();
  // Status será "paid" quase imediatamente
  ```
</CodeGroup>

***

## Webhooks no Sandbox

Webhooks funcionam normalmente no Sandbox. Configure sua URL de teste em **Dashboard > Configurações > Webhooks** e selecione o ambiente **Teste**.

Os eventos disparados são idênticos aos de produção:

* `charge.paid` — após confirmação simulada
* `charge.expired` — para cobranças com valor `R$ 999,99`
* `charge.failed` — para cobranças com valor `R$ 666,00`
* `transfer.completed` — saques simulados
* `transfer.failed` — saques com dados inválidos

<Tip>
  Use ferramentas como [webhook.site](https://webhook.site) ou [ngrok](https://ngrok.com) para testar webhooks localmente.
</Tip>

***

## Limites do Sandbox

* Dados são **resetados semanalmente** (domingos à meia-noite UTC)
* Máximo de **1.000 transações** por dia
* Webhooks possuem timeout de **10 segundos**
* QR Codes gerados são **não-funcionais** — não tente escaneá-los

***

## Checklist de Integração

Antes de migrar para produção, verifique:

1. Cobranças criadas e pagamentos confirmados via webhook
2. Polling de status funcionando (`GET /charges/{id}/status`)
3. Saques processados e callbacks recebidos
4. Tratamento de erros implementado (4xx e 5xx)
5. Retentativas de webhook tratadas corretamente

<Note>
  Quando estiver pronto, troque a Base URL e a API Key para produção. Nenhuma outra alteração no código é necessária.
</Note>