CyrusDocs

Quickstart

Faça sua primeira cobrança PIX com a API Cyrus em menos de 5 minutos.

1. Obtenha sua API Key

Acesse o painel Cyrus, vá em Configurações → API Keys e gere uma nova chave.

Chaves de produção têm prefixo sk_live_ e chaves de teste têm prefixo sk_test_.

⚠

Nunca exponha sua API Key no frontend ou em repositórios públicos. Use variáveis de ambiente.

2. Faça sua primeira cobrança

cURL
curl -X POST https://api.cyrus.com.br/api/v1/charges \
  -H "x-api-key: sk_test_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "clientName": "João Silva",
    "description": "Pedido #1234"
  }'
Node.js
const response = await fetch('https://api.cyrus.com.br/api/v1/charges', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CYRUS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100.00,
    clientName: 'João Silva',
    description: 'Pedido #1234',
  }),
})
 
const data = await response.json()
const { transactionId, txid, qrCode, qrCodeBase64 } = data
Python
import requests
 
response = requests.post(
    'https://api.cyrus.com.br/api/v1/charges',
    json={
        'amount': 100.00,
        'clientName': 'João Silva',
        'description': 'Pedido #1234',
    },
    headers={'x-api-key': 'sk_test_sua_chave_aqui'}
)
 
data = response.json()
transaction_id = data['transactionId']
qr_code_base64 = data['qrCodeBase64']

Resposta 201 Created

{
  "transactionId": "cm1abc123def456",
  "txid": "E1234567820240115120000000000001",
  "qrCode": "00020126580014br.gov.bcb.pix0136...",
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "expiresAt": "2024-01-15T13:00:00.000Z",
  "amount": 100.00,
  "fees": {
    "feeAmount": 0.33,
    "gatewayFeeAmount": 0.13,
    "adminMargin": 0.20,
    "netAmount": 99.67
  }
}

3. Exiba o QR Code para o pagador

O campo qrCodeBase64 contém a imagem PNG pronta para exibição:

<img src=

O campo qrCode é o código Copia e Cola que o pagador pode usar no app bancário.

4. Configure um webhook para receber a confirmação

Registre um endpoint no painel em Configurações → Webhooks. Quando o pagamento for confirmado você receberá:

{
  "event": "transaction.completed",
  "data": {
    "transactionId": "cm1abc123def456",
    "txid": "E1234567820240115120000000000001",
    "endToEndId": "E1234567820240115120000000000001",
    "amount": 100.00,
    "paidAt": "2024-01-15T12:03:42.000Z"
  },
  "timestamp": "2024-01-15T12:03:42.000Z"
}

5. Verifique a autenticidade do webhook

Cada evento inclui o header X-Cyrus-Signature com o secret do webhook cadastrado. Verifique antes de processar:

app.post('/webhooks/cyrus', (req, res) => {
  const signature = req.headers['x-cyrus-signature']
  const secret = process.env.CYRUS_WEBHOOK_SECRET
 
  if (signature !== secret) {
    return res.status(401).json({ error: 'Assinatura inválida' })
  }
 
  const { event, data } = req.body
 
  if (event === 'transaction.completed') {
    // liberar o pedido, enviar e-mail de confirmação, etc.
  }
 
  res.status(200).json({ received: true })
})
✓

Você concluiu sua primeira integração com a API Cyrus!

Próximos passos