Recebendo Pagamentos

Fluxo de uma cobrança PIX

Sua aplicação        API Cyrus          Pagador
     │                   │                 │
     │  POST /charges     │                 │
     │──────────────────>│                 │
     │   txid + QR Code  │                 │
     │<──────────────────│                 │
     │                   │                 │
     │  Exibe QR Code    │                 │
     │────────────────────────────────────>│
     │                   │  Paga via app  │
     │                   │<───────────────│
     │                   │                 │
     │  Webhook POST     │                 │
     │<──────────────────│                 │
     │    charge.paid    │                 │

Criar uma cobrança

POST /v1/charges

Parâmetros

| Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | amount | number | Sim | Valor em reais (ex: 49.90) | | description | string | Sim | Descrição da cobrança (máx. 500 chars) | | externalId | string | Não | Seu ID de referência (pedido, fatura, etc.) | | expiresIn | number | Não | Expiração em segundos (padrão: 3600) |

Exemplo

curl -X POST https://api.cyrus.com/v1/charges

  -H "X-API-Key: $CYRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "description": "Assinatura Plano Pro — Janeiro 2024",
    "externalId": "sub_jan2024_user123",
    "expiresIn": 1800
  }'

Resposta

{

  "success": true,
  "data": {
    "id": "txn_01hw3k9xyz",
    "txid": "a1b2c3d4e5f60718192a3b4c5d6e7f8g",
    "amount": 49.90,
    "status": "PENDING",
    "description": "Assinatura Plano Pro — Janeiro 2024",
    "externalId": "sub_jan2024_user123",
    "pixCopyPaste": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
    "expiresAt": "2024-01-15T12:30:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

Exibir o QR Code

Como imagem

<img

  src="data:image/png;base64,{qrCodeBase64}"
  alt="Escaneie para pagar"
  width="240"
  height="240"
/>

Copia e Cola

<button onclick=

  Copiar código PIX
</button>

Consultar status de uma cobrança

GET /v1/charges/{txid}

{

  "success": true,
  "data": {
    "txid": "a1b2c3d4e5f60718...",
    "status": "COMPLETED",
    "amount": 49.90,
    "paidAt": "2024-01-15T12:04:22.000Z"
  }
}

Status possíveis

| Status | Descrição | |---|---| | PENDING | Aguardando pagamento | | COMPLETED | Pago e confirmado | | FAILED | Expirou ou falhou | | REFUNDED | Estornado |

Confirmar via webhook (recomendado)

Em vez de fazer polling no status, configure um webhook para receber notificações automáticas:

{

  "event": "charge.paid",
  "data": {
    "id": "txn_01hw3k9xyz",
    "txid": "a1b2c3d4e5f60718...",
    "amount": 49.90,
    "externalId": "sub_jan2024_user123",
    "paidAt": "2024-01-15T12:04:22.000Z"
  }
}

Use o externalId para correlacionar com seus registros internos. Veja o Guia de Webhooks para configurar.

Tratamento de expiração

Cobranças expiradas mudam para status FAILED. Recomendamos:

Gerar uma nova cobrança ao detectar expiração
Invalidar o QR Code antigo na sua interface
Registrar a expiração para métricas de conversão

💡

Defina expiresIn com base no comportamento do seu usuário. Para checkouts, 15–30 minutos costumam funcionar bem. Para faturas, 24–72 horas.