Eventos Assíncronos

A informação mais importante para os integradores são as mensagens de evento enviadas via webhooks durante as mudanças do ciclo de vida da transação. Esses eventos são enviados para o Webhook URL informado em qualquer solicitação de pagamento.

Webhook de Pagamentos - Payload do Evento

O payload do evento contém um conjunto de atributos que representam o estado atual da transação de origem, conforme apresentado no exemplo abaixo, que representa uma transação que acabou de ser concluída.

{
  "id": "4494a26c-4f21-400a-bbe7-cbef6ea7c3c3",
  "transactionState": "Completed",
  "transactionDate": "2023-08-04T14:45:39.150Z",
  "transactionOrderId": "in-1414870875-158709817091784",
  "transactionReceipt": "https://api.sandbox.pagfast.com/v1/system/e-receipt/4494a26c-4f21-400a-bbe7-cbef6ea7c3c3/receipt.pdf", 
  "transactionReceiptDate": "2023-08-04T14:45:39.047Z",
  "transactionReceiptVoucher": "D6BE9C802C7846029269C485FE23060C",
  "transactionAmount": "50.000000",
  "transactionType": "Credit",
  "transactionPaymentType": "PIX",
  "stateRegisteredDate": "2023-08-04T14:45:34.332Z",
  "stateCompletedDate": "2023-08-04T14:45:39.150Z",
  "stateCancelledDate": null,
  "stateRefundDate": null,
  "stateErrorDate": null,
  "stateErrorCause": null,
  "webhookUrl": "https://postman-echo.com/post?test=1",
  "payer": {
    "name": "CRISTINA INACIO OLIVEIRA DA CONCEICAO",
    "taxNumber": "14435549603",
    "bankCode": "999",
    "bankName": null,
    "accountAgency": "99999",
    "accountNumber": "99999",
    "accountDigit": "9"
  },
  "recipient": {
    "name": "Pagfast Cobrança e Serviço em Tecnologia Ltda",
    "taxNumber": "46261360000148",
    "bankCode": "999",
    "bankName": "SANDBOX",
    "accountAgency": "99999",
    "accountNumber": "99999",
    "accountDigit": "9"
  }
}

Uma descrição detalhada é apresentada a seguir.

Nome do campo	Tipo	Estado da transação	Descrição
id	string	Todos os Estados	Um UID que identifica exclusivamente o evento
transactionState	string	Todos os Estados	O estado da transação atual como: Registered, Canceled, Completed, Reversed ou Error
transactionDate	string	Todos os Estados	A data de solicitação da transação
transactionOrderId	string	Todos os Estados	A identificação do pedido enviada pelo integrador durante a solicitação da transação
transactionReceipt	string	Completed	A URL de recebimento da transação, uma vez que este webhook notifica uma transação completa
transactionReceiptDate	string	Completed	A data de emissão do recibo de pagamento
transactionReceiptVoucher	string	Completed	Um código de pagamento fornecido pelo Banco de Emissão
transactionAmount	string	Todos os Estados	O valor da transação de origem
transactionCharges	string	Todos os Estados	Os valores de taxas aplicáveis à transação
transactionType	string	Todos os Estados	Tipo de transação, Credit para Cash In ou Debit para Cash Out
transactionPaymentType	string	Todos os Estados	Tipo de pagamento (por exemplo, PIX).
stateRegisteredDate	string	Todos os Estados	A data para o estado intermediário quando a transação é registrada no sistema bancário
stateCancelledDate	string	Cancelled	A data do cancelamento de uma transação se o estado da transação for Cancelado. Vazio caso contrário
stateCompletedDate	string	Completed	A data de conclusão de uma transação se o estado da transação for Concluído. Vazio caso contrário
stateRefundDate	string	Nenhum	A data do reembolso de uma transação se o estado da transação for Reembolsado. Vazio caso contrário. Nota: O estado Refunded existe na API mas não pode ser alcançado. Se você tiver dúvidas, por favor leia a discussão sobre reembolso na seção de ciclo de vida de transação.
stateReversedDate	string	Reversed	A data de uma reversão de transação se o estado da transação for Reversed. Vazio caso contrário. Nota: O estado Reverted só se aplica a transações em estados intermediários, não para transações em estado final.
stateErrorDate	string	Error	A data de um erro de transação se o estado da transação for Erro. Vazio caso contrário
stateErrorCause	string	Error	Uma chave para uma descrição de erro se o estado for Error. Vazio caso contrário. Para uma lista completa de erros, por favor visualize os Identificadores de Erros em nosso guia Erros da Plataforma.
webhookUrl	string	Todos os Estados	A URL de notificação do Webhook
payer.name	string	Completed	O nome do proprietário da conta
payer.taxNumber	string	Completed	O número do documento do proprietário da conta
payer.bankCode	string	Completed	O código do banco pagador conforme definido pela autoridade do Banco Central no Brasil
payer.bankIspb	string	Completed	Um código de seis dígitos do pagador usado para identificar exclusivamente as instituições de pagamento no Brasil (se disponível)
payer.bankName	string	Completed	O nome da instituição pagadora (se disponível)
payer.accountAgency	string	Completed	A agência da conta bancária do pagador (se disponível)
payer.accountNumber	string	Completed	O número da conta bancária do pagador (se disponível)
payer.accountDigit	string	Completed	O dígito de verificação da conta bancária do pagador (se disponível)
payer.accountType	string	Completed	Um texto com um dos seguintes: CheckingAccount, SavingsAccount ou SalaryAccount (se disponível)
recipient.name	string	Completed	O nome do portador da conta
recipient.taxNumber	string	Completed	O número do documento do portador da conta
recipient.bankCode	string	Completed	O código do banco do recebedor, conforme definido pela autoridade do Banco Central no Brasil
recipient.bankIspb	string	Completed	O código de seis dígitos para identificar unicamente o banco do recebedor no Brasil (se fornecido)
recipient.bankName	string	Completed	O nome do banco do recebedor (se fornecido)
recipient.accountAgency	string	Completed	O identificador da agência bancária do recebedor (se fornecido)
recipient.accountNumber	string	Completed	O identificador da conta bancária do recebedor (se fornecido)
recipient.accountDigit	string	Completed	O dígito de verificação da conta bancária do recebedor (se fornecido)
recipient.accountType	string	Completed	Um texto com um dos seguintes valores (se fornecido): CheckingAccount, SavingsAccount ou SalaryAccount

Observação: Falhas na entrega da notificação acionam novas tentativas de retirada, ativas durante uma janela de 24 horas. Durante esse período, ou depois disso, o integradores ou Merchants também podem reenviar manualmente os eventos do webhook usando o Portal Administrativo, se desejarem.

Tabela de Rentativas para Notificações Webhooks

Tentativa	Intervalo
1	1 min e 25 s
2	4 min e 15 s
3	9 min e 55 s
4	21 min e 15 s
5	43 min e 55 s
6	1h 30 min
7	3h
8	6h
9	12h
10	24h

Por fim, na documentação da API, apresentamos exemplos de payloads de webhook para os estados mais importantes de transação.