O DICT (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que mapeia chaves Pix para contas transacionais. O Plugin Pix Indireto (BTG) conecta você ao DICT por meio do BTG. Você registra e resolve chaves, transfere chaves entre instituições com reivindicações, concilia seus dados locais com o BACEN e gerencia marcadores de fraude do MED. A API do DICT abrange vários domínios: entradas e chaves, reivindicações, conciliação, estatísticas e as ferramentas de fraude do MED. Este guia cobre o ciclo de vida das chaves, as reivindicações, a conciliação, as estatísticas e o MED. As operações com escopo de conta exigem o cabeçalho X-Account-Id.

Entradas e chaves

Uma entrada vincula uma chave Pix a uma de suas contas. O plugin resolve os dados da conta e do titular a partir do CRM. Você cria entradas por tipo de chave em vez de detalhes da conta. Tipos de chave suportados:

Tipo	Origem do valor
`CPF`	Fornecido na requisição (deve corresponder ao CPF do titular no CRM)
`CNPJ`	Fornecido na requisição (deve corresponder ao CNPJ do titular no CRM)
`EMAIL`	Fornecido na requisição (e-mail válido, ≤ 77 caracteres)
`PHONE`	Fornecido na requisição (`^\+[1-9][0-9]\d{1,14}$`)
`EVP`	UUID aleatório gerado pelo sistema (não envie `key`)

POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "john.doe@example.com" }

Gerencie entradas com criar / listar / recuperar / atualizar / excluir (/v1/dict/entries). A criação e a exclusão validam contra reivindicações ativas e verificam a chave em relação ao documento do titular. Por exemplo, uma chave CPF deve corresponder ao CPF do titular.

O plugin não valida chaves com a Receita Federal nem realiza verificações de propriedade por MFA. Ele presume que você concluiu essas verificações antes de chamá-lo. Consulte o guia de integração para os pré-requisitos.

As consultas de chave (GET /v1/dict/keys/{key}) resolvem uma chave para fins de pagamento. A resposta retorna o titular atual e a conta, para que você possa iniciar um pagamento. A consulta exige o cabeçalho X-End-To-End-Id para o rastreamento do pagamento. Use POST /v1/dict/keys/check para verificar a existência em lote. O plugin retorna os dados como os recebe do BTG. Mascare os campos sensíveis antes de exibi-los no seu lado. Referência: Criar entrada · Listar · Recuperar · Atualizar · Excluir · Recuperar uma chave · Verificar chaves

Reivindicações: portabilidade e propriedade

Uma reivindicação transfere uma chave Pix entre instituições. Existem dois tipos:

PORTABILITY — move uma chave para outro banco para o mesmo titular. Permitido para CPF, CNPJ, PHONE e EMAIL.
OWNERSHIP — reivindica uma chave de uma pessoa diferente. Permitido somente para PHONE.

As duas partes são o doador (o participante que detém a chave atualmente) e o reivindicador (o participante que a solicita). O plugin obtém os dados de conta do reivindicador do CRM via X-Account-Id. O BTG define claimerParticipant e donorParticipant automaticamente.

Ciclo de vida da reivindicação

Status	Significado
`OPEN`	Reivindicação criada; aguardando o reconhecimento do doador
`WAITING_RESOLUTION`	Doador reconheceu; período de resolução em andamento (D+7)
`CONFIRMED`	Doador confirmou; a chave está bloqueada aguardando a conclusão
`COMPLETED`	Transferência da chave finalizada
`CANCELLED`	Cancelada pelo doador ou reivindicador

Enquanto uma reivindicação está ativa (OPEN, WAITING_RESOLUTION ou CONFIRMED), a reivindicação bloqueia a chave. O plugin impede novas entradas e exclusões. Durante OPEN e WAITING_RESOLUTION, o doador ainda pode atualizar os dados da conta, e as consultas de chave retornam os dados do doador. Após CONFIRMED, as consultas retornam “chave não encontrada” até que a reivindicação chegue a COMPLETED ou CANCELLED.

PORTABILITY pode ser concluída imediatamente após a confirmação.
OWNERSHIP adiciona uma janela de conclusão. O BTG retorna resolutionPeriodEnd (D+7) e completionPeriodEnd na reivindicação.

Operações de reivindicação

Operação	Papel	Endpoint
Criar	Reivindicador	`POST /v1/dict/claims`
Reconhecer	Doador	`POST /v1/dict/claims/{id}/acknowledge`
Confirmar	Doador	`POST /v1/dict/claims/{id}/confirm`
Concluir	Reivindicador	`POST /v1/dict/claims/{id}/complete`
Cancelar	Doador ou reivindicador	`POST /v1/dict/claims/{id}/cancel`

Os webhooks de saída CLAIM entregam as mudanças de status da reivindicação ao seu sistema. Consulte o guia de Webhooks. Referência: Criar uma reivindicação · Listar · Recuperar · Reconhecer · Confirmar · Concluir · Cancelar

Conciliação (VSync)

A conciliação mantém seus dados locais de DICT consistentes com os registros oficiais do BACEN. Ela usa dois conceitos:

CID (Content Identifier) — um hash HMAC-SHA256 de 256 bits dos atributos de uma entrada (tipo de chave, chave, titular, participante, agência, conta etc.).
VSync — um único checksum que aplica XOR a todos os CIDs de um tipo de chave. Como o XOR é comutativo, você compara seu VSync com o do BTG/BACEN para revelar se as suas entradas estão sincronizadas sem trocar todos os registros.

Existem dois caminhos:

API manual / administrativa — operadores disparam verificações sob demanda, baixam arquivos de CID e investigam inconsistências. Use Iniciar conciliação completa e Listar jobs de conciliação.
Worker VSync — um processo automatizado em segundo plano que compara periodicamente as entradas internas com o DICT e concilia divergências sem intervenção do usuário.

Configure a janela de tempo do worker de conciliação e a janela de bloqueio de escrita do DICT no guia de integração.

Durante a janela de bloqueio de escrita, o banco de dados bloqueia temporariamente as gravações para evitar inconsistências com o BACEN. Ancore a janela em America/Sao_Paulo e agende-a em períodos de baixo tráfego.

Estatísticas

O domínio Estatísticas expõe os agregados de risco e uso de Pix do BACEN. Você pode avaliar uma contraparte antes de liquidar um pagamento. Ambos os endpoints consultam o provedor diretamente e não armazenam dados localmente. Trate cada chamada como uma consulta nova, em tempo real. Ambos os endpoints exigem autenticação bearer.

Endpoint	Escopo	Use para
`GET /v1/dict/statistics/persons/{tax_id}`	Uma pessoa (CPF ou CNPJ)	Avaliar um pagador/beneficiário em todas as suas chaves e contas
`GET /v1/dict/statistics/keys/{key}`	Uma única chave Pix	Avaliar uma chave específica, além do seu titular atual

Estatísticas de pessoa

Passe o tax ID (CPF ou CNPJ) no caminho. A resposta agrega dados de liquidação, marcadores de fraude, relatórios de infração e informações de entradas. Ela cobre três janelas móveis: d90 (últimos 90 dias), m12 (últimos 12 meses) e m60 (últimos 60 meses).

GET /v1/dict/statistics/persons/12345678901
→ 200 OK
{
  "taxId": "12345678901",
  "statistics": {
    "settlements": { "d90": 42, "m12": 310, "m60": 1580 },
    "fraudMarkers": { "d90": 0, "m12": 1 },
    "infractionReports": { "d90": 0, "m12": 2 }
  }
}

Estatísticas de chave

Passe a chave Pix no caminho. A resposta retorna duas estatísticas em uma única chamada: em nível de chave e em nível de titular. As estatísticas em nível de chave referem-se à chave como entidade, independentes do seu titular atual. As estatísticas em nível de titular correspondem às estatísticas de pessoa do titular atual da chave.

GET /v1/dict/statistics/keys/john.doe@example.com
→ 200 OK
{
  "keyStatistics": { "settlements": { "d90": 12 }, "ownershipChanges": { "m12": 1 } },
  "ownerStatistics": { "fraudMarkers": { "d90": 0 }, "infractionReports": { "m12": 0 } }
}

Use as estatísticas de chave quando pagar uma chave específica. Use as estatísticas de pessoa para uma visão mais ampla do risco da contraparte. O plugin não persiste nenhum dos resultados. Faça cache com responsabilidade do seu lado se reutilizar um resultado dentro de um fluxo de requisição.

Referência: Recuperar estatísticas de pessoa · Recuperar estatísticas de chave

Marcadores de fraude e MED 1.0

O DICT também expõe as ferramentas de prevenção a fraudes do MED (Mecanismo Especial de Devolução) do BACEN. Marcadores de fraude sinalizam uma chave ou conta como associada a fraude. Você pode criá-los e cancelá-los (tipos de fraude: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER). Os relatórios de infração e as solicitações de devolução relacionados conduzem o fluxo de disputa do MED 1.0. Referência: Criar um marcador de fraude · Cancelar um marcador de fraude · Listar marcadores de fraude

Relatórios de infração

Um relatório de infração informa ao PSP da contraparte que você contesta uma transação como fraude. Você só pode abrir um relatório dentro de 90 dias da data da transação. O relatório segue um ciclo de vida create → acknowledge → close/cancel:

Etapa	Papel	Endpoint
Create	Relator (PSP do pagador)	`POST /v1/dict/infraction-reports`
Acknowledge	PSP da contraparte	`POST /v1/dict/infraction-reports/{id}/acknowledge`
Close	PSP do beneficiário/pagador	`POST /v1/dict/infraction-reports/{id}/close`
Cancel	Relator	`POST /v1/dict/infraction-reports/{id}/cancel`

Create — abre o relatório contra o end-to-end ID contestado, ex.: reason: REFUND_REQUEST, situationType: SCAM.
Acknowledge — o PSP receptor confirma o recebimento do relatório.
Close — o PSP respondente envia seu resultado de análise (por exemplo TOTALLY_ACCEPTED) dentro de 7 dias. O PSP do beneficiário fecha as infrações REFUND_REQUEST. O PSP do pagador fecha as infrações REFUND_CANCELLED. Após o fechamento, o relatório torna-se imutável.
Cancel — o relator retira um relatório que abriu.

POST /v1/dict/infraction-reports
{
  "transactionId": "E12345678202411241430ABCDEFGHIJK",
  "reason": "REFUND_REQUEST",
  "situationType": "SCAM",
  "reportDetails": "Customer reported receiving a call from a fake bank employee"
}

Solicitações de devolução

Uma solicitação de devolução é o mecanismo do MED 1.0 para pedir ao PSP da contraparte que devolva os fundos contestados. Ela espelha o mesmo ciclo de vida create → acknowledge → close/cancel:

Etapa	Endpoint
Create	`POST /v1/dict/refund-requests`
Retrieve / List	`GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests`
Close	`POST /v1/dict/refund-requests/{id}/close`
Cancel	`POST /v1/dict/refund-requests/{id}/cancel`

Close registra o resultado da análise e finaliza a solicitação. Cancel retira uma solicitação pendente. Os webhooks de saída entregam as mudanças de status tanto dos relatórios de infração quanto das solicitações de devolução. Consulte o guia de Webhooks. Referência: Criar um relatório de infração · Confirmar · Fechar · Cancelar · Criar uma solicitação de devolução Para os fluxos de recuperação de fundos, consulte Operações de devolução e MED 2.0 — Recuperação de Fundos.

Próximos passos

QR Codes — Gerando QR Codes em chaves registradas
Webhooks — Notificações de reivindicação, infração e devolução
Integração — Conciliação do DICT e configuração do worker

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

DICT

Entradas e chaves

Reivindicações: portabilidade e propriedade

Ciclo de vida da reivindicação

Operações de reivindicação

Conciliação (VSync)

Estatísticas

Estatísticas de pessoa

Estatísticas de chave

Marcadores de fraude e MED 1.0

Relatórios de infração

Solicitações de devolução

Próximos passos

​Entradas e chaves

​Reivindicações: portabilidade e propriedade

​Ciclo de vida da reivindicação

​Operações de reivindicação

​Conciliação (VSync)

​Estatísticas

​Estatísticas de pessoa

​Estatísticas de chave

​Marcadores de fraude e MED 1.0

​Relatórios de infração

​Solicitações de devolução

​Próximos passos

Entradas e chaves

Reivindicações: portabilidade e propriedade

Ciclo de vida da reivindicação

Operações de reivindicação

Conciliação (VSync)

Estatísticas

Estatísticas de pessoa

Estatísticas de chave

Marcadores de fraude e MED 1.0

Relatórios de infração

Solicitações de devolução

Próximos passos