Webhooks

Webhooks are used to send real-time notifications about events related to Automatic Pix transactions. Below, we detail the different webhook methods available, including payload examples and descriptions of their fields.

ConfirmPixAutomatic

This webhook is sent when an Automatic Pix confirmation is requested, typically in Journey 1 or 4, so that the Business Unit (BU) can notify the end user and obtain authorization.

For payer

{
    "Method": "ConfirmPixAutomatic",
    "BusinessUnitId": 3225,
    "RecurrenceId": "RN1320335420250912ddfe90d58c2",
    "Description": "Conta",
    "Payer": {
        "Name": "Davi",
        "TaxNumber": "29128883012",
        "BankCode": "450",
        "BankISPB": "13203354",
        "BankBranch": "0001",
        "BankAccount": "203880697",
        "BankAccountDigit": "0"
    },
    "Retry": false,
    "Value": {
        "FinalValue": null,
        "MinimumValue": 2.0
    },
    "Contract": {
        "Identifier": "b6ad966a-54d9-4682-b5ae-bcc6f289752a",
        "Description": "Conta"
    },
    "Data": {
        "Frequency": 0,
        "InitialDate": "2025-09-15",
        "FinalDate": null
    },
    "Receiver": {
        "Name": "Teste Pessoa Pix CNPJ",
        "TaxNumber": "24151460000189"
    },
    "Timestamp": "2025-09-12T16:03:57.4104387-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Description of the transaction or service	String	Yes
Payer	Object containing payer information	Object	Yes
Payer.Name	Payer's name	String	Yes
Payer.TaxNumber	Payer's CPF/CNPJ	String	Yes
Payer.BankCode	Payer's bank code	String	Yes
Payer.BankISPB	Payer's bank ISPB code	String	Yes
Payer.BankBranch	Payer's bank branch code	String	Yes
Payer.BankAccount	Payer's bank account number	String	Yes
Payer.BankAccountDigit	Payer's bank account digit	String	Yes
Retry	Indicates if the recurrence can have retries	Boolean	Yes
Value	Object containing value-related information	Object	Yes
Value.FinalValue	Transaction value	String	Conditional
Value.MinimumValue	Minimum allowed value for the transaction	String	Conditional
Contract	Object containing contract information	Object	Yes
Contract.Identifier	Contract identifier	String	Yes
Contract.Description	Contract or transaction description	String	Yes
Data	Object containing date-related information	Object	Yes
Data.Frequency	Transaction frequency	Integer	Yes
Data.InitialDate	Transaction start date	String	Yes
Data.FinalDate	Transaction final date	String	Yes
Receiver	Object containing receiver information	Object	Yes
Receiver.Name	Receiver's name	String	Yes
Receiver.TaxNumber	Receiver's CNPJ	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifySchedule

This webhook notifies when a scheduling is created by the receiver.

For receiver

{
    "Method": "NotifySchedule",
    "BusinessUnitId": 3225,
    "RecurrenceId": "RN1320335420250912ae62e9cbe51",
    "Description": "Pix Automático agendado",
    "Details": {
        "ScheduledId": "ec718cb3-201a-47e5-8e1a-c696bf832232",
        "PayerName": "Mariana Holanda",
        "PayerTaxNumber": "***.635.903-**",
        "Value": "1.00",
        "PaymentDate": "2025-09-15"
    },
    "Timestamp": "2025-09-12T13:56:12.8600715-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ScheduledId	Identifier for the scheduled transaction	String	Yes
Details.PayerName	Payer's name	String	Yes
Details.PayerTaxNumber	Payer's CNPJ	String	Yes
Details.Value	Transaction value	String	Yes
Details.PaymentDate	Payment date of the scheduling	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

For payer

{
    "Method": "NotifySchedule",
    "BusinessUnitId": 643,
    "RecurrenceId": "RN1320335420250912ae62e9cbe51",
    "Description": "Pix Automático agendado",
    "Details": {
        "ScheduledId": "ec718cb3-201a-47e5-8e1a-c696bf832232",
        "EntityId": 7794011,
        "ReceiverName": "Isabelle Cruz CNPJ",
        "ReceiverTaxNumber": "82361554000189",
        "Value": "1.00",
        "PaymentDate": "2025-09-15"
    },
    "Timestamp": "2025-09-12T13:56:12.9169924-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ScheduledId	Identifier for the scheduled transaction	String	Yes
Details.EntityId	DocumentNumberId of the created PixOut	Integer	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.ReceiverTaxNumber	Receiver's CNPJ	String	Yes
Details.Value	Transaction value	String	Yes
Details.PaymentDate	Payment date of the scheduling	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifyScheduleError

This webhook notifies when an error occurs while scheduling by the receiver.

For receiver

{
    "Method": "NotifyScheduleError",
    "BusinessUnitId": 643,
    "RecurrenceId": "RN1320335420250912ae62e9cbe51",
    "Description": "Falha ao gerar agendamento por instabilidade no sistema do participante pagador.",
    "Details": {
        "ScheduledId": "64ffef9e-56e3-4eb1-98bb-f275cab0e6b8",
        "PayerName": "Mariana Holanda",
        "PayerTaxNumber": "***.635.903-**",
        "Value": "1.00",
        "PaymentDate": "2025-09-16"
    },
    "Timestamp": "2025-09-12T13:56:45.520907-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ScheduledId	Identifier for the scheduled transaction	String	Yes
Details.PayerName	Payer's name	String	Yes
Details.PayerTaxNumber	Payer's CPF/CNPJ	String	Yes
Details.Value	Transaction value	String	Yes
Details.PaymentDate	Payment date of the scheduling	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifyRecurrenceCanceled

This webhook notifies when a recurrence has been canceled by the receiver.

{
    "Method": "NotifyRecurrenceCanceled",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR2025071517611176B7XLH0W3KBC",
    "Description": "Recorrência cancelada pelo recebedor",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Description": "internet banda larga ventos novos",
        "PendingPayments": "NaiBsj5eCLFhMYcN3FBim6KgoTi2ASj4Tw8",
        "Guidance": "Recorrência cancelada pelo recebedor. Novos agendamentos estarão suspensos"
    },
    "Timestamp": "2025-07-15T11:05:16.939366-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.Description	Description of the service or transaction	String	Yes
Details.PendingPayments	Identifier for pending payments	String	Yes
Details.Guidance	Guidance for the user	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifyScheduleCanceled

This webhook notifies when a scheduling is canceled.

{
    "Method": "NotifyScheduleCanceled",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR20250715703179819P6TN2OUFW8",
    "Description": "Agendamento cancelada",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Description": "Conta",
        "ScheduledId": "12321252341134",
        "Reason": "Cancelamento solicitado pelo usuário recebedor"
    }
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.Description	Description of the service or transaction	String	Yes
Details.ScheduledId	Payment date of the scheduling	String	Yes
Details.Reason	Reason for the scheduling cancellation	String	Yes

NotifyLimit

This webhook is sent when the transaction value exceeds the configured per-transaction limit.

{
    "Method": "NotifyLimit",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR2025071594938451H2W9YMSRQG6",
    "Description": "Valor da transação de Pagamento Pix excede o Limite por transação para essa operação",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Value": 1001.00,
        "Guidance": "Por favor, tente novamente mais tarde ou entre em contato com o recebedor"
    },
    "Timestamp": "2025-07-15T10:57:01.0223579-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.Value	Transaction value that exceeded the limit	Number	Yes
Details.Guidance	Guidance for the user	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifyValueExceed

This webhook is sent when the payment value exceeds the allowed limit for the operation.

{
    "Method": "NotifyValueExceed",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR20250715803986008I2Y4LB9S9O",
    "Description": "Valor do pagamento excede o limite permitido",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Value": 1001.00,
        "Guidance": "Por favor, entre em contato com o recebedor para ajustar o valor"
    },
    "Timestamp": "2025-07-15T10:34:09.8100998-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.Value	Transaction value that exceeded the limit	Number	Yes
Details.Guidance	Guidance for the user	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifyOperationalFailure

This webhook notifies operational failures in payment processing.

{
    "Method": "NotifyOperationalFailure",
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR202507106706383424EJPKFTZ66",
    "Description": "Falha operacional no pagamento",
    "Details": {
        "ReceiverName": "COMPUTADORES OCSIS S/A",
        "Value": 0.01,
        "Guidance": "Por favor, tente novamente mais tarde ou entre em contato com o recebedor"
    },
    "Timestamp": "2025-07-11T09:15:31.7035239-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.Value	Value of the affected transaction	Number	Yes
Details.Guidance	Guidance for the user	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifySuccess

This webhook notifies that the recurrence has been approved.

For receiver

{
    "Method": "NotifySuccess",
    "BusinessUnitId": 3225,
    "RecurrenceId": "RN13203354202509127d62f060156",
    "Description": "Recorrência confirmada",
    "Details": {
        "PayerName": "Davi Brito",
        "PayerTaxNumber": "***.288.830-**"
    },
    "Timestamp": "2025-09-12T15:31:14.3557079-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.PayerName	Payer's name	String	Yes
Details.PayerTaxNumber	Payer's CPF/CNPJ	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

For Payer

{
    "Method": "NotifySuccess",
    "BusinessUnitId": 643,
    "RecurrenceId": "RN1320335420250912ae62e9cbe51",
    "Description": "Processamento da recorrência realizado com sucesso",
    "Details": {
        "ReceiverName": "Isabelle Cruz CNPJ",
        "ReceiverTaxNumber": "82361554000189"
    },
    "Timestamp": "2025-09-12T13:45:10.2862017-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.ReceiverTaxNumber	Receiver's CNPJ	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

NotifyFailure

This webhook notifies that the recurrence has been rejected.

{
    "Method": "NotifyFailure",
    "BusinessUnitId": 643,
    "RecurrenceId": "RN1320335420250912fde73c52a58",
    "Description": "CPF/CNPJ do usuário pagador não localizado ou diferente",
    "Details": {
        "ReceiverName": "Teste Pessoa Pix CNPJ",
        "Guidance": "Por favor, revise os dados do pagador"
    },
    "Timestamp": "2025-09-12T15:20:30.6877204-03:00"
}

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
Description	Event description	String	Yes
Details	Object with additional details	Object	Yes
Details.ReceiverName	Receiver's name	String	Yes
Details.Guidance	Guidance for the user	String	Yes
Timestamp	Event date and time (ISO 8601 format)	String	Yes

ExpiredPixAutomatic

This webhook notifies that the recurrence has expired.

{
    "Method": "ExpiredPixAutomatic",
    "PartnerId": 657,
    "BusinessUnitId": 11665,
    "RecurrenceId": "RR20250715703179819P6TN2OUFW8",
    "ExpirationDate": "2025-08-29",
    "Status": "Expired",
    "Contract": {
      "Identifier": "string",
      "Description": "internet banda larga ventos novos",
      "Debtor": {
        "Name": "Etevaldo MT",
        "TaxNumber": "98905764061"
      },
      "Timestamp": "2025-07-15T11:13:09.2348675-03:00"
    }
  }

Field	Description	Type	Mandatory
Method	Method or action of the webhook	String	Yes
BusinessUnitId	Business unit identifier	Integer	Yes
RecurrenceId	Recurrence identifier	String	Yes
ExpirationDate	Expiration date of the recurrence	String	Yes
Status	Status of the recurrence	String	Yes
Contract	Object with contract details	Object	Yes
Contract.Identifier	Contract identifier	String	Yes
Contract.Description	Contract description	String	Yes
Contract.Debtor	Object with debtor details	Object	Yes
Contract.Debtor.Name	Debtor's name	String	Yes
Contract.Debtor.TaxNumber	Debtor's tax number	String	Yes
Contract.Timestamp	Event date and time (ISO 8601 format)	String	Yes