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

TentativaIntervalo
11 min e 25 s
24 min e 15 s
39 min e 55 s
421 min e 15 s
543 min e 55 s
61h 30 min
73h
86h
912h
1024h

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