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 Consulta

Parâmetro	Tipo	Obrigatório	Descrição
page	integer	—	Número da página
limit	integer	—	Itens por página
order_by	string	—	Campo para ordenação: created_at, acquirer, payment_method, status, amount, card_brand, card_first_digits, card_last_digits
order_direction	string	—	Direção da ordenação: asc, desc
created_at	string	—	Filtrar por data de criação
acquirer	string	—	Filtrar por adquirente
payment_method	string	—	Filtrar por método de pagamento
status	string	—	Filtrar por status da transação
amount	string	—	Filtrar por valor
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

Campos da Resposta

Summary

Campo	Tipo	Descrição
acquirer	string	Nome do adquirente que processou a transação
amount	string	Valor da transação
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
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

Request

curl -X GET https://yby-dev.positivolabs.com.br/v1/transactions/summaries \
  -H "Authorization: Bearer <access_token>"

Resposta

[
  {
    "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"
  }
]

Próximos Passos

• Consultar transação específica
• Tratamento de Erros