Asynchronous Events

The most important information for integrators are the event messages sent via webhooks during changes of the transaction lifecycle. These events are sent to the WebhookURL informed on any payment request.


Payments Webhook Event Payload

The event payload contains a set of attributes that represent the current state of the origin transaction, as presented in the example bellow, that represents a transaction that was just completed.

{
  "id": "4494a26c-4f21-400a-bbe7-cbef6ea7c3c3",
  "transactionState": "Completed",
  "transactionDate": "2023-08-04T14:45:39.150Z",
  "transactionOrderId": "in-1414870875-158709817091784",
  "transactionOrderDescription": "This is a test order.",
  "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,
  "stateReversedDate": 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"
  }
}

A detailed description is presented next.

Field Name

Type

Transaction State

Description

id

string

All States

An UID that uniquely identifies the event

transactionState

string

All States

The current transaction state as one of: Registered, Cancelled, Completed, Reversed or Error

transactionDate

string

All States

The transaction request date

transactionOrderId

string

All States

The order identification sent by the integrator during the transaction request

transactionReceipt

string

Completed

The transaction receipt URL, once this webhook notifies a complete transaction

transactionReceiptDate

string

Completed

The payment receipt issue date

transactionReceiptVoucher

string

Completed

A payment code provided by the Bank of Emission.

transactionAmount

string

All States

The value of the origin transaction

transactionCharges

string

Completed

The changes applicable to the transaction

transactionType

string

All States

Transaction Type, Credit for Cash In, or Debit for Cash Out

transactionPaymentType

string

All States

Payment type (e.g. PIX).

stateRegisteredDate

string

All States

The date for the intermediary state when the transaction is registered with the bank

stateCancelledDate

string

Canceled

The date of a transaction canceling if the transaction state is Canceled. Empty otherwise

stateCompletedDate

string

Completed

The date of a transaction completion if the transaction state is Completed. Empty otherwise

stateRefundDate

string

None

The date of a transaction refund if the transaction state is Refunded. Empty otherwise.

  • *Note**: Refund state is included in the API but can not be reached. If you have doubts, please read the discussion about refunds in the transaction lifecycle section.

stateReversedDate

string

Reversed

The date of a transaction rollback if the transaction state is Reversed. Empty otherwise.

  • *Note**: Rollback state only applies to transactions in intermediate states, not transactions in final state.

stateErrorDate

string

Error

The date of a transaction error if the transaction state is Error. Empty otherwise

stateErrorCause

string

Error

A key for an error description if the state is Error. Empty otherwise.
For a full list of errors, please refer to our Errors Identifiers in the Platform Errors guide.

webhookUrl

string

All States

The Webhook notification URL

payer.name

string

Completed

The account owner name

payer.taxNumber

string

Completed

The account owner document number

payer.bankCode

string

Completed

The payer bank code as defined by the Central Bank authority in Brazil

payer.bankIspb

string

Completed

A payer six-digit code used to uniquely identify payment institutions in Brazil (if available)

payer.bankName

string

Completed

The payer institution name (if available)

payer.accountAgency

string

Completed

The payer bank account agency (if available)

payer.accountNumber

string

Completed

The payer bank account number (if available)

payer.accountDigit

string

Completed

The payer bank account verification digit (if available)

payer.accountType

string

Completed

A text with one of the following: CheckingAccount, SavingsAccount or SalaryAccount (if available)

recipient.name

string

Completed

The recipient account owner name

recipient.taxNumber

string

Completed

The account owner document number

recipient.bankCode

string

Completed

The recipient bank code as defined by the Central Bank authority in Brazil

recipient.bankIspb

string

Completed

The recipient six-digit code used to uniquely identify payment institutions in Brazil (if available)

recipient.bankName

string

Completed

The recipient institution name (if available)

recipient.accountAgency

string

Completed

The recipient bank agency (if available)

recipient.accountNumber

string

Completed

The recipient bank account number (if available)

recipient.accountDigit

string

Completed

The recipient bank account verification digit (if available)

recipient.accountType

string

Completed

A text with one of the following: CheckingAccount, SavingsAccount or SalaryAccount (if available)

Observation: Failures in the notification delivery trigger backoff retries, active during a 24-hour window. During this period, or after that, integrators can also manually resend the webhook events using the Administrative Portal if desired.

Table of Retries for Webhooks Notifications

RetryInterval
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

Finally, in the API documentation we present webhook payloads examples for each transaction state.