Cobranças

POST /api/v1/charges

Cria uma nova cobrança PIX e retorna o QR Code e código Copia e Cola.

Headers

| Header | Obrigatório | Descrição | |---|---|---| | x-api-key | Sim | Sua API Key (sk_live_... ou sk_test_...) | | Content-Type | Sim | application/json |

Requisição

  -H "x-api-key: $CYRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.90,
    "clientName": "Maria Souza",
    "clientDoc": "123.456.789-00",
    "description": "Plano Mensal"
  }'

Parâmetros do body

| Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | amount | number | Sim | Valor em reais. Mínimo: 0.01 | | clientName | string | Não | Nome do pagador | | clientDoc | string | Não | CPF ou CNPJ do pagador | | description | string | Não | Descrição da cobrança |

Resposta 201 Created

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

Campos da resposta

| Campo | Tipo | Descrição | |---|---|---| | transactionId | string | ID interno da transação na Cyrus | | txid | string | TXID PIX único gerado pelo banco | | qrCode | string | Código EMV Copia e Cola | | qrCodeBase64 | string | Imagem PNG do QR Code em Base64 | | expiresAt | string | ISO 8601 — data/hora de expiração | | amount | number | Valor bruto da cobrança | | fees.feeAmount | number | Taxa total cobrada (gateway + margem) | | fees.gatewayFeeAmount | number | Parte repassada ao gateway bancário | | fees.adminMargin | number | Margem da plataforma Cyrus | | fees.netAmount | number | Valor líquido que o merchant recebe |

Como exibir o QR Code

<img
  src="data:image/png;base64,{qrCodeBase64}"
  alt="Escaneie para pagar"
  width="240"
/>
 
<!-- Botão Copia e Cola -->
<button onclick="navigator.clipboard.writeText('{qrCode}')">
  Copiar código PIX
</button>

Erros possíveis

| Código HTTP | Mensagem | Causa | |---|---|---| | 400 | Invalid JSON body | Body malformado | | 401 | Unauthorized | API Key ausente ou inválida | | 422 | amount must be a positive number | Valor ausente ou ≤ 0 | | 502 | Failed to create charge | Falha na comunicação com o gateway |