Notificação

Os webhooks permitem que você receba notificações em tempo real sobre eventos em sua conta.

Visão Geral

Quando um evento ocorre (por exemplo, um pagamento é concluído), a plataforma envia uma requisição HTTP POST para seu endpoint de webhook configurado.

Configurando Webhooks

1. Informe os endpoints de webhook: sandbox e produção
2. Implemente um handler para receber eventos de webhook

Tipos de Evento

Evento	Descrição
payment.completed	Um pagamento foi concluído com sucesso

Payload de Webhook

payment.completed

Enviado quando uma transação de pagamento é concluída.

{
  "id": "d3skoqrr425c54fi9fr0",
  "eventId": "d3skor3r425c54fi9frg",
  "eventType": "payment.completed",
  "processedAt": "2025-10-22T21:28:11.436914699Z",
  "acquirerName": "pagseguro",
  "transactionType": "pre_authorization",
  "transactionStatus": "denied",
  "terminalId": "d3e7s9br425c0klkg9r0",
  "terminalSerialNumber": "PST09732089",
  "merchantId": "69349310-aafb-4dc2-a361-fa2af30179a8",
  "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": {}
}

Campos do Payload

Campo	Tipo	Descrição
id	string	Identificador da transação
eventId	string	Identificador único do evento de webhook
createdAt	string	Timestamp de criação do evento (ISO 8601)
updatedAt	string	Timestamp de atualização do evento (ISO 8601)
acquirerName	string	Nome do adquirente/provedor, ex: pagseguro, btg_pactual
transactionType	string	Um dos seguintes: authorization, pre_authorization, capture, void, reversal
transactionStatus	string	Um dos seguintes: pending, approved, denied
terminalId	string	Identificador do terminal
terminalSerialNumber	string	Número de série do terminal
merchantId	string	Identificador do estabelecimento
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
cardData.captureMethod	string	Ver Métodos de Captura abaixo
cardData.holderName	string	Nome do titular; pode ser null se indisponível
cardData.cardBrand	string	ex: visa, mastercard; pode ser null
cardData.bin	string	Primeiros 6-8 dígitos; pode ser null
cardData.last4	string	Últimos 4 dígitos; pode ser null
terminalData	object	Informações do terminal/dispositivo; campos individuais podem ser null
terminalData.navigationMethod	string	ex: wifi, 4g, 5g; pode ser null
terminalData.networkSsid	string	SSID da Wi-Fi
terminalData.simSerialNumber	string	SIM ICCID
terminalData.simApnData	string	Informações de APN
terminalData.ipAddress	string	Endereço IP do terminal
terminalData.latitude	number	Coordenada de latitude
terminalData.longitude	number	Coordenada de longitude
metadata	object	Metadados arbitrários chave-valor (pode estar vazio)

Métodos de Captura

• typed - Cartão digitado manualmente
• magstripe - Leitura de tira magnética
• chip - Cartão com chip EMV
• typed_fallback_791 - Fallback digitado (erro 791)
• typed_fallback_821 - Fallback digitado (erro 821)
• magstripe_fallback_801 - Fallback de tira magnética (erro 801)
• magstripe_fallback_811 - Fallback de tira magnética (erro 811)
• contactless_chip - Chip sem contato
• contactless_magstripe - Tira magnética sem contato
• typed_for_recurrence - Digitado para pagamento recorrente