Listar transações

Lista transações com filtros, ordenação e paginação. Os itens de data são uma projeção leve — diferente do objeto completo retornado por Consultar(/docs/guide/transactions/read). Para os detalhes comp

Visão Geral

Lista transações com filtros, ordenação e paginação. Os itens de data são uma projeção leve — diferente do objeto completo retornado por Consultar. Para os detalhes completos (cliente, itens, recebíveis, etc.), consulte cada transação individualmente.

Precauções

Resposta paginada, com limite máximo de 100 registros por requisição.
Para conjuntos grandes, navegue com limit/offset.
Requisições frequentes podem estar sujeitas a rate limiting.

Requisição

GET /v1/transactions

Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`status`	string	Não	Filtra pelo status	`approved`
`method`	string	Não	Filtra pelo método	`credit`
`id`	string	Não	Filtra por um ID de transação	`tra_1234567890`
`customid`	string	Não	Filtra pelo identificador personalizado	`E5D4C3B2A1`
`referenceid`	string	Não	Filtra pela referência externa	`pedido_loja_9876`
`customerId` (ou `customerid`)	string	Não	Filtra pelo ID do cliente	`cus_1234567890`
`customeremail`	string	Não	Filtra pelo email do cliente	`[email protected]`
`source`	string	Não	Filtra pela origem	`api`
`ipaddress`	string	Não	Filtra pelo IP de origem	`187.85.132.45`
`limit`	integer	Não	Registros por página (1–100, padrão: 20)	`50`
`offset`	integer	Não	Registros a pular (paginação)	`20`
`sort`	string	Não	Ordenação (`ascending`/`descending` ou `campo:asc`/`campo:desc`)	`descending`

Valores Aceitos para status

pending, pre-authorized, approved, failed, refused, canceled, refunded, chargeback, dispute, fraud-review, analyzing, awaiting. O alias unauthorized também é aceito como filtro (compatibilidade).

Valores Aceitos para method

credit, pix, billet. O alias nupay é aceito como filtro (compatibilidade com dados legados); a criação suporta apenas credit/pix/billet.

Exemplos de Requisição

GET /v1/transactions?status=approved&method=credit&limit=50&sort=descending
GET /v1/transactions?status=pending&customerId=cus_1234567890
GET /v1/transactions?status=refunded&limit=20&sort=updatedAt:desc

Resposta

Sucesso (HTTP 200 OK)

Resposta paginada no nível raiz. Os itens de data são projeções leves: amount/originalAmount vêm como strings e fees é um único número (total em centavos).

{
  "offset": 0,
  "limit": 20,
  "total": 142,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 8,
    "offset": { "first": 0, "prev": null, "next": 20, "last": 140 }
  },
  "data": [
    {
      "id": "tra_01hqzvabc",
      "customId": "E5D4C3B2A1",
      "customerId": "cus_987654321",
      "cardBrand": "Mastercard",
      "amount": "9500",
      "originalAmount": "10000",
      "status": "approved",
      "method": "credit",
      "currency": "BRL",
      "fees": 45,
      "approvedAt": "2026-06-15T14:23:45.000Z",
      "updatedAt": "2026-06-15T14:00:30.000Z",
      "createdAt": "2026-06-10T09:15:25.000Z",
      "images": []
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions",
      "method": "GET",
      "description": "List all transactions."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/transactions",
      "method": "POST",
      "description": "Create a new transaction."
    }
  }
}

Atributos da Resposta Paginada

Atributo	Tipo	Descrição
`offset`	integer	Posição inicial dos resultados
`limit`	integer	Máximo de registros retornados
`total`	integer	Total de registros disponíveis
`page.offset.first/prev/next/last`	integer \| null	Offsets de navegação
`page.current`	integer	Página atual
`page.total`	integer	Total de páginas
`hasMore`	boolean	Se há mais resultados
`data`	array	Projeções leves das transações
`merchant`	object	Merchant da conta
`_links`	object	Links HATEOAS (`self`, `create`)

Item de lista (projeção leve em data)

Atributo	Tipo	Descrição
`id`	string	Identificador (`tra_` / `trx_`)
`customId`	string \| null	Identificador personalizado
`customerId`	string \| null	Cliente associado (`cus_*`)
`cardBrand`	string \| null	Bandeira do cartão
`amount`	string	Valor cobrado em centavos (como string)
`originalAmount`	string	Valor original em centavos (como string)
`status`	string	Status atual
`method`	string	Método de pagamento
`currency`	string	Moeda (`BRL`)
`fees`	integer	Total de taxas em centavos
`approvedAt`	string \| null	Data/hora de aprovação (ISO)
`updatedAt`	string	Última atualização (ISO)
`createdAt`	string	Criação (ISO)
`images`	array	URLs de imagens dos itens (geralmente vazia na listagem)

Melhores Práticas

Utilize filtros específicos para reduzir o volume retornado.
Pagine adequadamente para grandes conjuntos.
Para reconciliação, combine filtros de status e período.
Evite consultas muito frequentes para não atingir rate limits.

Listar transações

On this page