CyrusDocs

Ambientes

Entenda a diferença entre os ambientes sandbox e produção da API Cyrus.

Ambientes disponíveis

A Cyrus oferece dois ambientes isolados: sandbox para testes e produção para operações reais.

| Característica | Sandbox | Produção | |---|---|---| | Base URL | https://sandbox.api.cyrus.com/v1 | https://api.cyrus.com/v1 | | Prefixo da API Key | sk_sandbox_ | sk_live_ | | Dinheiro real | Não | Sim | | Pagamentos automáticos | Sim (em ~3s) | Depende do pagador | | Taxa cobrada | Não | R$ 0,33 por transação | | Rate limit | 100 req/min | 100 req/min |

Sandbox

O ambiente sandbox simula o comportamento completo da API sem movimentar dinheiro real.

Comportamento automático

No sandbox, cobranças e pagamentos são processados automaticamente após alguns segundos:

  • Cobranças (POST /v1/charges): confirmadas automaticamente em ~3 segundos
  • Pagamentos (POST /v1/payments): concluídos automaticamente em ~2 segundos

Você receberá os webhooks correspondentes normalmente, permitindo testar todo o fluxo end-to-end.

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.

Chaves PIX no sandbox

Qualquer chave PIX é aceita no sandbox, inclusive valores fictícios. A validação de formato é aplicada (e-mail, CPF, CNPJ, telefone), mas não há verificação se a chave existe no sistema bancário.

Produção

O ambiente de produção conecta-se diretamente à infraestrutura bancária via MW Bank. Todas as transações são reais e irreversíveis (exceto estornos PIX dentro do prazo).

Ativação

Para usar o ambiente de produção:

  1. Complete o cadastro e verificação KYC no painel Cyrus
  2. Assine o contrato de uso da plataforma
  3. Gere uma API Key com prefixo sk_live_ em Configurações → API Keys

Boas práticas em produção

⚠

Nunca use chaves sk_live_ em ambiente de desenvolvimento, CI/CD ou repositórios públicos.

  • Armazene API Keys em variáveis de ambiente (ex: AWS Secrets Manager, Vault, Doppler)
  • Implemente retry com backoff exponencial para erros 5xx
  • Sempre verifique a assinatura HMAC dos webhooks antes de processar
  • Monitore o endpoint /v1/balance para alertas de saldo baixo

Detectando o ambiente atual

A API retorna o campo environment em algumas respostas para indicar o ambiente ativo:

{
  "success": true,
  "data": {
    "available": 10000.00,
    "environment": "sandbox"
  }
}

No seu código, você pode detectar pelo prefixo da chave:

const isSandbox = process.env.CYRUS_API_KEY?.startsWith('sk_sandbox_')
const baseUrl = isSandbox
  ? 'https://sandbox.api.cyrus.com/v1'
  : 'https://api.cyrus.com/v1'