O DICT (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que associa chaves Pix a contas transacionais. O Plugin Pix Indireto (BTG) conecta você ao DICT pelo BTG. Você registra e resolve chaves, transfere chaves entre instituições com reivindicações, concilia seus dados locais com o BACEN e gerencia as marcações de fraude do MED. A API do DICT abrange vários domínios: vínculos e chaves, reivindicações, conciliação, estatísticas e as ferramentas de fraude do MED. As operações no escopo de conta exigem o header X-Account-Id.

Vínculos e chaves

Um vínculo associa uma chave Pix a uma das suas contas. O plugin resolve os dados da conta e do titular a partir do CRM. Você cria vínculos por tipo de chave, em vez de por dados da conta. Tipos de chave aceitos:

Tipo	Origem do valor
`CPF`	Informado na requisição (deve corresponder ao CPF do titular no CRM)
`CNPJ`	Informado na requisição (deve corresponder ao CNPJ do titular no CRM)
`EMAIL`	Informado na requisição (e-mail válido, ≤ 77 caracteres)
`PHONE`	Informado 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 os vínculos com criar / listar / consultar / atualizar / excluir (/v1/dict/entries). A criação e a exclusão validam as reivindicações ativas e conferem a chave com o documento do titular. Por exemplo, uma chave CPF deve corresponder ao CPF do titular.

O plugin não valida chaves na Receita Federal e não executa verificações de posse com MFA. Ele supõe que você concluiu essas verificações antes de chamá-lo. Veja os pré-requisitos no guia de integração.

As consultas de chave (GET /v1/dict/keys/{key}) resolvem uma chave para pagamento. A resposta traz o dono atual e a conta, para você iniciar um pagamento. A consulta exige o header X-End-To-End-Id para o rastreamento do pagamento. Use POST /v1/dict/keys/check para checar a existência em lote. O plugin devolve os dados como os recebe do BTG. Mascare os campos sensíveis antes de mostrá-los no seu lado. Referência: Criar vínculo · Listar · Consultar · Atualizar · Excluir · Consultar uma chave · Checar chaves

Reivindicações: portabilidade e posse

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

PORTABILITY: move uma chave para outro banco para o mesmo titular. Permitida para CPF, CNPJ, PHONE e EMAIL.
OWNERSHIP: reivindica uma chave de uma pessoa diferente. Permitida apenas para PHONE.

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

Ciclo de vida da reivindicação

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

Enquanto uma reivindicação está ativa (OPEN, WAITING_RESOLUTION ou CONFIRMED), ela trava a chave. O plugin bloqueia novos vínculos e exclusões. Durante OPEN e WAITING_RESOLUTION, o doador ainda pode atualizar os dados da conta, e as consultas de chave devolvem os dados do doador. Depois de CONFIRMED, as consultas devolvem “chave não encontrada” até a reivindicação chegar a COMPLETED ou CANCELLED.

PORTABILITY pode ser concluída logo após a confirmação.
OWNERSHIP acrescenta uma janela de conclusão. O BTG devolve 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 das reivindicações ao seu sistema. Veja o guia de Webhooks. Referência: Criar uma reivindicação · Listar · Consultar · Reconhecer · Confirmar · Concluir · Cancelar

Conciliação (VSync)

A conciliação mantém seus dados locais do 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 um vínculo (tipo de chave, chave, dono, participante, agência, conta etc.).
VSync: um único checksum que aplica XOR a cada CID de um tipo de chave. Como o XOR é comutativo, você compara o seu VSync com o do BTG/BACEN para revelar se seus vínculos estão sincronizados, sem trocar todos os registros.

Existem dois caminhos:

API manual / administrativa: os 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 automático em background que compara periodicamente os vínculos internos com o DICT e concilia as divergências sem intervenção do usuário.

Configure a janela de horário 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 bloqueia temporariamente as escritas 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 Statistics expõe os agregados de risco e de uso do Pix do BACEN. Você pode avaliar uma contraparte antes de liquidar um pagamento. Os dois endpoints consultam o provedor diretamente e não armazenam dados localmente. Trate cada chamada como uma consulta nova, em tempo real. Os dois endpoints exigem autenticação bearer.

Endpoint	Escopo	Use para
`GET /v1/dict/statistics/persons/{tax_id}`	Uma pessoa (CPF ou CNPJ)	Avaliar um pagador/recebedor em todas as chaves e contas dele
`GET /v1/dict/statistics/keys/{key}`	Uma única chave Pix	Avaliar uma chave específica e o dono atual dela

Estatísticas da pessoa

Passe o documento fiscal (CPF ou CNPJ) no path. A resposta agrega dados de liquidação, marcações de fraude, relatos de infração e informações de vínculo. 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 da chave

Passe a chave Pix no path. A resposta devolve duas estatísticas em uma única chamada: no nível da chave e no nível do dono. As estatísticas no nível da chave se ligam à chave como entidade, independentemente do dono atual dela. As estatísticas no nível do dono correspondem às estatísticas da pessoa referentes ao dono 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 da chave quando você paga uma chave específica. Use as estatísticas da pessoa para uma visão mais ampla do risco da contraparte. O plugin não persiste nenhum dos dois resultados. Faça cache com responsabilidade no seu lado se reutilizar um resultado dentro de um fluxo de requisição.

Referência: Consultar estatísticas da pessoa · Consultar estatísticas da chave

Marcações de fraude e MED 1.0

O DICT também expõe as ferramentas de prevenção a fraude do MED (Mecanismo Especial de Devolução) do BACEN. As marcações de fraude sinalizam uma chave ou conta como associada a fraude. Você pode criar e cancelar essas marcações (tipos de fraude: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER). Os relatos de infração e as solicitações de devolução relacionados conduzem o workflow de disputa do MED 1.0. Referência: Criar uma marcação de fraude · Cancelar uma marcação de fraude · Listar marcações de fraude

Relatos de infração

Um relato de infração avisa o PSP da contraparte que você contesta uma transação como fraude. Você pode abrir um relato apenas dentro de 90 dias a partir da data da transação. O relato segue um ciclo de vida criar → reconhecer → encerrar/cancelar:

Etapa	Papel	Endpoint
Criar	Relator (PSP do pagador)	`POST /v1/dict/infraction-reports`
Reconhecer	PSP da contraparte	`POST /v1/dict/infraction-reports/{id}/acknowledge`
Encerrar	PSP do recebedor/pagador	`POST /v1/dict/infraction-reports/{id}/close`
Cancelar	Relator	`POST /v1/dict/infraction-reports/{id}/cancel`

Criar: abre o relato contra o end-to-end ID contestado, por exemplo reason: REFUND_REQUEST, situationType: SCAM.
Reconhecer: o PSP que recebe confirma o recebimento do relato.
Encerrar: o PSP que responde envia o resultado da análise (por exemplo TOTALLY_ACCEPTED) em até 7 dias. O PSP do recebedor fecha as infrações REFUND_REQUEST. O PSP do pagador fecha as infrações REFUND_CANCELLED. Depois do encerramento, o relato fica imutável.
Cancelar: o relator retira um relato que ele 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 recursos contestados. Ela espelha o mesmo ciclo de vida criar → reconhecer → encerrar/cancelar:

Etapa	Endpoint
Criar	`POST /v1/dict/refund-requests`
Consultar / Listar	`GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests`
Encerrar	`POST /v1/dict/refund-requests/{id}/close`
Cancelar	`POST /v1/dict/refund-requests/{id}/cancel`

Encerrar registra o resultado da análise e finaliza a solicitação. Cancelar retira uma solicitação pendente. Os webhooks de saída entregam as mudanças de status tanto dos relatos de infração quanto das solicitações de devolução. Veja o guia de Webhooks. Referência: Criar um relato de infração · Reconhecer · Encerrar · Cancelar · Criar uma solicitação de devolução Para os fluxos de recuperação de recursos, veja Operações de devolução e MED 2.0 — Funds Recovery.

Próximos passos

QR Codes: gerar QR Codes em chaves registradas
Webhooks: notificações de reivindicação, de infração e de devolução
Integração: conciliação do DICT e configuração do worker

​Vínculos e chaves

​Reivindicações: portabilidade e posse

​Ciclo de vida da reivindicação

​Operações de reivindicação

​Conciliação (VSync)

​Estatísticas

​Estatísticas da pessoa

​Estatísticas da chave

​Marcações de fraude e MED 1.0

​Relatos de infração

​Solicitações de devolução

​Próximos passos

Vínculos e chaves

Reivindicações: portabilidade e posse

Ciclo de vida da reivindicação

Operações de reivindicação

Conciliação (VSync)

Estatísticas

Estatísticas da pessoa

Estatísticas da chave

Marcações de fraude e MED 1.0

Relatos de infração

Solicitações de devolução

Próximos passos