CyrusDocs

Enviando Pagamentos

Como realizar transferências PIX via chave ou QR Code com a API Cyrus.

Pré-requisitos

  • Saldo suficiente na conta Cyrus (verifique com GET /v1/balance)
  • API Key válida no header X-API-Key
⚠

Pagamentos PIX são irreversíveis em produção. Valide sempre o valor e a chave de destino antes de confirmar.

Pagar via chave PIX

POST /v1/payments

Parâmetros

| Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | pixKey | string | Sim | Chave PIX de destino | | pixKeyType | string | Sim | CPF, CNPJ, EMAIL, PHONE, RANDOM | | amount | number | Sim | Valor em reais | | description | string | Não | Descrição da transferência (máx. 500 chars) | | externalId | string | Não | Seu ID de referência |

Exemplo

curl -X POST https://api.cyrus.com/v1/payments 
  -H "X-API-Key: $CYRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "pagamento@empresa.com.br",
    "pixKeyType": "EMAIL",
    "amount": 250.00,
    "description": "Pagamento fornecedor #F-0089",
    "externalId": "payment_F0089"
  }'

Resposta

{
  "success": true,
  "data": {
    "id": "txn_01hw4m...",
    "referenceCode": "pmt_a1b2c3d4",
    "status": "PROCESSING",
    "amount": 250.00,
    "fee": 0.33,
    "netAmount": 249.67,
    "pixKey": "pagamento@empresa.com.br",
    "pixKeyType": "EMAIL",
    "createdAt": "2024-01-15T14:00:00.000Z"
  }
}

Pagar via QR Code

Para pagar com um código Copia e Cola ou QR Code escaneado:

POST /v1/payments/qrcode

Parâmetros

| Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | qrCode | string | Sim | Código Copia e Cola (EMV) completo | | externalId | string | Não | Seu ID de referência |

Exemplo

curl -X POST https://api.cyrus.com/v1/payments/qrcode 
  -H "X-API-Key: $CYRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrCode": "00020126580014br.gov.bcb.pix0136...",
    "externalId": "qr_payment_xyz"
  }'

Consultar status de um pagamento

GET /v1/payments/{referenceCode}
{
  "success": true,
  "data": {
    "referenceCode": "pmt_a1b2c3d4",
    "status": "COMPLETED",
    "amount": 250.00,
    "completedAt": "2024-01-15T14:00:08.000Z"
  }
}

Status possíveis

| Status | Descrição | |---|---| | PENDING | Aguardando início do processamento | | PROCESSING | Em processamento pelo banco | | COMPLETED | Transferência concluída | | FAILED | Falha no processamento | | REFUNDED | Devolvido (estorno PIX) |

Taxas

Cada pagamento tem uma taxa de R$ 0,33. O valor é debitado do saldo, não do valor transferido:

  • Saldo antes: R$ 500,00
  • Pagamento de: R$ 250,00
  • Taxa: R$ 0,33
  • Saldo após: R$ 249,67

Você pode verificar as taxas acumuladas com GET /v1/balance.

Verificar saldo antes de pagar

Sempre verifique o saldo disponível antes de iniciar um pagamento para evitar falhas:

async function sendPayment(pixKey: string, amount: number) {
  // Verifica saldo
  const balanceRes = await fetch('/v1/balance', {
    headers: { 'X-API-Key': process.env.CYRUS_API_KEY }
  })
  const { data } = await balanceRes.json()
 
  if (data.available < amount + 0.33) {
    throw new Error('Saldo insuficiente')
  }
 
  // Realiza pagamento
  return fetch('/v1/payments', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.CYRUS_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ pixKey, pixKeyType: 'EMAIL', amount }),
  })
}

Confirmar via webhook

Configure um webhook para receber payment.sent e payment.failed:

{
  "event": "payment.sent",
  "data": {
    "referenceCode": "pmt_a1b2c3d4",
    "amount": 250.00,
    "externalId": "payment_F0089",
    "completedAt": "2024-01-15T14:00:08.000Z"
  }
}

Veja o Guia de Webhooks para mais detalhes.