Transações

GET /api/v1/transactions

Retorna uma lista paginada de transações do merchant autenticado.

Headers

| Header | Obrigatório | Descrição | |---|---|---| | x-api-key | Sim | Sua API Key |

Requisição

  -H "x-api-key: $CYRUS_API_KEY"

Parâmetros de query

| Parâmetro | Tipo | Padrão | Descrição | |---|---|---|---| | page | number | 1 | Número da página | | limit | number | 20 | Itens por página (máx: 100) | | type | string | — | Filtra por tipo: deposit, withdrawal, payment | | status | string | — | Filtra por status: pending, completed, failed, refunded | | startDate | string | — | Data de início — formato YYYY-MM-DD | | endDate | string | — | Data de fim — formato YYYY-MM-DD |

Resposta 200 OK

  "data": [
    {
      "id": "cm1abc123def456",
      "type": "deposit",
      "status": "completed",
      "amount": 99.90,
      "clientName": "Maria Souza",
      "clientDocument": "123.456.789-00",
      "pixKey": null,
      "txid": "E1234567820240115120000000000001",
      "endToEndId": "E1234567820240115120000000000001",
      "feeAmount": 0.33,
      "gatewayFeeAmount": 0.13,
      "netAmount": 99.57,
      "createdAt": "2024-01-15T12:00:00.000Z",
      "updatedAt": "2024-01-15T12:08:33.000Z"
    }
  ],
  "total": 143,
  "page": 1,
  "limit": 20,
  "pages": 8
}

Campos de cada transação

| Campo | Tipo | Descrição | |---|---|---| | id | string | ID interno da transação | | type | string | deposit (cobrança recebida), withdrawal (payout enviado), payment (pagamento interno) | | status | string | pending, completed, failed, refunded | | amount | number | Valor bruto | | clientName | string | null | Nome do cliente | | clientDocument | string | null | CPF/CNPJ do cliente | | pixKey | string | null | Chave PIX de destino (payouts) | | txid | string | null | TXID PIX (cobranças) | | endToEndId | string | null | ID end-to-end PIX (disponível após completed) | | feeAmount | number | Taxa total cobrada | | gatewayFeeAmount | number | Parte repassada ao gateway | | netAmount | number | Valor líquido | | createdAt | string | ISO 8601 — data de criação | | updatedAt | string | ISO 8601 — última atualização |

Campos da paginação

| Campo | Descrição | |---|---| | total | Total de registros que atendem ao filtro | | page | Página atual | | limit | Itens por página retornados | | pages | Total de páginas |

Exemplos de filtro

GET /api/v1/transactions?type=deposit&status=completed
 
# Período específico
GET /api/v1/transactions?startDate=2024-01-01&endDate=2024-01-31
 
# Página 2 com 50 itens
GET /api/v1/transactions?page=2&limit=50

Erros possíveis

| Código HTTP | Mensagem | Causa | |---|---|---| | 401 | Unauthorized | API Key ausente ou inválida |