Listar Eventos

Consulte e filtre eventos de notificações processadas pela plataforma.

Visão Geral

Os endpoints de consulta de eventos permitem recuperar e consultar o histórico completo de notificações processadas pela plataforma. Use este endpoint para auditoria, troubleshooting de webhooks ou análise de eventos específicos. É possível filtrar por status, tipo de evento, data de criação e paginar os resultados.

Endpoint

GET/v1/webhooks/events

Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
status	string	✓	Filtrar por status do evento: pending, failed, processed
type	string	✓	Filtrar por tipo de evento
created_at	string	—	Filtrar por data de criaçã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
sort	string	—	Direção da ordenação: ASC ou DESC

Campos da Resposta

Event

Campo	Tipo	Descrição
id	string	Identificador do evento
createdAt	string	Timestamp de criação do evento (ISO 8601)
updatedAt	string	Timestamp de atualização do evento (ISO 8601)
type	string	Tipo do evento: payment.completed
status	string	Status do evento: pending, failed, processed
data	object	Dados da transação associada ao evento (ver Data)

Data

Campo	Tipo	Descrição
terminalId	string	Identificador do terminal
merchantId	string	Identificador do estabelecimento
acquirerName	string	Nome do adquirente/provedor, ex: pagseguro
transactionType	string	Um dos seguintes: authorization, pre_authorization, capture, void, reversal
transactionStatus	string	Um dos seguintes: pending, approved, denied
terminalSerialNumber	string	Número de série do terminal
merchantTaxId	string	Documento fiscal do estabelecimento
acquirerMerchantIdentifier	string	Identificador do estabelecimento no adquirente
acquirerTerminalIdentifier	string	Identificador do terminal no adquirente
currency	string	Código de moeda ISO 4217 (ex: BRL)
amount	integer	Valor da transação em centavos
paymentMethod	string	Um dos seguintes: credit_card, debit_card, pix
installments	integer	Número de parcelas; pode ser null para pagamentos sem parcelamento
installmentInterest	boolean	Se as parcelas cobram juros; pode ser null se não aplicável
authorizationCode	string	Código de autorização do adquirente; pode ser null para status pending/denied
productAid	string	EMV Application Identifier (AID); null para métodos não-EMV ou não-cartão
retrievalReferenceNumber	string	RRN/NSU do adquirente; pode ser null dependendo do provedor/estado
acquirerResponseCode	string	Código de resposta ABECS; pode ser null quando não fornecido
cardData	object	Detalhes do cartão para pagamentos com cartão; null para pix (ver CardData)
terminalData	object	Informações do terminal/dispositivo; campos individuais podem ser null (ver TerminalData)
metadata	object	Metadados arbitrários chave-valor (pode estar vazio)

CardData

Campo	Tipo	Descrição
captureMethod	string	Método de captura do cartão
holderName	string	Nome do titular; pode ser null se indisponível
cardBrand	string	ex: visa, mastercard; pode ser null
bin	string	Primeiros 6-8 dígitos; pode ser null
last4	string	Últimos 4 dígitos; pode ser null

TerminalData

Campo	Tipo	Descrição
navigationMethod	string	ex: wifi, 4g, 5g; pode ser null
networkSsid	string	SSID da Wi-Fi
simSerialNumber	string	SIM ICCID
simApnData	string	Informações de APN
ipAddress	string	Endereço IP do terminal
latitude	number	Coordenada de latitude
longitude	number	Coordenada de longitude

Request

curl -X GET https://yby-dev.positivolabs.com.br/v1/webhooks/events \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "status=processed" \
  --data-urlencode "type=payment.completed" \
  --data-urlencode "limit=20" \
  --data-urlencode "order_by=created_at" \
  --data-urlencode "sort=DESC"

Resposta

{
  "metadata": {
    "cursor": "d3skoqrr425c54fi9fr0",
    "limit": 20
  },
  "data": [
  {
    "id": "d3skoqrr425c54fi9fr0",
    "createdAt": "2025-10-22T21:28:11.436914699Z",
    "updatedAt": "2025-10-22T21:28:11.436914699Z",
    "type" : "payment.completed",
    "status" : "processed",
    "data": {
      "terminalId": "d3e7s9br425c0klkg9r0",
      "merchantId": "69349310-aafb-4dc2-a361-fa2af30179a8",
      "acquirerName": "pagseguro",
      "transactionType": "pre_authorization",
      "transactionStatus": "denied",
      "terminalSerialNumber": "PST09732089",
      "merchantTaxId": "00.000.000/0001-00",
      "acquirerMerchantIdentifier": "CF20251125",
      "acquirerTerminalIdentifier": "TL1534",
      "currency": "BRL",
      "amount": 123,
      "paymentMethod": "credit_card",
      "installments": 12,
      "installmentInterest": false,
      "authorizationCode": "AUH000",
      "productAid": "A0000000041010000000000000000000",
      "retrievalReferenceNumber": "221022182812",
      "acquirerResponseCode": "51",
      "cardData": {
        "captureMethod": "typed",
        "holderName": "Jose Matias",
        "cardBrand": "visa",
        "bin": "424242",
        "last4": "3456"
      },
      "terminalData": {
        "navigationMethod": "5g",
        "networkSsid": "Yby_WiFi_1234",
        "simSerialNumber": "8955101234567890123",
        "simApnData": "apn=internet.yby.com.br; user=yby-pos; auth=pap",
        "ipAddress": "10.12.34.56",
        "latitude": -23.55052,
        "longitude": -46.63331
      },
      "metadata": {}
    }
  }
  ]
}