Sandbox

Visão geral

O ambiente sandbox é uma réplica completa do ambiente de produção, com as mesmas APIs, respostas e eventos — mas sem efeitos financeiros reais.

Use o sandbox para:

• Desenvolver e testar sua integração antes de ir a produção
• Simular diferentes cenários (pagamento bem-sucedido, falha, expiração)
• Rodar testes automatizados em CI/CD

Configuração

1. URL base: https://sandbox.api.cyrus.com/v1
2. API Key: Use uma chave com prefixo sk_sandbox_ (gere no painel em Configurações → API Keys)

CYRUS_API_KEY=sk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CYRUS_API_URL=https://sandbox.api.cyrus.com/v1

Comportamento automático

No sandbox, transações são processadas automaticamente após um curto delay:

| Operação | Delay | Evento disparado | |---|---|---| | POST /v1/charges | ~3 segundos | charge.paid | | POST /v1/payments | ~2 segundos | payment.sent |

Isso significa que você pode testar o fluxo completo — incluindo recebimento de webhooks — sem intervenção manual.

Saldo sandbox

O saldo no sandbox é fixo em R$ 10.000,00 e nunca é debitado. Você pode:

• Testar pagamentos de qualquer valor dentro desse limite
• Verificar o saldo com GET /v1/balance (sempre retorna 10000.00 no sandbox)
• Não se preocupar em "esgotar" o saldo

Chaves PIX no sandbox

Qualquer string é aceita como chave PIX, inclusive valores fictícios:

• teste@exemplo.com ✓
• 000.000.000-00 ✓
• chave-qualquer-123 ✓

A validação de formato é aplicada normalmente (e-mail deve ter @, CPF deve ter 11 dígitos, etc.), mas não há verificação se a chave existe na base do Banco Central.

Testando webhooks localmente

Para receber webhooks em desenvolvimento local, use um serviço de tunelamento:

# Instale ngrok: https://ngrok.com
ngrok http 3000
 
# Use a URL gerada para registrar o webhook:
# https://abc123.ngrok.io/webhooks/cyrus

# Instale cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/local/
cloudflared tunnel --url http://localhost:3000

Em seguida, registre o webhook com a URL do tunnel:

  -H "X-API-Key: $CYRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/webhooks/cyrus",
    "events": ["charge.paid", "payment.sent"]
  }'

Testes automatizados

Exemplo de suite de testes com Jest e a API sandbox:

  it('deve criar e confirmar uma cobrança', async () => {
    // Cria a cobrança
    const createRes = await api.post('/charges', {
      amount: 50.00,
      description: 'Teste automatizado',
    })
    expect(createRes.data.status).toBe('PENDING')
 
    const { txid } = createRes.data
 
    // Aguarda processamento automático do sandbox (~3s)
    await new Promise(r => setTimeout(r, 4000))
 
    // Verifica status
    const checkRes = await api.get(`/charges/${txid}`)
    expect(checkRes.data.status).toBe('COMPLETED')
  }, 10000)
})

Diferenças em relação à produção

| Aspecto | Sandbox | Produção | |---|---|---| | Dinheiro real | Não | Sim | | Saldo debitado | Não | Sim | | Taxa cobrada | Não | R$ 0,33 | | Tempo de processamento | ~2–3s (automático) | Depende do banco | | Validação de chave PIX | Formato apenas | Banco Central | | Webhooks | Funcionais | Funcionais | | Rate limit | 100 req/min | 100 req/min |

Indo para produção

Quando sua integração estiver pronta:

1. Gere uma API Key sk_live_ no painel
2. Atualize a variável de ambiente CYRUS_API_KEY
3. Atualize a URL base para https://api.cyrus.com/v1
4. Registre novamente seus webhooks com URLs de produção
5. Realize uma transação de teste com valor mínimo para validar