Eventos

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.

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).
Conta Digital	`ContaDigital.CadastroPf`	Resultado do cadastro de pessoa física/jurídica — cobre sucesso e erro.
Conta Digital	`ContaDigital.ValidacaoCliente`	Resultado da validação de disponibilidade de um dado (CPF, e-mail, celular) — dispara em toda tentativa, sucesso ou falha.

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).

Incluindo este evento na sua configuração de webhook

{ "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.

Envelope completo entregue

{
  "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.

Incluindo este evento na sua configuração de webhook

{ "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

Envelope completo entregue

{
  "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.

Incluindo este evento na sua configuração de webhook

{ "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.

Envelope completo entregue

{
  "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).

Incluindo este evento na sua configuração de webhook

{ "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.

Envelope completo entregue

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

Evento: ContaDigital.CadastroPf


Versão atual	`v1`
Descrição	Resultado do cadastro de uma pessoa física/jurídica na Conta Digital.
`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.

Incluindo este evento na sua configuração de webhook

{ "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.

Envelope completo entregue

{
  "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.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.

Incluindo este evento na sua configuração de webhook

{ "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.

Envelope completo entregue

{
  "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: Pix.CreditoRecebido#

Incluindo este evento na sua configuração de webhook#

Payload (Data)#

Envelope completo entregue#

Evento: Pix.TransferenciaRealizada#

Incluindo este evento na sua configuração de webhook#

Payload (Data) — sucesso#

Payload (Data) — negado/invalidado#

Envelope completo entregue#

Evento: Pix.DevolucaoEnviada#

Incluindo este evento na sua configuração de webhook#

Payload (Data)#

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

Envelope completo entregue#

Evento: Pix.DevolucaoRecebida#

Incluindo este evento na sua configuração de webhook#

Payload (Data)#

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

Envelope completo entregue#

Evento: ContaDigital.CadastroPf#

Incluindo este evento na sua configuração de webhook#

Payload (Data) — sucesso#

Payload (Data) — erro#

Envelope completo entregue#

Evento: ContaDigital.ValidacaoCliente#

Incluindo este evento na sua configuração de webhook#

Payload (Data)#

Deduplicação — não use EntityId#

Envelope completo entregue#

Evento: Pix.CreditoRecebido

Incluindo este evento na sua configuração de webhook

Payload (`Data`)

Envelope completo entregue

Evento: Pix.TransferenciaRealizada

Incluindo este evento na sua configuração de webhook

Payload (`Data`) — sucesso

Payload (`Data`) — negado/invalidado

Envelope completo entregue

Evento: Pix.DevolucaoEnviada

Incluindo este evento na sua configuração de webhook

Payload (`Data`)

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

Envelope completo entregue

Evento: Pix.DevolucaoRecebida

Incluindo este evento na sua configuração de webhook

Payload (`Data`)

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

Envelope completo entregue

Evento: ContaDigital.CadastroPf

Incluindo este evento na sua configuração de webhook

Payload (`Data`) — sucesso

Payload (`Data`) — erro

Envelope completo entregue

Evento: ContaDigital.ValidacaoCliente

Incluindo este evento na sua configuração de webhook

Payload (`Data`)

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

Envelope completo entregue