Cada evento tem seu próprio payload (Data), mas compartilha o mesmo envelope, headers, assinatura e política de reenvio — descritos em Estrutura da entrega, Autenticidade e Política de reenvio.

PIX

Domínio	Evento	Descrição
Pix	`Pix.CreditoRecebido`	Um Pix foi recebido e confirmado na conta digital de um cliente.
Pix	`Pix.TransferenciaRealizada`	Resultado do processamento de uma transferência Pix enviada por um cliente — cobre sucesso e falha.
Pix	`Pix.DevolucaoEnviada`	Confirmação do Bacen sobre uma devolução Pix enviada por um cliente (cliente = pagador da devolução).
Pix	`Pix.DevolucaoRecebida`	Devolução Pix processada e creditada na conta de um cliente (cliente = recebedor da devolução).

MED

Domínio	Evento	Descrição
Med	`Med.InfracaoAtualizada`	Uma infração MED (Mecanismo Especial de Devolução) em que a Pinbank é contraparte foi criada ou teve seu status alterado.
Med	`Med.DevolucaoAtualizada`	Uma devolução MED em que a Pinbank é parte contestada foi criada ou teve seu status alterado.

Conta Digital (Gestão de Contas)

Domínio	Evento	Descrição
Conta Digital	`ContaDigital.CadastroPf`	Resultado do cadastro de pessoa física — cobre sucesso e erro.
Conta Digital	`ContaDigital.CadastroPj`	Resultado do cadastro de pessoa jurídica — cobre sucesso e erro.
Conta Digital	`ContaDigital.ContaCriada`	Conta digital (PF ou PJ) criada com sucesso(evento final de sucesso) — payload completo com os dados cadastrais da conta.
Conta Digital	`ContaDigital.ValidacaoCliente`	Resultado da validação de disponibilidade de um dado (CPF, e-mail, celular) — dispara em toda tentativa, sucesso ou falha.
Conta Digital	`ContaDigital.AlteracaoStatus`	Status da conta foi alterado.

Compras (Transacional)

Domínio	Evento	Descrição
Compra	`Compra.TransacaoPendente`	Transação de cartão recém-criada, antes do resultado do adquirente.
Compra	`Compra.TransacaoRealizada`	Transação de cartão aprovada pelo adquirente.
Compra	`Compra.TransacaoNegada`	Transação de cartão negada (pelo adquirente, ou em validação prévia antes de chegar ao adquirente).
Compra	`Compra.TransacaoCancelada`	Transação de cartão cancelada.
Compra	`Compra.TransacaoDesfeita`	Transação de cartão desfeita (estorno no mesmo dia).
Compra	`Compra.TransacaoReembolsada`	Transação de cartão reembolsada.
Compra	`Compra.PixCobrancaPendente`	Transação Pix (via rede de cartão) recém-criada, antes do resultado.
Compra	`Compra.PixTransferenciaRealizada`	Transferência Pix (via rede de cartão) confirmada.
Compra	`Compra.PixTransferenciaNegada`	Transferência Pix (via rede de cartão) negada.
Compra	`Compra.PixCobrancaInvalidada`	QR Code Pix invalidado antes de ser pago — não é transferência revertida, é cobrança abandonada.

Boletos / Títulos

Domínio	Evento	Descrição
Boleto	`Boleto.Registro`	Boleto registrado com sucesso e disponível para pagamento.
Boleto	`Boleto.Liquidacao`	Boleto pago — retorno de cobrança acolhido pela Pinbank.
Boleto	`Boleto.Baixa`	Título baixado — cobre baixa a pedido do cedente, da instituição e por pagamento via Pix.

Eventos

Evento: Pix.CreditoRecebido


Versão atual	`v1`
Descrição	Um Pix foi recebido e confirmado (pago) na conta digital de um cliente Pinbank.
`EntityId` do envelope	Identificador interno do lançamento Pix (string numérica).

O evento é publicado quando um Pix recebido é efetivamente confirmado — não existe, hoje, um evento equivalente para Pix pendente, em processamento ou desfeito posteriormente (devolução — veja Pix.DevolucaoRecebida para esse caso).

{ "TipoEntidade": "Pix.CreditoRecebido", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`)

{
  "IdLancamentoPix": 987654,
  "Valor": 250.50,
  "DataLancamento": "2026-06-30T12:00:00Z",
  "DataGravacao": "2026-06-30T12:00:01Z",
  "Status": "PAGO",
  "IdSistemaOrigem": 4,
  "NsuSistemaOrigem": 111222333,
  "TxId": "TXID001",
  "EndToEndId": "E00000000202606301200BR1234567890",
  "IdQrcode": 5555,
  "Pagador": {
    "PagadorNome": "João da Silva",
    "PagadorCpfCnpj": "12345678901",
    "PagadorIspbPsp": "17079937",
    "PagadorConta": "00012345",
    "PagadorAgencia": "0001",
    "PagadorTipoConta": "CACC"
  },
  "Recebedor": {
    "CodigoCliente": 123456,
    "CodigoCanal": 79,
    "RecebedorCpfCnpj": "98765432100",
    "RecebedorKeyValue": "98765432100"
  }
}

Campo	Tipo	Descrição	Sensível
`IdLancamentoPix`	number	Identificador do lançamento Pix na Pinbank. Mesmo valor de `EntityId`.	não
`Valor`	decimal	Valor do Pix recebido.	não
`DataLancamento`	string (ISO 8601)	Data/hora do lançamento do crédito.	não
`DataGravacao`	string (ISO 8601)	Data/hora de gravação do registro na Pinbank.	não
`Status`	string	Sempre `"PAGO"` neste evento.	não
`IdSistemaOrigem`	number (enum)	Sistema que originou a movimentação do lado pagador: `1`=POS, `2`=iOS, `3`=Android, `4`=GVC, `5`=E-commerce, `6`=E-commerce (webhook), `7`=Transferência Pix, `8`=Transferência Pix interna, `9`=Transferência Pix Itaú, `10`=IO, `11`=E-commerce webhook plus, `12`=Boleto Pix, `13`=Boleto Pix Bet, `14`=OPA Pix.	não
`NsuSistemaOrigem`	number	NSU (número sequencial único) atribuído pelo sistema de origem.	não
`TxId`	string	Identificador da transação Pix (`txid`).	não
`EndToEndId`	string	Identificador fim a fim do Bacen (`E2E`) da transação Pix.	não
`IdQrcode`	number	Identificador do QR Code Pinbank associado, quando o crédito se originou de um QR Code gerado pela Pinbank. `0` quando não houve QR Code.	não
`Pagador.PagadorNome`	string	Nome do pagador.	sim
`Pagador.PagadorCpfCnpj`	string	CPF/CNPJ do pagador — enviado sem máscara.	sim
`Pagador.PagadorIspbPsp`	string	ISPB da instituição financeira do pagador.	não
`Pagador.PagadorConta`	string	Número da conta do pagador.	sim
`Pagador.PagadorAgencia`	string	Agência do pagador.	sim
`Pagador.PagadorTipoConta`	string	Tipo de conta do pagador (ex.: `"CACC"` = conta corrente).	não
`Recebedor.CodigoCliente`	number	Seu código de cliente Pinbank (o recebedor é sempre o cliente Pinbank neste evento).	não
`Recebedor.CodigoCanal`	number	Código do produto contratado com a Pinbank, do recebedor.	não
`Recebedor.RecebedorCpfCnpj`	string	CPF/CNPJ do recebedor (seu cliente) — enviado sem máscara.	sim
`Recebedor.RecebedorKeyValue`	string	Valor da chave Pix utilizada pelo pagador para enviar o crédito (pode ser o próprio CPF, e-mail, celular ou chave aleatória do recebedor).	sim

Nota sobre IdSistemaOrigem: em cenários de pagamento via QR Code Pix Copia e Cola automático, o valor pode ser 6 (E-commerce webhook) mesmo quando a origem técnica é uma transferência Pix. Trate como indicativo do sistema de origem, não como identificador determinístico de fluxo interno.

{
  "EventType": "Pix.CreditoRecebido",
  "EventVersion": "v1",
  "EventId": "550e8400-e29b-41d4-a716-446655440000",
  "EntityId": "987654",
  "OccurredAt": "2026-06-30T12:00:01Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Pix.TransferenciaRealizada


Versão atual	`v1`
Descrição	Resultado do processamento de uma transferência Pix enviada por um cliente Pinbank (pagador).
`EntityId` do envelope	`EndToEndId` (identificador fim a fim Bacen) da transferência.

Importante: apesar do nome, este evento não é exclusivo de sucesso. Ele é disparado para os quatro resultados possíveis do processamento — veja o campo Status abaixo. Trate NEGADO e INVALIDADO como fluxos de falha na sua lógica de negócio, e consulte Rejeicao para o motivo.

Diferente do Pix.CreditoRecebido, aqui o cliente Pinbank é o pagador — os dados de Pagador.CodigoCliente/Pagador.CodigoCanal identificam seu cliente, e o Recebedor pode ser qualquer terceiro, dentro ou fora da Pinbank.

Este evento pode requerer habilitação específica para os seus produtos contratados com a Pinbank. Se ao configurar seu webhook você não começar a receber entregas, confirme com o suporte Pinbank se o evento está habilitado para os seus produtos contratados antes de investigar problemas na sua implementação.

{ "TipoEntidade": "Pix.TransferenciaRealizada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`) — sucesso

{
  "Valor": 250.50,
  "DataPagamento": "2026-06-30",
  "Status": "CONFIRMADO",
  "TxId": "TXID001",
  "EndToEndId": "E00000000202606301200BR1234567890",
  "IdQrcode": null,
  "IdComprovante": 987654,
  "NsuSistemaOrigem": 111222333,
  "Rejeicao": null,
  "Pagador": {
    "CodigoCliente": 123456,
    "CodigoCanal": 79,
    "PagadorNome": "João da Silva",
    "PagadorCpfCnpj": "12345678901",
    "PagadorIspbPsp": "17079937",
    "PagadorConta": "00012345",
    "PagadorAgencia": "0001",
    "PagadorTipoConta": "CACC"
  },
  "Recebedor": {
    "RecebedorNome": "Maria Souza",
    "RecebedorCpfCnpj": "98765432100",
    "RecebedorIspbPsp": "60701190",
    "RecebedorConta": "00098765",
    "RecebedorAgencia": "0002",
    "RecebedorTipoConta": "CACC",
    "RecebedorKeyValue": "maria@example.com"
  }
}

Payload (`Data`) — negado/invalidado

{
  "Valor": 250.50,
  "DataPagamento": "2026-06-30",
  "Status": "NEGADO",
  "TxId": "TXID001",
  "EndToEndId": "E00000000202606301200BR1234567890",
  "IdQrcode": null,
  "IdComprovante": null,
  "NsuSistemaOrigem": 111222333,
  "Rejeicao": {
    "Codigo": "AB03",
    "Origem": "SPI",
    "DescricaoCliente": "Não foi possível concluir o pagamento.",
    "DescricaoTecnica": "Saldo insuficiente na conta do pagador.",
    "Acionavel": false
  },
  "Pagador": { "...": "mesmos campos do exemplo de sucesso" },
  "Recebedor": { "...": "mesmos campos do exemplo de sucesso" }
}

Campo	Tipo	Descrição	Sensível
`Valor`	decimal	Valor da transferência.	não
`DataPagamento`	string (`AAAA-MM-DD`)	Data do pagamento — apenas a data, sem horário.	não
`Status`	string (enum)	Resultado do processamento: `CONFIRMADO`, `ENVIADO`, `NEGADO`, `INVALIDADO`.	não
`TxId`	string	Identificador da transação Pix (`txid`).	não
`EndToEndId`	string	Identificador fim a fim do Bacen (`E2E`). Mesmo valor de `EntityId`.	não
`IdQrcode`	number \| null	Identificador do QR Code Pinbank associado, quando aplicável.	não
`IdComprovante`	number \| null	Identificador do comprovante Pinbank da transferência, quando disponível.	não
`NsuSistemaOrigem`	number	NSU (número sequencial único) atribuído pelo sistema de origem.	não
`Rejeicao`	objeto \| null	Detalhe do motivo, preenchido apenas quando `Status` é `NEGADO` ou `INVALIDADO`; `null` em `CONFIRMADO`/`ENVIADO`.	não
`Rejeicao.Codigo`	string	Código de negócio/Bacen do motivo da rejeição.	não
`Rejeicao.Origem`	string	Sistema que originou a rejeição (ex.: `"SPI"`).	não
`Rejeicao.DescricaoCliente`	string	Descrição amigável, adequada para exibir ao usuário final.	não
`Rejeicao.DescricaoTecnica`	string	Descrição técnica do motivo, para logs/suporte.	não
`Rejeicao.Acionavel`	bool	Se `true`, o cliente pode agir para corrigir e tentar novamente (ex.: saldo insuficiente); se `false`, é um erro definitivo.	não
`Pagador.CodigoCliente`	number	Seu código de cliente Pinbank (pagador).	não
`Pagador.CodigoCanal`	number	Código do produto contratado com a Pinbank, do pagador.	não
`Pagador.PagadorNome`	string	Nome do pagador (seu cliente).	sim
`Pagador.PagadorCpfCnpj`	string	CPF/CNPJ do pagador — sem máscara.	sim
`Pagador.PagadorIspbPsp`	string	ISPB da instituição do pagador.	não
`Pagador.PagadorConta`	string	Conta do pagador.	sim
`Pagador.PagadorAgencia`	string	Agência do pagador.	sim
`Pagador.PagadorTipoConta`	string \| null	Tipo de conta do pagador (ex.: `"CACC"`). Pode não estar presente em todos os casos.	não
`Recebedor.RecebedorNome`	string	Nome do recebedor (pode ser terceiro fora da Pinbank).	sim
`Recebedor.RecebedorCpfCnpj`	string	CPF/CNPJ do recebedor — sem máscara.	sim
`Recebedor.RecebedorIspbPsp`	string	ISPB da instituição do recebedor.	não
`Recebedor.RecebedorConta`	string	Conta do recebedor.	sim
`Recebedor.RecebedorAgencia`	string	Agência do recebedor.	sim
`Recebedor.RecebedorTipoConta`	string	Tipo de conta do recebedor.	não
`Recebedor.RecebedorKeyValue`	string	Chave Pix do recebedor usada no pagamento.	sim

{
  "EventType": "Pix.TransferenciaRealizada",
  "EventVersion": "v1",
  "EventId": "660e8400-e29b-41d4-a716-446655440111",
  "EntityId": "E00000000202606301200BR1234567890",
  "OccurredAt": "2026-06-30T12:00:01Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Pix.DevolucaoEnviada


Versão atual	`v1`
Descrição	Confirmação (aceite ou rejeição) do Bacen sobre uma devolução Pix enviada por um cliente Pinbank — o cliente é o pagador da devolução, por ter sido o recebedor do Pix original.
`EntityId` do envelope	`EndToEndId` da transação de devolução.

Este evento é publicado tanto para devolução aceita quanto rejeitada pelo Bacen — veja Status. Trate RJCT como falha da devolução.

Uma devolução Pix é sempre iniciada pelo lado que recebeu o pagamento original (via PACS.004 ao Bacen) — a Pinbank não publica um evento no momento da solicitação da devolução, apenas na confirmação de seu processamento pelo Bacen.

{ "TipoEntidade": "Pix.DevolucaoEnviada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`)

{
  "EndToEndId": "D00000000202607011500BR1234567890",
  "EndToEndIdOriginal": "E00000000202606301200BR1234567890",
  "Valor": 100.00,
  "Status": "ACCC",
  "MotivoRejeicao": null,
  "IdQrcode": 5555,
  "DataGravacao": "2026-07-01T15:00:01Z",
  "Pagador": {
    "CodigoCliente": 123456,
    "CodigoCanal": 79
  }
}

Campo	Tipo	Descrição	Sensível
`EndToEndId`	string	Identificador fim a fim (`E2E`) Bacen da transação de devolução. Mesmo valor de `EntityId`.	não
`EndToEndIdOriginal`	string	`E2E` do pagamento Pix original que está sendo devolvido.	não
`Valor`	decimal	Valor devolvido nesta transação — pode representar apenas parte do pagamento original (devolução parcial — veja nota abaixo).	não
`Status`	string (enum)	Status Bacen da devolução: `ACCC` (aceita/confirmada) ou `RJCT` (rejeitada).	não
`MotivoRejeicao`	string \| null	Código de motivo retornado pelo Bacen, sem tradução — preenchido apenas quando `Status` é `RJCT`. Consulte a tabela oficial de códigos SPI/Bacen; a Pinbank não valida nem traduz este valor.	não
`IdQrcode`	number	ID do QR Code Pinbank associado ao pagamento original, quando aplicável. `0` quando não houve QR Code.	não
`DataGravacao`	string (ISO 8601)	Data/hora de gravação da confirmação Bacen (PACS.002) recebida pela Pinbank.	não
`Pagador.CodigoCliente`	number	Seu código de cliente Pinbank — o pagador da devolução (quem recebeu o Pix original).	não
`Pagador.CodigoCanal`	number	Código do produto contratado com a Pinbank, do pagador da devolução.	não

Este evento não inclui CPF/CNPJ, conta ou agência de nenhuma das partes — diferente de Pix.CreditoRecebido/Pix.TransferenciaRealizada, o payload de devolução expõe apenas identificadores internos Pinbank e dados da própria transação Pix.

Devolução parcial — não some, acumule

Um mesmo pagamento Pix pode ser devolvido em mais de uma parcela, ao longo de várias entregas distintas, todas referenciando o mesmo EndToEndIdOriginal mas com Valor/EndToEndId diferentes entre si. Não assuma que uma única entrega representa a devolução total do pagamento original — trate Valor como um incremento sobre o total já devolvido para aquele EndToEndIdOriginal, não como substituição.

{
  "EventType": "Pix.DevolucaoEnviada",
  "EventVersion": "v1",
  "EventId": "770e8400-e29b-41d4-a716-446655440222",
  "EntityId": "D00000000202607011500BR1234567890",
  "OccurredAt": "2026-07-01T15:00:01Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Pix.DevolucaoRecebida


Versão atual	`v1`
Descrição	Devolução Pix processada e creditada com sucesso na conta de um cliente Pinbank — o cliente é o recebedor da devolução, por ter sido o pagador do Pix original.
`EntityId` do envelope	`EndToEndId` da transação de devolução.

Este evento só é publicado quando a devolução é processada com sucesso — não existe, hoje, um evento equivalente para devolução rejeitada do lado do recebedor (o cenário de rejeição é coberto pelo lado pagador, em Pix.DevolucaoEnviada).

{ "TipoEntidade": "Pix.DevolucaoRecebida", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`)

{
  "EndToEndId": "D00000000202607011500BR1234567890",
  "EndToEndIdOriginal": "E00000000202606301200BR1234567890",
  "Valor": 100.00,
  "ValorOriginal": 250.50,
  "TipoMoeda": "BRL",
  "InfoEntreUsuarios": "Produto com defeito",
  "DataLancamento": "2026-06-30",
  "IdLpf": 987654,
  "Recebedor": {
    "CodigoCliente": 123456,
    "CodigoCanal": 79
  }
}

Campo	Tipo	Descrição	Sensível
`EndToEndId`	string	Identificador fim a fim (`E2E`) Bacen da transação de devolução. Mesmo valor de `EntityId`.	não
`EndToEndIdOriginal`	string	`E2E` do pagamento Pix original, enviado por seu cliente, que está sendo devolvido.	não
`Valor`	decimal	Valor devolvido nesta transação — pode representar apenas parte do pagamento original (devolução parcial — veja nota abaixo).	não
`ValorOriginal`	decimal	Valor total do pagamento Pix original.	não
`TipoMoeda`	string	Moeda da transação (tipicamente `BRL`).	não
`InfoEntreUsuarios`	string	Campo livre de texto informado na devolução (mensagem entre as partes), quando presente.	possível
`DataLancamento`	string (`AAAA-MM-DD`)	Data do lançamento do pagamento Pix original.	não
`IdLpf`	number	Identificador do lançamento financeiro de crédito gerado pela devolução no extrato do seu cliente.	não
`Recebedor.CodigoCliente`	number	Seu código de cliente Pinbank — o recebedor da devolução (quem enviou o Pix original).	não
`Recebedor.CodigoCanal`	number	Código do produto contratado com a Pinbank, do recebedor da devolução.	não

InfoEntreUsuarios é texto livre preenchido por quem inicia a devolução e pode eventualmente conter dado pessoal digitado livremente — trate como potencialmente sensível na sua política de retenção.
Este evento não inclui CPF/CNPJ, conta ou agência de nenhuma das partes — diferente de Pix.CreditoRecebido/Pix.TransferenciaRealizada, o payload de devolução expõe apenas identificadores internos Pinbank e dados da própria transação Pix.

Devolução parcial — não some, acumule

Um mesmo pagamento Pix pode ser devolvido em mais de uma parcela, ao longo de várias entregas distintas, todas referenciando o mesmo EndToEndIdOriginal mas com Valor diferentes entre si. Trate Valor como incremento sobre o total já devolvido, não como substituição.

{
  "EventType": "Pix.DevolucaoRecebida",
  "EventVersion": "v1",
  "EventId": "880e8400-e29b-41d4-a716-446655440333",
  "EntityId": "D00000000202607011500BR1234567890",
  "OccurredAt": "2026-07-01T15:00:01Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Med.InfracaoAtualizada


Versão atual	`v1`
Descrição	Uma infração MED (Mecanismo Especial de Devolução) em que a Pinbank é contraparte foi criada ou teve seu status alterado.
`EntityId` do envelope	Identificador da infração no DICT/Bacen.

{ "TipoEntidade": "Med.InfracaoAtualizada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`)

{
  "IdTransacao": "E9999901012341234123412345678900",
  "Motivo": "SOLICITACAO_DEVOLUCAO",
  "TipoSituacao": "GOLPE",
  "Situacao": "FECHADA",
  "DataCriacao": "2026-06-30T12:00:00Z",
  "DataUltimaModificacao": "2026-07-02T09:30:00Z",
  "DetalhesRelato": "Cliente reportou golpe via ligação telefônica.",
  "ResultadoAnalise": "Aceita",
  "DetalhesAnalise": "Confirmado extravio de valores; devolução autorizada."
}

Campo	Tipo	Descrição	Sensível
`IdTransacao`	string	Identificador da transação Pix (`txid`) associada à infração.	não
`Motivo`	string (enum)	Motivo da infração. Valores traduzidos: `SOLICITACAO_DEVOLUCAO` (Bacen `REFUND_REQUEST`), `DEVOLUCAO_CANCELADA` (`REFUND_CANCELLED`). Um valor novo do Bacen ainda não mapeado é gravado sem tradução — trate como lista aberta.	não
`TipoSituacao`	string (enum)	Tipo de situação da infração. Valores traduzidos: `GOLPE` (Bacen `SCAM`), `TOMADA_DE_CONTA` (`ACCOUNT_TAKEOVER`), `COACAO` (`COERCION`), `ACESSO_FRAUDULENTO` (`FRAUDULENT_ACCESS`), `OUTRO` (`OTHER`), `DESCONHECIDO` (`UNKNOWN`).	não
`Situacao`	string (enum)	Status da infração no momento da entrega: `ABERTA`, `FECHADA`, `CANCELADA`.	não
`DataCriacao`	string (ISO 8601)	Data/hora de criação da infração.	não
`DataUltimaModificacao`	string (ISO 8601)	Data/hora da última modificação da infração no Bacen.	não
`DetalhesRelato`	string \| null	Texto livre escrito pelo reportador ao criar a infração. `null` quando não informado. Pode conter dado da contraparte digitado pelo reportador.	sim
`ResultadoAnalise`	string \| null (enum)	Resultado da análise da infração: `Aceita` (Bacen `AGREED`) ou `Rejeitada` (Bacen `DISAGREED`). `null` antes da análise ser concluída.	não
`DetalhesAnalise`	string \| null	Texto livre preenchido na análise/reconhecimento da infração. `null` quando não informado. Pode conter dado da contraparte digitado pelo analista.	sim

{
  "EventType": "Med.InfracaoAtualizada",
  "EventVersion": "v1",
  "EventId": "1a2b8400-e29b-41d4-a716-446655441111",
  "EntityId": "E9999901012341234123412345678900",
  "OccurredAt": "2026-07-02T09:30:15Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Med.DevolucaoAtualizada


Versão atual	`v1`
Descrição	Uma devolução MED (Mecanismo Especial de Devolução) em que a Pinbank é parte contestada foi criada ou teve seu status alterado.
`EntityId` do envelope	Identificador da devolução no DICT/Bacen.

{ "TipoEntidade": "Med.DevolucaoAtualizada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`)

{
  "IdTransacao": "E10573521202607271840aUdD5tVPSFc",
  "Motivo": "FRAUDE",
  "Situacao": "FECHADA",
  "DataCriacao": "2026-08-06T15:20:25Z",
  "DataUltimaModificacao": "2026-08-06T18:30:15Z",
  "Valor": 200.00,
  "DetalhesDevolucao": null,
  "ResultadoAnalise": "Rejeitada",
  "DetalhesAnalise": "Não há saldo preservado na conta para devolução dos valores.",
  "MotivoRejeicao": "SEM_SALDO"
}

Campo	Tipo	Descrição	Sensível
`IdTransacao`	string	Identificador da transação Pix (`txid`/E2E) associada à devolução.	não
`Motivo`	string (enum)	Motivo da devolução. Valores traduzidos: `FRAUDE` (Bacen `FRAUD`), `FALHA_OPERACIONAL` (`OPERATIONAL_FLAW`), `PIX_AUTOMATICO` (`PIX_AUTOMATICO`). Um valor novo do Bacen ainda não mapeado é gravado sem tradução — trate como lista aberta.	não
`Situacao`	string (enum)	Status da devolução no momento da entrega: `ABERTA`, `FECHADA`, `CANCELADA`.	não
`DataCriacao`	string (ISO 8601)	Data/hora de criação da devolução.	não
`DataUltimaModificacao`	string (ISO 8601)	Data/hora da última modificação da devolução no Bacen.	não
`Valor`	decimal	Valor solicitado da devolução.	não
`DetalhesDevolucao`	string \| null	Texto livre associado à devolução. `null` quando não informado. Pode conter dado da contraparte digitado pelo solicitante.	sim
`ResultadoAnalise`	string \| null (enum)	Resultado da análise da devolução. Valores traduzidos: `Aceita` (Bacen `TOTALLY_ACCEPTED`), `Aceita Parcialmente` (`PARTIALLY_ACCEPTED`), `Rejeitada` (`REJECTED`). `null` antes da análise ser concluída.	não
`DetalhesAnalise`	string \| null	Texto livre preenchido na análise da devolução. `null` quando não informado. Pode conter dado da contraparte digitado pelo analista.	sim
`MotivoRejeicao`	string \| null (enum)	Motivo pelo qual a devolução foi rejeitada. Valores traduzidos: `SEM_SALDO` (Bacen `NO_BALANCE`), `CONTA_ENCERRADA` (`ACCOUNT_CLOSURE`), `SOLICITACAO_INVALIDA` (`INVALID_REQUEST`), `OUTRO` (`OTHER`), `EXCLUSAO_PARTICIPANTE` (`PARTICIPANT_EXCLUSION`). `null` quando a devolução não foi rejeitada ou a análise ainda não concluiu. Um valor novo do Bacen ainda não mapeado é gravado sem tradução — trate como lista aberta.	não

{
  "EventType": "Med.DevolucaoAtualizada",
  "EventVersion": "v1",
  "EventId": "2b3c8400-e29b-41d4-a716-446655442222",
  "EntityId": "E10573521202607271840aUdD5tVPSFc",
  "OccurredAt": "2026-08-06T18:30:15Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: ContaDigital.CadastroPf


Versão atual	`v1`
Descrição	Resultado do cadastro de uma pessoa física na Conta Digital. Cadastros de pessoa jurídica geram `ContaDigital.CadastroPj`.
`EntityId` do envelope	Código do cliente/MML recém-criado (sucesso) ou código do cliente/CPF já existente (erro).

Este evento cobre sucesso e erro — não existe um EventType separado para falha de cadastro. Diferencie os dois casos por Data.Status ("Cadastrado" ou "Erro") ou Data.Aprovado (true/false) — não existe outro campo de roteamento que distinga sucesso de erro.

{ "TipoEntidade": "ContaDigital.CadastroPf", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`) — sucesso

{
  "CodigoCliente": 123456,
  "CodigoCanal": 101,
  "Documento": "12345678901",
  "Nome": "Cliente Teste",
  "Email": "cliente@pinbank.com",
  "Celular": {
    "Ddi": 55,
    "Ddd": 11,
    "NumeroMascarado": "*****4321"
  },
  "OrigemCadastro": "APP_ANDROID",
  "Status": "Cadastrado",
  "Aprovado": true,
  "CodigoRetorno": 0,
  "DescricaoRetorno": "Sucesso",
  "CadastradoEm": "2026-06-03T18:40:53.0000000Z"
}

Campo	Tipo	Descrição	Sensível
`CodigoCliente`	number	Código MML do cliente recém-criado.	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank, de origem do cadastro.	não
`Documento`	string	CPF, 11 dígitos com zeros à esquerda — sem máscara.	sim
`Nome`	string	Nome completo do cliente — sem máscara.	sim
`Email`	string	E-mail do cliente — sem máscara.	sim
`Celular.Ddi`	number	DDI do celular — sem máscara.	não
`Celular.Ddd`	number	DDD do celular — sem máscara.	não
`Celular.NumeroMascarado`	string	Número do celular mascarado, últimos 4 dígitos visíveis (ex.: `"*****4321"`).	não
`OrigemCadastro`	string (enum)	`APP_IOS` \| `APP_ANDROID` \| `WEB` \| `CADASTRO_LOTE` \| `EXTERNO`.	não
`Status`	string	`"Cadastrado"` neste payload.	não
`Aprovado`	bool	`true` neste payload.	não
`CodigoRetorno`	number	`0` neste payload.	não
`DescricaoRetorno`	string	`"Sucesso"` neste payload.	não
`CadastradoEm`	string (ISO 8601)	Timestamp do momento do cadastro.	não

Payload (`Data`) — erro

{
  "CodigoCliente": 0,
  "CodigoCanal": 101,
  "Documento": "12345678901",
  "Nome": "Cliente Teste",
  "Email": "cliente@pinbank.com",
  "Celular": {
    "Ddi": 55,
    "Ddd": 11,
    "NumeroMascarado": "*****4321"
  },
  "OrigemCadastro": "APP_ANDROID",
  "Status": "Erro",
  "Aprovado": false,
  "CodigoRetorno": 177,
  "DescricaoRetorno": "CPF/CNPJ já cadastrado",
  "MensagemAdicional": null,
  "Etapa": "CadastroPf",
  "OcorridoEm": "2026-06-03T18:40:53.0000000Z"
}

Mesmos campos do payload de sucesso, exceto:

Campo	Tipo	Descrição	Sensível
`CodigoCliente`	number	`0` se o cadastro falhou antes de gerar um cliente.	não
`Status`	string	`"Erro"` neste payload.	não
`Aprovado`	bool	`false` neste payload.	não
`CodigoRetorno`	number	Código de negócio do erro (ex.: `177` = CPF/CNPJ já cadastrado).	não
`DescricaoRetorno`	string	Descrição textual do erro.	não
`MensagemAdicional`	string \| null	Detalhe adicional opcional.	não
`Etapa`	string	`"CadastroPf"` neste payload.	não
`OcorridoEm`	string (ISO 8601)	Timestamp do momento da falha (substitui `CadastradoEm`).	não

Campos que nunca aparecem no payload, em nenhuma das duas variantes: Senha, Rg, NomeMae, Endereco, ReportId.

{
  "EventType": "ContaDigital.CadastroPf",
  "EventVersion": "v1",
  "EventId": "550e8400-e29b-41d4-a716-446655440000",
  "EntityId": "123456",
  "OccurredAt": "2026-06-03T18:40:53.0000000Z",
  "Data": { "...": "ver tabelas acima" }
}

Evento: ContaDigital.CadastroPj


Versão atual	`v1`
Descrição	Resultado do cadastro de uma pessoa jurídica na Conta Digital.
`EntityId` do envelope	Código do cliente recém-criado (sucesso) ou já existente (erro de CNPJ já cadastrado). Quando o cadastro falha antes de gerar um cliente, o CNPJ com 14 dígitos.

Este evento cobre sucesso e erro. Não existe um EventType separado para falha de cadastro. Diferencie os dois casos por Data.Status ("Cadastrado" ou "Erro") ou Data.Aprovado (true/false).
Em caso de sucesso, a Pinbank também publica ContaDigital.ContaCriada para a mesma conta, com o cadastro completo. Assine apenas ContaDigital.CadastroPj se precisar só do resultado do cadastro. Assine ContaDigital.ContaCriada se precisar dos dados cadastrais.

{ "TipoEntidade": "ContaDigital.CadastroPj", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`) — sucesso

{
  "CodigoCliente": 123456,
  "CodigoCanal": 101,
  "Documento": "12345678000199",
  "RazaoSocial": "Empresa Teste Ltda",
  "NomeFantasia": "Empresa Teste",
  "Email": "empresa@pinbank.com",
  "Celular": {
    "Ddi": 55,
    "Ddd": 11,
    "NumeroMascarado": "*****4321"
  },
  "OrigemCadastro": "APP_ANDROID",
  "Status": "Cadastrado",
  "Aprovado": true,
  "CodigoRetorno": 0,
  "DescricaoRetorno": "Sucesso",
  "CadastradoEm": "2026-06-03T18:40:53.0000000Z"
}

Campo	Tipo	Descrição	Sensível
`CodigoCliente`	number	Código do cliente recém-criado. Mesmo valor de `EntityId`.	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank, de origem do cadastro.	não
`Documento`	string	CNPJ, 14 dígitos com zeros à esquerda — sem máscara.	sim
`RazaoSocial`	string	Razão social da empresa.	não
`NomeFantasia`	string	Nome fantasia da empresa.	não
`Email`	string	E-mail da empresa — sem máscara.	sim
`Celular.Ddi`	number	DDI do celular.	não
`Celular.Ddd`	number	DDD do celular.	não
`Celular.NumeroMascarado`	string	Número do celular mascarado, com os últimos 4 dígitos visíveis (ex.: `"*****4321"`).	não
`OrigemCadastro`	string (enum)	`APP_IOS` \| `APP_ANDROID` \| `WEB` \| `CADASTRO_LOTE` \| `EXTERNO`.	não
`Status`	string	`"Cadastrado"` neste payload.	não
`Aprovado`	bool	`true` neste payload.	não
`CodigoRetorno`	number	`0` neste payload.	não
`DescricaoRetorno`	string	`"Sucesso"` neste payload.	não
`CadastradoEm`	string (ISO 8601)	Timestamp do momento do cadastro (UTC).	não

Payload (`Data`) — erro

{
  "CodigoCliente": 0,
  "CodigoCanal": 101,
  "Documento": "12345678000199",
  "RazaoSocial": "Empresa Teste Ltda",
  "NomeFantasia": "Empresa Teste",
  "Email": "empresa@pinbank.com",
  "Celular": {
    "Ddi": 55,
    "Ddd": 11,
    "NumeroMascarado": "*****4321"
  },
  "OrigemCadastro": "EXTERNO",
  "Status": "Erro",
  "Aprovado": false,
  "CodigoRetorno": 177,
  "DescricaoRetorno": "CPF/CNPJ já cadastrado",
  "MensagemAdicional": null,
  "Etapa": "CadastroPj",
  "OcorridoEm": "2026-06-03T18:40:53.0000000Z"
}

Mesmos campos do payload de sucesso, exceto:

Campo	Tipo	Descrição	Sensível
`CodigoCliente`	number	`0` se o cadastro falhou antes de gerar um cliente. Em `CodigoRetorno` `177` (CPF/CNPJ já cadastrado), traz o código do cliente já existente.	não
`Documento`	string	Documento informado no cadastro, com zeros à esquerda até 14 dígitos — sem máscara.	sim
`Status`	string	`"Erro"` neste payload.	não
`Aprovado`	bool	`false` neste payload.	não
`CodigoRetorno`	number	Código de negócio do erro (ex.: `177` = CPF/CNPJ já cadastrado).	não
`DescricaoRetorno`	string	Descrição textual do erro.	não
`MensagemAdicional`	string \| null	Detalhe adicional opcional.	não
`Etapa`	string	`"CadastroPj"` neste payload.	não
`OcorridoEm`	string (ISO 8601)	Timestamp do momento da falha (substitui `CadastradoEm`).	não

Campos que nunca aparecem no payload, em nenhuma das duas variantes: Senha, dados dos sócios, endereço, dados bancários e número de celular sem máscara. Esses dados, quando o cadastro tem sucesso, estão em ContaDigital.ContaCriada.

{
  "EventType": "ContaDigital.CadastroPj",
  "EventVersion": "v1",
  "EventId": "3c4d8400-e29b-41d4-a716-446655443333",
  "EntityId": "123456",
  "OccurredAt": "2026-06-03T18:40:53.0000000Z",
  "Data": { "...": "ver tabelas acima" }
}

Evento: ContaDigital.ContaCriada


Versão atual	`v1`
Descrição	Conta digital (pessoa física ou jurídica) criada com sucesso na Pinbank, com os dados cadastrais completos da conta.
`EntityId` do envelope	Código do cliente recém-criado (`Data.CodigoCliente`).

O evento é publicado uma única vez por conta, depois que o cadastro e o login de acesso são concluídos, na mesma transação que grava o ContaDigital.CadastroPf ou ContaDigital.CadastroPj de sucesso. Não existe variante de erro: cadastros que falham geram apenas o CadastroPf/CadastroPj com Status: "Erro".

O formato de Data muda conforme Data.TipoPessoa ("CNPJ" ou "CPF"). Leia esse campo antes de interpretar o restante do payload.

Atenção — dados pessoais sem máscara: diferente de ContaDigital.CadastroPf/CadastroPj, este evento traz o cadastro completo e sem mascaramento: CPF/CNPJ, CPF do proprietário e dos sócios, RG, nome da mãe, endereço, dados bancários e número de celular completo (Contato.Celular.Numero). Assine este evento só se o seu fluxo realmente precisar desses dados. Aplique a eles a mesma política de retenção e acesso dos seus dados cadastrais.

{ "TipoEntidade": "ContaDigital.ContaCriada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`) — pessoa jurídica (`TipoPessoa: "CNPJ"`)

{
  "CodigoCliente": 123456,
  "CodigoCanal": 101,
  "TipoPessoa": "CNPJ",
  "Documento": "12345678000199",
  "RazaoSocial": "Empresa Teste Ltda",
  "NomeFantasia": "Empresa Teste",
  "DataConstituicao": "2020-01-15",
  "RamoAtividade": 1,
  "RamoAtividade2": 0,
  "RamoAtividade3": 0,
  "Titular": {
    "CpfProprietario": "12345678900",
    "NomeProprietario": "Fulano de Tal"
  },
  "Contato": {
    "NomeContato": "Fulano de Tal",
    "Email": "empresa@pinbank.com",
    "Celular": { "Ddi": 55, "Ddd": 11, "Numero": "987654321" },
    "Comercial": { "Ddd": 11, "Telefone": 33334444, "Ramal": 0 }
  },
  "Endereco": {
    "Cep": "01001000",
    "Logradouro": "Praca da Se",
    "Numero": "100",
    "Complemento": null,
    "Bairro": "Centro",
    "Cidade": "Sao Paulo",
    "Uf": "SP",
    "Pais": "BR"
  },
  "DadosBancarios": {
    "CodigoBanco": null,
    "Agencia": null,
    "ContaCorrente": null,
    "CpfCnpjContaCorrente": null,
    "TipoContaCorrente": null,
    "NomeContaCorrente": null
  },
  "Sociedade": {
    "ListaSociosPj": [
      { "NomeSocio": "Fulano de Tal", "CpfSocio": "12345678900", "PepSocio": false }
    ]
  },
  "OrigemCadastro": "APP_ANDROID",
  "Distribuidor": null,
  "MiniEc": null,
  "MudarSenha": null,
  "ReportId": null,
  "Status": "Criada",
  "CriadaEm": "2026-06-03T18:40:53.0000000Z"
}

Campo	Tipo	Descrição	Sensível
`CodigoCliente`	number	Código do cliente recém-criado. Mesmo valor de `EntityId`.	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank, de origem do cadastro.	não
`TipoPessoa`	string	`"CNPJ"` neste payload.	não
`Documento`	string	CNPJ, 14 dígitos com zeros à esquerda — sem máscara.	sim
`RazaoSocial`	string	Razão social.	não
`NomeFantasia`	string	Nome fantasia.	não
`DataConstituicao`	string (`AAAA-MM-DD`)	Data de constituição da empresa.	não
`RamoAtividade` / `RamoAtividade2` / `RamoAtividade3`	number	Códigos de ramo de atividade. `0` quando não informado.	não
`Titular.CpfProprietario`	string	CPF do proprietário, 11 dígitos — sem máscara.	sim
`Titular.NomeProprietario`	string	Nome do proprietário.	sim
`Contato.NomeContato`	string	Nome do contato da empresa.	sim
`Contato.Email`	string	E-mail — sem máscara.	sim
`Contato.Celular.Ddi` / `Contato.Celular.Ddd`	number	DDI e DDD do celular.	não
`Contato.Celular.Numero`	string	Número do celular completo, sem máscara.	sim
`Contato.Comercial.Ddd` / `.Telefone` / `.Ramal`	number \| null	Telefone comercial.	sim
`Endereco.Cep`	string	CEP, 8 dígitos com zeros à esquerda.	sim
`Endereco.Logradouro` / `.Numero` / `.Complemento` / `.Bairro`	string \| null	Endereço da empresa.	sim
`Endereco.Cidade` / `.Uf` / `.Pais`	string	Cidade, UF e país.	não
`DadosBancarios.CodigoBanco`	number \| null	Código do banco da conta de domicílio.	não
`DadosBancarios.Agencia` / `.ContaCorrente`	string \| null	Agência e conta de domicílio.	sim
`DadosBancarios.CpfCnpjContaCorrente`	string \| null	CPF/CNPJ do titular da conta de domicílio — sem máscara.	sim
`DadosBancarios.TipoContaCorrente`	number \| null	Tipo da conta de domicílio.	não
`DadosBancarios.NomeContaCorrente`	string \| null	Nome do titular da conta de domicílio.	sim
`Sociedade.ListaSociosPj`	array \| null	Sócios da empresa. `null` quando não informado.	—
`Sociedade.ListaSociosPj[].NomeSocio`	string	Nome do sócio.	sim
`Sociedade.ListaSociosPj[].CpfSocio`	string	CPF do sócio — sem máscara.	sim
`Sociedade.ListaSociosPj[].PepSocio`	bool	Indica se o sócio é Pessoa Exposta Politicamente.	sim
`OrigemCadastro`	string (enum)	`APP_IOS` \| `APP_ANDROID` \| `WEB` \| `CADASTRO_LOTE` \| `EXTERNO`.	não
`Distribuidor`	objeto \| null	Distribuidor associado ao cadastro (`DexbId`, `CodProdutoDistribuidor`, `CodClienteDistribuidor`). `null` quando não houver.	não
`MiniEc`	bool \| null	Indica se a conta é um Mini EC.	não
`MudarSenha`	string \| null	Indica se a troca de senha é exigida no primeiro acesso.	não
`ReportId`	string \| null	Identificador de relatório informado no cadastro.	não
`Status`	string	Sempre `"Criada"`.	não
`CriadaEm`	string (ISO 8601)	Timestamp da criação da conta (UTC).	não

Payload (`Data`) — pessoa física (`TipoPessoa: "CPF"`)

{
  "CodigoCliente": 123456,
  "CodigoCanal": 101,
  "TipoPessoa": "CPF",
  "Documento": "12345678901",
  "DocumentoTitular": null,
  "Nome": "Cliente Teste",
  "NomeMae": "Ciclana de Tal",
  "NomePai": null,
  "Sexo": "M",
  "DataNascimento": "1990-05-20",
  "EstadoCivil": 1,
  "Nacionalidade": 1,
  "GrauEscolar": 5,
  "Documento_RG": {
    "Numero": "123456789",
    "Emissor": "SSP",
    "DataEmissao": "2010-03-10"
  },
  "Contato": {
    "Email": "cliente@pinbank.com",
    "Celular": { "Ddi": 55, "Ddd": 11, "Numero": "912345678" },
    "TelefoneResidencial": { "Ddi": 0, "Ddd": 0, "Numero": 0 },
    "TelefoneComercial": { "Ddd": null, "Telefone": 0, "Ramal": null }
  },
  "Endereco": {
    "Cep": "01001000",
    "Logradouro": "Praca da Se",
    "Numero": "100",
    "Complemento": null,
    "Bairro": "Centro",
    "Cidade": "Sao Paulo",
    "Uf": "SP",
    "EstadoResidencia": "SP"
  },
  "CadastroBasico": false,
  "Status": "Criada",
  "CriadaEm": "2026-06-03T18:40:53.0000000Z"
}

Campo	Tipo	Descrição	Sensível
`CodigoCliente`	number	Código do cliente recém-criado. Mesmo valor de `EntityId`.	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank, de origem do cadastro.	não
`TipoPessoa`	string	`"CPF"` neste payload.	não
`Documento`	string	CPF, 11 dígitos com zeros à esquerda — sem máscara.	sim
`DocumentoTitular`	string \| null	CPF do titular (11 dígitos), quando a conta foi aberta vinculada a outro titular. `null` quando não informado.	sim
`Nome` / `NomeMae` / `NomePai`	string \| null	Nome do cliente e filiação.	sim
`Sexo`	string	`"M"` ou `"F"`.	sim
`DataNascimento`	string (`AAAA-MM-DD`)	Data de nascimento.	sim
`EstadoCivil` / `Nacionalidade` / `GrauEscolar`	number	Códigos de estado civil, nacionalidade e escolaridade. `0` quando não informado.	sim
`Documento_RG.Numero` / `.Emissor`	string \| null	Número do RG e órgão emissor.	sim
`Documento_RG.DataEmissao`	string (`AAAA-MM-DD`)	Data de emissão do RG.	sim
`Contato.Email`	string	E-mail — sem máscara.	sim
`Contato.Celular.Ddi` / `Contato.Celular.Ddd`	number	DDI e DDD do celular.	não
`Contato.Celular.Numero`	string	Número do celular completo, sem máscara.	sim
`Contato.TelefoneResidencial.Ddi` / `.Ddd` / `.Numero`	number	Telefone residencial. `0` quando não informado.	sim
`Contato.TelefoneComercial.Ddd` / `.Telefone` / `.Ramal`	number \| null	Telefone comercial.	sim
`Endereco.Cep`	string	CEP, 8 dígitos com zeros à esquerda.	sim
`Endereco.Logradouro` / `.Numero` / `.Complemento` / `.Bairro`	string \| null	Endereço residencial.	sim
`Endereco.Cidade` / `.Uf`	string	Cidade e UF.	não
`Endereco.EstadoResidencia`	string	UF de residência (mesmo valor de `Endereco.Uf`, mantido por compatibilidade).	não
`CadastroBasico`	bool	`true` quando a conta foi aberta com cadastro simplificado.	não
`Status`	string	Sempre `"Criada"`.	não
`CriadaEm`	string (ISO 8601)	Timestamp da criação da conta (UTC).	não

Campos não informados no cadastro chegam como null (texto) ou 0 (números). Não trate 0 como valor válido em telefones, códigos de ramo ou estado civil.
Campos que nunca aparecem no payload, em nenhuma das variantes: Senha.

{
  "EventType": "ContaDigital.ContaCriada",
  "EventVersion": "v1",
  "EventId": "4d5e8400-e29b-41d4-a716-446655444444",
  "EntityId": "123456",
  "OccurredAt": "2026-06-03T18:40:53.0000000Z",
  "Data": { "...": "ver tabelas acima" }
}

Evento: ContaDigital.ValidacaoCliente


Versão atual	`v1`
Descrição	Resultado da validação de disponibilidade de um dado (CPF, e-mail ou celular) durante o fluxo de cadastro na Conta Digital.
`EntityId` do envelope	CPF do titular associado à validação — sempre, mesmo quando o dado validado (`Data.TipoDado`) é e-mail ou celular.

Dispara em toda tentativa de validação, com sucesso ou falha, inclusive tentativas repetidas do mesmo CPF/e-mail/celular (ex.: um usuário testando o mesmo CPF várias vezes no app). Volume tende a ser maior que ContaDigital.CadastroPf. Diferencie os casos por Data.Aprovado (true/false) e Data.CodigoRetorno.

{ "TipoEntidade": "ContaDigital.ValidacaoCliente", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (`Data`)

{
  "TipoDado": "CPF",
  "Cpf": "12345678901",
  "CodigoCanal": 101,
  "ValorDado": "12345678901",
  "Aprovado": true,
  "CodigoRetorno": 0,
  "DescricaoRetorno": "Sucesso",
  "MensagemAdicional": null,
  "ValidadoEm": "2026-07-28T12:00:00.0000000Z"
}

Campo	Tipo	Descrição	Sensível
`TipoDado`	string (enum)	Dado que foi validado: `"CPF"`, `"EMAIL"` ou `"PHONE"`.	não
`Cpf`	string	CPF do titular associado à validação — sem máscara. Mesmo valor de `EntityId`.	sim
`CodigoCanal`	number	Código do produto contratado com a Pinbank, de origem da tentativa de validação.	não
`ValorDado`	string	Conteúdo depende de `TipoDado`: se `"CPF"`, repete o próprio CPF; se `"EMAIL"`, o e-mail em claro; se `"PHONE"`, o JSON bruto do celular (DDI/DDD/número) em claro, sem máscara — ver nota abaixo.	sim
`Aprovado`	bool	`true` se o dado está disponível/validado com sucesso; `false` em qualquer falha.	não
`CodigoRetorno`	number	Código de negócio do resultado (`0` = sucesso). A Pinbank não publica hoje uma tabela fechada e estável desses códigos — trate como opaco e use `DescricaoRetorno` para exibição.	não
`DescricaoRetorno`	string	Descrição textual do resultado.	não
`MensagemAdicional`	string \| null	Detalhe adicional opcional sobre a falha, quando aplicável.	não
`ValidadoEm`	string (ISO 8601)	Timestamp do momento da validação.	não

Atenção — celular sem máscara: diferente de ContaDigital.CadastroPf (que sempre mascara o celular em Celular.NumeroMascarado), aqui, quando TipoDado=="PHONE", ValorDado traz DDI, DDD e número completos, sem qualquer mascaramento na origem.

Deduplicação — não use `EntityId`

Não use EntityId como chave de deduplicação de negócio para este evento. Múltiplas tentativas de validação distintas (com TipoDado/ValorDado/CodigoRetorno diferentes) para o mesmo titular compartilham o mesmo EntityId (o CPF). Deduplique estritamente por EventId/Webhook-Id, nunca por EntityId.

{
  "EventType": "ContaDigital.ValidacaoCliente",
  "EventVersion": "v1",
  "EventId": "990e8400-e29b-41d4-a716-446655440444",
  "EntityId": "12345678901",
  "OccurredAt": "2026-07-28T12:00:00.0000000Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: ContaDigital.AlteracaoStatus


Versão atual	`v1`
Descrição	Alteração de Status da conta do cliente. Pode ser por processo automatizado ou realizada manualmente.
`EntityId` do envelope	Código do cliente afetado.

payload

Campo	Tipo	Descrição
`CodigoCliente`	int	`cod_mml` da conta
`CodigoCanal`	short	`cod_produto`
`StatusAnterior`	string (1 char)	Status da conta antes da alteração
`NovoStatus`	string (1 char)	Status atual
`Observacao`	string	Observação (máx. 160 char)
`UsrId`	string	Usuário/sistema que solicitou a alteração (máx. 20 char)
`OcorridoEm`	string (ISO 8601, UTC)	Timestamp da gravação do evento (`DateTime.UtcNow`)

Exemplo

{
  "CodigoCliente": 123456,
  "CodigoCanal": 1,
  "StatusAnterior": "A",
  "NovoStatus": "I",
  "Observacao": "Inativação solicitada pelo cliente",
  "UsrId": "POT",
  "TipoOperacao": "AlteracaoStatus",
  "IdLogBloqueioJudicial": null,
  "OcorridoEm": "2026-08-25T13:04:12.1234567Z"
}

Boleto - Ciclo de Vida

Os três eventos do domínio Boleto acompanham o ciclo de vida do título:

Boleto.Registro → Boleto.Liquidacao (pago) e/ou Boleto.Baixa (título encerrado)

Boleto.Baixa não significa que o boleto deixou de ser pago. Baixa é o encerramento do título, e acontece tanto em boletos não pagos quanto em boletos já liquidados. Um boleto pago via QR Code Pix, por exemplo, recebe Boleto.Liquidacao e, em seguida, Boleto.Baixa com TipoBaixa: 4 — a baixa aqui fecha o título, não reverte o pagamento. Use TipoBaixa para interpretar o motivo, e nunca a simples presença do evento.

Todos os eventos de Boleto usam o nosso número como EntityId do envelope — é o identificador do boleto na Pinbank e a chave de correlação natural entre os três eventos.

Evento: Boleto.Registro


Versão atual	v1
Descrição	Boleto registrado com sucesso, a partir do arquivo de retorno de registro (DDA0101R1), e disponível para pagamento.
EntityId do envelope	Nosso número do boleto (string numérica de até 12 posições).

O evento é publicado apenas na transição efetiva de estado do boleto — de PENDENTE para REGISTRADO. Reprocessamento da mesma mensagem não reemite o evento: se o boleto já está REGISTRADO, nada é publicado.

Não existe hoje evento para boleto rejeitado no registro, nem para boleto em estado PENDENTE (emitido, mas ainda sem confirmação). A ausência de Boleto.Registro para um boleto que você emitiu não distingue, por si só, "ainda em processamento" de "rejeitado".

{ "TipoEntidade": "Boleto.Registro", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (Data)

{
  "NossoNumero": "00012345678",
  "CodigoBarras": "52990000000001500000123456789012345678901234",
  "CodigoCliente": 123456,
  "CodigoCanal": 79,
  "Valor": 150.00,
  "DataVencimento": 20260815,
  "DataRegistro": "2026-07-31"
}

Campo	Tipo	Descrição	Sensível
`NossoNumero`	string	Nosso número do boleto — identificador do título na Pinbank. Mesmo valor de `EntityId`.	não
`CodigoBarras`	string	Código de barras do boleto registrado, sem máscara.	não
`CodigoCliente`	number	Seu código de cliente Pinbank (beneficiário do boleto).	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank.	não
`Valor`	decimal	Valor nominal do boleto, conforme registrado.	não
`DataVencimento`	number (AAAAMMDD)	Data de vencimento como inteiro, não como string — ex.: `20260815`. Veja a nota abaixo.	não
`DataRegistro`	string (AAAA-MM-DD)	Data do registro do boleto, no fuso `America/Sao_Paulo`.	não

Atenção — dois formatos de data no mesmo payload: DataVencimento é um número no formato AAAAMMDD (20260815), enquanto DataRegistro é uma string AAAA-MM-DD ("2026-07-31"). Não trate os dois campos com o mesmo parser. O mesmo vale para DataVencimento em Boleto.Liquidacao e Boleto.Baixa, que seguem a mesma convenção numérica.

Este evento não inclui CPF/CNPJ, nome, conta ou agência de nenhuma das partes — o payload expõe apenas identificadores Pinbank e os dados do próprio título.

{
  "EventType": "Boleto.Registro",
  "EventVersion": "v1",
  "EventId": "aa0e8400-e29b-41d4-a716-446655440555",
  "EntityId": "00012345678",
  "OccurredAt": "2026-07-31T14:20:11Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Boleto.Liquidacao


Versão atual	v1
Descrição	Boleto pago — retorno de cobrança acolhido pela Pinbank e título marcado como liquidado.
EntityId do envelope	Nosso número do boleto (string numérica de até 12 posições).

Este evento representa a liquidação do título, não a disponibilidade do dinheiro na sua conta. Ele é publicado no momento em que a Pinbank acolhe o retorno de cobrança e marca o boleto como liquidado. O crédito na conta do beneficiário é processado no mesmo fluxo, mas a liquidação financeira interbancária (SILOC/Reserva) pode ocorrer em janela posterior. Se a sua conciliação depende de saldo disponível, use o extrato da conta como fonte de verdade, e este evento como gatilho.

O valor creditado ao beneficiário é ValorPago menos ValorSplit, quando houver split configurado — a parcela de split é creditada na conta master e não gera evento próprio.

{ "TipoEntidade": "Boleto.Liquidacao", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (Data)

{
  "NossoNumero": "00012345678",
  "CodigoBarras": "52990000000001500000123456789012345678901234",
  "CodigoCliente": 123456,
  "CodigoCanal": 79,
  "ValorPago": 150.00,
  "ValorSplit": 0.00,
  "DataPagamento": "2026-07-31",
  "DataVencimento": 20260815,
  "CodigoOcorrencia": "06",
  "IspbPagador": "60701190",
  "Banco": "PINBANK",
  "ModalidadeBoleto": "C"
}

Campo	Tipo	Descrição	Sensível
`NossoNumero`	string	Nosso número do boleto liquidado. Mesmo valor de `EntityId`.	não
`CodigoBarras`	string	Código de barras do boleto, sem máscara.	não
`CodigoCliente`	number	Seu código de cliente Pinbank (beneficiário do boleto).	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank.	não
`ValorPago`	decimal	Valor efetivamente pago pelo pagador. Pode divergir do valor nominal do boleto (juros, multa, desconto ou pagamento parcial).	não
`ValorSplit`	decimal	Parcela do `ValorPago` destinada à conta master por regra de split. `0.00` quando não há split.	não
`DataPagamento`	string (AAAA-MM-DD)	Data do pagamento informada no retorno de cobrança — apenas a data, sem horário.	não
`DataVencimento`	number (AAAAMMDD)	Data de vencimento do boleto como inteiro — ex.: `20260815`.	não
`CodigoOcorrencia`	string	Código de ocorrência do retorno de cobrança. Enviado como string, preservando zeros à esquerda (ex.: `"06"`, `"10"`).	não
`IspbPagador`	string	ISPB da instituição em que o pagamento foi efetuado. Em pagamentos feitos dentro da própria Pinbank, vem `"17079937"` (ISPB da Pinbank).	não
`Banco`	string (enum)	Trilho de retorno que originou a liquidação: `PINBANK`, `ITAU`, `ITAUBOLECODE`, `BRADESCO`, `POLOCRED`.	não
`ModalidadeBoleto`	string (enum)	Modalidade do título: `C` = boleto de cobrança, `P` = boleto proposta, `R` = boleto de cartão de crédito.	não

Modalidade R pode liquidar mais de uma vez. Boletos de cartão de crédito (ModalidadeBoleto = "R") admitem, por desenho, mais de uma liquidação para o mesmo nosso número — e portanto mais de um Boleto.Liquidacao com o mesmo EntityId, com ValorPago e DataPagamento diferentes entre si. Nas demais modalidades, uma segunda tentativa de liquidação do mesmo título é descartada e não gera evento. Deduplique sempre por EventId/Webhook-Id, nunca por EntityId, e trate ValorPago como incremento no caso da modalidade R.

Este evento não inclui CPF/CNPJ, nome, conta ou agência do pagador — a única informação sobre a origem do pagamento é o IspbPagador, que identifica a instituição, não a pessoa.

{
  "EventType": "Boleto.Liquidacao",
  "EventVersion": "v1",
  "EventId": "bb0e8400-e29b-41d4-a716-446655440666",
  "EntityId": "00012345678",
  "OccurredAt": "2026-07-31T23:05:42Z",
  "Data": { "...": "ver tabela acima" }
}

Evento: Boleto.Baixa


Versão atual	v1
Descrição	Título baixado, com baixa já confirmada pela instituição.
EntityId do envelope	Nosso número do boleto (string numérica de até 12 posições).

O evento é publicado somente após confirmar a baixa — não no momento em que a baixa é solicitada. Se a solicitação falhar, nenhum evento é entregue.

A baixa não implica que o boleto não foi pago — veja Ciclo de vida do boleto. Use TipoBaixa para saber o motivo.

{ "TipoEntidade": "Boleto.Baixa", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

Payload (Data)

{
  "NossoNumero": "00012345678",
  "CodigoBarras": "52990000000001500000123456789012345678901234",
  "CodigoCliente": 123456,
  "CodigoCanal": 79,
  "TipoBaixa": 8,
  "Valor": 150.00,
  "DataVencimento": 20260815,
  "DataBaixa": "2026-08-05"
}

Campo	Tipo	Descrição	Sensível
`NossoNumero`	string	Nosso número do boleto baixado. Mesmo valor de `EntityId`.	não
`CodigoBarras`	string	Código de barras do boleto, sem máscara.	não
`CodigoCliente`	number	Seu código de cliente Pinbank (beneficiário do boleto).	não
`CodigoCanal`	number	Código do produto contratado com a Pinbank.	não
`TipoBaixa`	number (enum)	Motivo da baixa: `4` = baixa integral por pagamento via Pix, `5` = baixa integral por solicitação do cedente, `8` = baixa integral por solicitação da instituição destinatária.	não
`Valor`	decimal	Valor nominal do boleto — não o valor pago.	não
`DataVencimento`	number (AAAAMMDD)	Data de vencimento do boleto como inteiro — ex.: `20260815`.	não
`DataBaixa`	string (AAAA-MM-DD)	Data em que a baixa foi confirmada.	não

TipoBaixa: 8 não identifica um motivo único. O tipo 8 (solicitação da instituição destinatária) agrupa origens distintas, entre elas a baixa por decurso de prazo — boleto vencido e não pago, baixado automaticamente para não manter o título aberto. Não é possível, a partir deste payload, distinguir decurso de prazo de outras baixas solicitadas pela instituição. Se o seu fluxo precisa dessa distinção, fale com o suporte Pinbank.

Valor é o valor nominal, não o pago. Em boletos baixados após pagamento (TipoBaixa: 4, ou 5/8 sobre título já liquidado), o valor efetivamente pago está em ValorPago de Boleto.Liquidacao, e pode divergir do Valor deste evento.

Deduplicação: um mesmo boleto pode ser enviado para baixa mais de uma vez, por origens diferentes. A Pinbank descarta essas repetições e publica um único Boleto.Baixa por nosso número. Ainda assim, deduplique por EventId/Webhook-Id — é a única garantia de idempotência da plataforma, e cobre também as reentregas previstas na Política de Reenvio.

Este evento não inclui CPF/CNPJ, nome, conta ou agência de nenhuma das partes.

{
  "EventType": "Boleto.Baixa",
  "EventVersion": "v1",
  "EventId": "cc0e8400-e29b-41d4-a716-446655440777",
  "EntityId": "00012345678",
  "OccurredAt": "2026-08-05T10:01:33Z",
  "Data": { "...": "ver tabela acima" }
}

Compras & Transacional - Visão Geral

Os eventos do domínio Compra cobrem transações de cartão e Pix processadas via rede de cartão (bridge/adquirência) — domínio diferente dos eventos Pix.* de transferência/QR Code da conta digital. O prefixo Compra. é proposital, para não colidir com aquele domínio.

Uma mesma transação gera mais de um evento ao longo da sua vida — tipicamente Compra.TransacaoPendente (ou Compra.PixCobrancaPendente, para Pix) no início do fluxo, seguido do evento de resultado final (Realizada/Negada), e eventualmente Cancelada/Desfeita/Reembolsada depois. Todos os eventos deste domínio usam o NSU da operação como EntityId do envelope — mesmo valor para todos os eventos publicados ao longo da vida de uma mesma transação — e compartilham exatamente a mesma estrutura de Data, descrita uma única vez a seguir; o que muda de um evento para o outro é o Data.status no momento da publicação e, por consequência, quais campos já estão preenchidos.

Para transações Pix processadas via rede de cartão, os campos relacionados a cartão (bloco cartao, emvChip, metodoAutorizacao, etc.) não se aplicam e chegam vazios/nulos ou com valores neutros.

Campos que dependem de uma resposta do adquirente (nsuGateway, nsuAdquirente, codAutorizAdquirente, etc.) chegam vazios/nulos no evento Pendente e só ficam disponíveis nos eventos seguintes — não trate a ausência desses campos no evento inicial como erro.

Estrutura comum do Payload (`Data`)

Exemplo (Compra.TransacaoRealizada):

{
  "split": { "valor": 0 },
  "valor": 500,
  "valorOriginal": 500,
  "canal": {
    "id": "79",
    "descricao": "PINBANK"
  },
  "estabelecimento": {
    "id": 4,
    "chaveGateway": "BC000014",
    "subEstabelecimento": false,
    "nome": "TESTE",
    "nomeRazaoSocial": "TESTE FIS",
    "documento": "915***46",
    "endereco": {
      "logradouro": "RUA TESTE",
      "numero": "***",
      "complemento": "**************",
      "cidade": "São Paulo",
      "estado": "SP",
      "cep": "1307001"
    },
    "telefone": "1198***55",
    "email": "al***@gl***.com",
    "mcc": "5999"
  },
  "origem": "SWITCH_POS",
  "tipoTransacao": "POS",
  "emvChip": "A",
  "codigoMoeda": 986,
  "cartao": {
    "id": 687,
    "bin": "650956040",
    "pan": "65095604****4470",
    "bandeira": "ELO"
  },
  "status": "Aprovada",
  "nsuGateway": "46254",
  "nsu": 2121978,
  "nsuAdquirente": "123456789123",
  "formaPagamento": "AVISTA",
  "numeroParcelas": 1,
  "data": "2026-07-16T16:53:38",
  "dataCriacao": "2026-07-16T17:04:34",
  "descricaoPedido": "",
  "terminal": {
    "versao": "150",
    "tipo": "N/A"
  },
  "metodoAutorizacao": "NOAUTHORIZATION",
  "codAutorizAdquirente": "341630",
  "capturada": true,
  "tipoCaptura": "CARTAO_CONTACTLESS_EMV_CHIP",
  "autenticacao3dSecure": false,
  "assinaturaEletronica": "",
  "subCredenciadora": {
    "id": 1,
    "cpfCnpj": "12345678000199",
    "nome": "Subcredenciadora XPTO",
    "softDescriptor": "XPTO*LOJA"
  }
}

Campo	Tipo	Descrição	Sensível
`split.valor`	number	Valor do split, em centavos.	não
`valor`	number	Valor da transação, em centavos.	não
`valorOriginal`	number	Valor original da transação, em centavos (antes de estornos parciais).	não
`canal.id`	string	Código do produto/canal Pinbank.	não
`canal.descricao`	string	Descrição do canal. Ausente quando o estabelecimento não pôde ser resolvido.	não
`estabelecimento.id`	number	ID interno da loja.	não
`estabelecimento.chaveGateway`	string	Chave da loja no gateway.	não
`estabelecimento.subEstabelecimento`	boolean	`true` quando os dados do estabelecimento vieram de um sub-estabelecimento informado pelo próprio cliente na transação, em vez de uma loja cadastrada internamente.	não
`estabelecimento.nome`	string	Nome do estabelecimento (ou do sub-estabelecimento, quando aplicável). Ausente se nenhuma das duas fontes estiver disponível.	não
`estabelecimento.nomeRazaoSocial`	string	Razão social da loja cadastrada internamente. Só presente quando `subEstabelecimento` não sobrepõe esse dado.	não
`estabelecimento.documento`	string	CPF/CNPJ do estabelecimento, mascarado (3 primeiros + `***` + 2 últimos).	não
`estabelecimento.endereco.logradouro`	string	Logradouro do endereço.	não
`estabelecimento.endereco.numero`	string	Número do endereço, mascarado por completo.	não
`estabelecimento.endereco.complemento`	string	Complemento do endereço, mascarado por completo.	não
`estabelecimento.endereco.bairro`	string	Bairro. Só presente quando o endereço vem de um sub-estabelecimento.	não
`estabelecimento.endereco.cidade`	string	Cidade.	não
`estabelecimento.endereco.estado`	string	UF.	não
`estabelecimento.endereco.cep`	string	CEP.	não
`estabelecimento.telefone`	string	Telefone da loja cadastrada internamente, mascarado (4 primeiros + `***` + 2 últimos).	não
`estabelecimento.email`	string	E-mail da loja cadastrada internamente, mascarado (parte local e domínio, mantendo a extensão).	não
`estabelecimento.mcc`	string	Merchant Category Code.	não
`estabelecimento.responsavel.nome`	string	Nome do responsável pelo sub-estabelecimento. Só presente quando informado pelo cliente.	sim
`estabelecimento.responsavel.telefone`	string	Telefone do responsável pelo sub-estabelecimento.	sim
`estabelecimento.responsavel.email`	string	E-mail do responsável pelo sub-estabelecimento.	sim
`origem`	string (enum)	Canal de entrada bruto: `SWITCH_POS`, `SWITCH_MPOS`, `ECOMMERCE`, `TEF`, `TEF_SOFTNEX`, `QRCODE_MANAGER`, `GW_BKBANK`, `GW_PINBANK`, `GW_PINBANK_POS`, `LINK_PAGAMENTO`.	não
`tipoTransacao`	string (enum)	Classificação de alto nível de `origem`: `POS`, `Online`, `TEF`, ou `Não mapeada` quando `origem` não se encaixa claramente em nenhuma das três.	não
`emvChip`	string	Dado do chip EMV, quando aplicável.	não
`codigoMoeda`	number	Código ISO 4217 da moeda.	não
`cartao.id`	number	ID interno do cartão.	não
`cartao.bin`	string	BIN do cartão.	sim
`cartao.pan`	string	Número do cartão, já mascarado na origem (ex.: `65095604****4470`).	sim
`cartao.bandeira`	string (enum)	Bandeira do cartão (ex.: `MASTERCARD`, `VISA`, `ELO`, `PIX`).	não
`status`	string (enum)	`Pendente`, `Aprovada`, `Negada`, `Cancelada`, `Desfeita`, `Reembolsada`.	não
`nsuGateway`	string	NSU do gateway. Ausente/vazio até o adquirente responder.	não
`nsu`	number	NSU da operação. Mesmo valor de `EntityId` no envelope.	não
`nsuAdquirente`	string	NSU do adquirente. Ausente/vazio até o adquirente responder.	não
`formaPagamento`	string (enum)	`AVISTA`, `PARCELADO_SEM_JUROS`, `PARCELADO_COM_JUROS`, `DEBITO`, `VOUCHER`, entre outros.	não
`numeroParcelas`	number	Quantidade de parcelas.	não
`data`	string (ISO 8601)	Data/hora da transação.	não
`dataCriacao`	string (ISO 8601)	Data/hora da transação original (ex.: em capturas de pré-autorização, a data da compra original).	não
`descricaoPedido`	string	Descrição do pedido informada na transação.	não
`terminal.versao`	string	Versão do terminal/integração de origem.	não
`terminal.tipo`	string (enum)	Tipo de terminal (ex.: `GERTEC`, `VERIFONE`, `PAX_A920`), ou `N/A` quando não identificado/não aplicável.	não
`metodoAutorizacao`	string (enum)	`PIN`, `SIGNATURE`, `NOAUTHORIZATION`, ou `Não informado`.	não
`codAutorizAdquirente`	string	Código de autorização do adquirente. Ausente/vazio até o adquirente responder.	não
`capturada`	boolean	Indica se a transação já foi capturada (`false` para pré-autorizações pendentes de captura).	não
`tipoCaptura`	string (enum)	Forma de captura do cartão (ex.: `CARTAO_EMV_CHIP`, `CARTAO_CONTACTLESS_EMV_CHIP`, `ECOMMERCE`, `CREDENCIAL_EM_ARQUIVO`).	não
`autenticacao3dSecure`	boolean	Indica se houve autenticação 3D Secure.	não
`assinaturaEletronica`	string	Assinatura eletrônica do portador, quando capturada.	sim
`subCredenciadora.id`	number	ID da subcredenciadora. Bloco inteiro ausente quando a transação não usa uma subcredenciadora (hoje, exclusivo de transações roteadas via Pinbank).	não
`subCredenciadora.cpfCnpj`	string	CPF/CNPJ da subcredenciadora.	sim
`subCredenciadora.nome`	string	Nome/descrição da subcredenciadora.	não
`subCredenciadora.softDescriptor`	string	Soft descriptor exibido na fatura.	não

Evento: Compra.TransacaoPendente


Versão atual	`v1`
Descrição	Transação de cartão recém-criada, antes do resultado do adquirente.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Pendente". Campos que dependem da resposta do adquirente (nsuGateway, nsuAdquirente, codAutorizAdquirente) ainda chegam vazios/nulos — veja Estrutura comum do Payload (Data).

{ "TipoEntidade": "Compra.TransacaoPendente", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.TransacaoPendente",
  "EventVersion": "v1",
  "EventId": "dd0e8400-e29b-41d4-a716-446655440888",
  "EntityId": "2121978",
  "OccurredAt": "2026-07-16T17:04:34Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Pendente\"" }
}

Evento: Compra.TransacaoRealizada


Versão atual	`v1`
Descrição	Transação de cartão aprovada pelo adquirente.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Aprovada". Payload completo de exemplo em Estrutura comum do Payload (Data).

{ "TipoEntidade": "Compra.TransacaoRealizada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.TransacaoRealizada",
  "EventVersion": "v1",
  "EventId": "550e8400-e29b-41d4-a716-446655440000",
  "EntityId": "2121978",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Aprovada\"" }
}

Evento: Compra.TransacaoNegada


Versão atual	`v1`
Descrição	Transação de cartão negada (pelo adquirente, ou em validação prévia antes de chegar ao adquirente).
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Negada". Estrutura idêntica à de Estrutura comum do Payload (Data) — quando a negativa ocorre antes de chegar ao adquirente, os campos que dependem dele (nsuGateway, nsuAdquirente, codAutorizAdquirente) permanecem vazios/nulos.

{ "TipoEntidade": "Compra.TransacaoNegada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.TransacaoNegada",
  "EventVersion": "v1",
  "EventId": "ee0e8400-e29b-41d4-a716-446655440999",
  "EntityId": "2121978",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Negada\"" }
}

Evento: Compra.TransacaoCancelada


Versão atual	`v1`
Descrição	Transação de cartão cancelada.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Cancelada". Estrutura idêntica à de Estrutura comum do Payload (Data).

{ "TipoEntidade": "Compra.TransacaoCancelada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.TransacaoCancelada",
  "EventVersion": "v1",
  "EventId": "ff0e8400-e29b-41d4-a716-446655440aaa",
  "EntityId": "2121978",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Cancelada\"" }
}

Evento: Compra.TransacaoDesfeita


Versão atual	`v1`
Descrição	Transação de cartão desfeita (estorno no mesmo dia).
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Desfeita". Estrutura idêntica à de Estrutura comum do Payload (Data).

{ "TipoEntidade": "Compra.TransacaoDesfeita", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.TransacaoDesfeita",
  "EventVersion": "v1",
  "EventId": "0a1e8400-e29b-41d4-a716-446655440bbb",
  "EntityId": "2121978",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Desfeita\"" }
}

Evento: Compra.TransacaoReembolsada


Versão atual	`v1`
Descrição	Transação de cartão reembolsada.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Reembolsada". Estrutura idêntica à de Estrutura comum do Payload (Data).

{ "TipoEntidade": "Compra.TransacaoReembolsada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.TransacaoReembolsada",
  "EventVersion": "v1",
  "EventId": "0b2e8400-e29b-41d4-a716-446655440ccc",
  "EntityId": "2121978",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Reembolsada\"" }
}

Evento: Compra.PixCobrancaPendente


Versão atual	`v1`
Descrição	Transação Pix (via rede de cartão) recém-criada, antes do resultado.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Pendente". Mesma estrutura de Estrutura comum do Payload (Data) — campos de cartão (cartao, emvChip, metodoAutorizacao, etc.) vazios/nulos ou com valores neutros, por não se aplicarem a Pix.

{ "TipoEntidade": "Compra.PixCobrancaPendente", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.PixCobrancaPendente",
  "EventVersion": "v1",
  "EventId": "0c3e8400-e29b-41d4-a716-446655440ddd",
  "EntityId": "2121979",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Pendente\", campos de cartão vazios/nulos" }
}

Evento: Compra.PixTransferenciaRealizada


Versão atual	`v1`
Descrição	Transferência Pix (via rede de cartão) confirmada.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Aprovada". Mesma estrutura de Estrutura comum do Payload (Data) — campos de cartão vazios/nulos ou com valores neutros, por não se aplicarem a Pix.

{ "TipoEntidade": "Compra.PixTransferenciaRealizada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.PixTransferenciaRealizada",
  "EventVersion": "v1",
  "EventId": "0d4e8400-e29b-41d4-a716-446655440eee",
  "EntityId": "2121979",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Aprovada\", campos de cartão vazios/nulos" }
}

Evento: Compra.PixTransferenciaNegada


Versão atual	`v1`
Descrição	Transferência Pix (via rede de cartão) negada.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Negada". Mesma estrutura de Estrutura comum do Payload (Data) — campos de cartão vazios/nulos ou com valores neutros, por não se aplicarem a Pix.

{ "TipoEntidade": "Compra.PixTransferenciaNegada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.PixTransferenciaNegada",
  "EventVersion": "v1",
  "EventId": "0e5e8400-e29b-41d4-a716-446655440fff",
  "EntityId": "2121979",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Negada\", campos de cartão vazios/nulos" }
}

Evento: Compra.PixCobrancaInvalidada


Versão atual	`v1`
Descrição	QR Code Pix invalidado antes de ser pago.
`EntityId` do envelope	NSU da operação (`nsu` dentro de `Data`).

Data.status = "Desfeita". Não é uma transferência revertida — é uma cobrança abandonada (QR Code que expirou ou foi invalidado antes do pagamento). Mesma estrutura de Estrutura comum do Payload (Data) — campos de cartão vazios/nulos ou com valores neutros, por não se aplicarem a Pix.

{ "TipoEntidade": "Compra.PixCobrancaInvalidada", "Versao": "v1" }

dentro do array VersoesEntidade da sua configuração de webhook — veja Configurando o webhook.

{
  "EventType": "Compra.PixCobrancaInvalidada",
  "EventVersion": "v1",
  "EventId": "0f6e8400-e29b-41d4-a716-446655441000",
  "EntityId": "2121979",
  "OccurredAt": "2026-07-16T19:53:39Z",
  "Data": { "...": "ver Estrutura comum do Payload (Data), status \"Desfeita\", campos de cartão vazios/nulos" }
}

Eventos

PIX#

MED#

Conta Digital (Gestão de Contas)#

Compras (Transacional)#

Boletos / Títulos#

Eventos#

Evento: Pix.CreditoRecebido#

Payload (Data)#

Evento: Pix.TransferenciaRealizada#

Payload (Data) — sucesso#

Payload (Data) — negado/invalidado#

Evento: Pix.DevolucaoEnviada#

Payload (Data)#

Devolução parcial — não some, acumule#

Evento: Pix.DevolucaoRecebida#

Payload (Data)#

Devolução parcial — não some, acumule#

Evento: Med.InfracaoAtualizada#

Payload (Data)#

Evento: Med.DevolucaoAtualizada#

Payload (Data)#

Evento: ContaDigital.CadastroPf#

Payload (Data) — sucesso#

Payload (Data) — erro#

Evento: ContaDigital.CadastroPj#

Payload (Data) — sucesso#

Payload (Data) — erro#

Evento: ContaDigital.ContaCriada#

Payload (Data) — pessoa jurídica (TipoPessoa: "CNPJ")#

Payload (Data) — pessoa física (TipoPessoa: "CPF")#

Evento: ContaDigital.ValidacaoCliente#

Payload (Data)#

Deduplicação — não use EntityId#

Evento: ContaDigital.AlteracaoStatus#

payload#

Exemplo#

Boleto - Ciclo de Vida#

Evento: Boleto.Registro#

Payload (Data)#

Evento: Boleto.Liquidacao#

Payload (Data)#

Evento: Boleto.Baixa#

Payload (Data)#

Compras & Transacional - Visão Geral#

Estrutura comum do Payload (Data)#

Evento: Compra.TransacaoPendente#

Evento: Compra.TransacaoRealizada#

Evento: Compra.TransacaoNegada#

Evento: Compra.TransacaoCancelada#

Evento: Compra.TransacaoDesfeita#

Evento: Compra.TransacaoReembolsada#

Evento: Compra.PixCobrancaPendente#

Evento: Compra.PixTransferenciaRealizada#

Evento: Compra.PixTransferenciaNegada#

Evento: Compra.PixCobrancaInvalidada#

PIX

MED

Conta Digital (Gestão de Contas)

Compras (Transacional)

Boletos / Títulos

Eventos

Evento: Pix.CreditoRecebido

Payload (`Data`)

Evento: Pix.TransferenciaRealizada

Payload (`Data`) — sucesso

Payload (`Data`) — negado/invalidado

Evento: Pix.DevolucaoEnviada

Payload (`Data`)

Devolução parcial — não some, acumule

Evento: Pix.DevolucaoRecebida

Payload (`Data`)

Devolução parcial — não some, acumule

Evento: Med.InfracaoAtualizada

Payload (`Data`)

Evento: Med.DevolucaoAtualizada

Payload (`Data`)

Evento: ContaDigital.CadastroPf

Payload (`Data`) — sucesso

Payload (`Data`) — erro

Evento: ContaDigital.CadastroPj

Payload (`Data`) — sucesso

Payload (`Data`) — erro

Evento: ContaDigital.ContaCriada

Payload (`Data`) — pessoa jurídica (`TipoPessoa: "CNPJ"`)

Payload (`Data`) — pessoa física (`TipoPessoa: "CPF"`)

Evento: ContaDigital.ValidacaoCliente

Payload (`Data`)

Deduplicação — não use `EntityId`

Evento: ContaDigital.AlteracaoStatus

payload

Exemplo

Boleto - Ciclo de Vida

Evento: Boleto.Registro

Payload (Data)

Evento: Boleto.Liquidacao

Payload (Data)

Evento: Boleto.Baixa

Payload (Data)

Compras & Transacional - Visão Geral

Estrutura comum do Payload (`Data`)

Evento: Compra.TransacaoPendente

Evento: Compra.TransacaoRealizada

Evento: Compra.TransacaoNegada

Evento: Compra.TransacaoCancelada

Evento: Compra.TransacaoDesfeita

Evento: Compra.TransacaoReembolsada

Evento: Compra.PixCobrancaPendente

Evento: Compra.PixTransferenciaRealizada

Evento: Compra.PixTransferenciaNegada

Evento: Compra.PixCobrancaInvalidada