Consulta

Consulte e filtre transações processadas pela plataforma.

Visão Geral

Os endpoints de consulta de transações permitem recuperar resumos de pagamento com suporte a filtros, ordenação e paginação. Cada resumo de transação (Summary) contém os dados do cartão utilizado e os ciclos de transação associados (Cycle).

Endpoint

GET/v1/transactions/summaries

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
cursor	string	—	Token de paginação retornado pela resposta anterior. Omitir na primeira página.
limit	integer	—	Itens por página (padrão: 20, máximo: 100)
order_by	string	—	Campo para ordenação: created_at, acquirer, payment_method, status, amount, card_brand, card_first_digits, card_last_digits
sort	string	—	Direção da ordenação: ASC ou DESC
created_at	string	—	Filtrar por data de criação
acquirer	string	—	Filtrar por adquirente
payment_method	string	—	Filtrar por método de pagamento: credit_card, debit_card, voucher, pix
status	string	—	Filtrar por status da transação
amount	string	—	Filtrar por valor (string decimal, ex.: 150.00)
card_brand	string	—	Filtrar por bandeira do cartão
card_first_digits	string	—	Filtrar pelos primeiros dígitos do cartão
card_last_digits	string	—	Filtrar pelos últimos dígitos do cartão

Response

{
  "metadata": {
    "nextCursor": "d3skoqrr425c54fi9fr1",
    "previousCursor": null,
    "limit": 20
  },
  "data": [
    {
      "acquirer": "pagseguro",
      "amount": "150.00",
      "card": {
        "brand": "visa",
        "expirationMonth": 12,
        "expirationYear": 2028,
        "firstDigits": "411111",
        "holderName": "JOAO SILVA",
        "lastDigits": "1234"
      },
      "currency": "BRL",
      "cycles": [
        {
          "amount": "150.00",
          "authorizationCode": "123456",
          "device": {
            "fingerprintId": "abc123",
            "geolocation": [-23.5505, -46.6333],
            "ipAddress": "192.168.1.1"
          },
          "gatewayTransactionId": "gtw_abc123",
          "responseCode": "00",
          "responseMessage": "Approved",
          "retrievalReferenceNumber": "000001234",
          "status": "approved",
          "systemTraceAuditNumber": "000001",
          "transactionSummaryId": "d3skoqrr425c54fi9fr0",
          "type": "authorization"
        }
      ],
      "gatewayTransactionId": "gtw_abc123",
      "installments": 1,
      "paymentMethod": "credit_card",
      "status": "approved"
    }
  ]
}

Campos da Resposta

Resposta paginada — envelope padrão da plataforma (ver Filtros e Paginação):

Campo	Tipo	Descrição
metadata.nextCursor	string | null	Token para a próxima página. null na última página.
metadata.previousCursor	string | null	Token para a página anterior. null na primeira página.
metadata.limit	integer	Quantidade de itens retornados na página
data	array	Lista de resumos de transação — cada item tem os campos de Summary

Summary

Campo	Tipo	Descrição
acquirer	string	Nome do adquirente que processou a transação
amount	string	Valor da transação como string decimal (ex.: 150.00). Este endpoint usa string decimal; o webhook payment.completed usa objeto {amount, scale}.
card	object	Dados do cartão utilizado (ver CardData)
currency	string	Código da moeda (ex.: BRL)
cycles	array	Ciclos da transação (ver Cycle)
gatewayTransactionId	string	Identificador da transação no gateway
installments	integer	Número de parcelas
paymentMethod	string	Método de pagamento utilizado: credit_card, debit_card, voucher, pix
status	string	Status atual da transação

CardData

Campo	Tipo	Descrição
brand	string	Bandeira do cartão (ex.: visa, mastercard)
expirationMonth	integer	Mês de expiração do cartão
expirationYear	integer	Ano de expiração do cartão
firstDigits	string	Primeiros dígitos do cartão (BIN)
holderName	string	Nome do portador do cartão
lastDigits	string	Últimos dígitos do cartão

Cycle

Campo	Tipo	Descrição
amount	string	Valor do ciclo
authorizationCode	string	Código de autorização do adquirente
device	object	Dados do dispositivo (ver DeviceData)
gatewayTransactionId	string	Identificador da transação no gateway
responseCode	string	Código de resposta do adquirente
responseMessage	string	Mensagem de resposta do adquirente
retrievalReferenceNumber	string	Número de referência de recuperação (RRN)
status	string	Status do ciclo
systemTraceAuditNumber	string	Número de auditoria de rastreamento do sistema (STAN)
transactionSummaryId	string	Identificador do resumo de transação associado
type	string	Tipo do ciclo (ex.: authorization, capture, refund)

DeviceData

Campo	Tipo	Descrição
fingerprintId	string	Identificador de fingerprint do dispositivo
geolocation	array	Coordenadas geográficas [latitude, longitude]
ipAddress	string	Endereço IP do dispositivo