Pular para o conteúdo principal
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) atua como intermediário do DICT por meio do BTG, permitindo que você registre e resolva chaves, transfira chaves entre instituições via reivindicações, mantenha seus dados locais conciliados com o BACEN e gerencie marcadores de fraude do MED. O módulo DICT é organizado em seis domínios: Entradas, Chaves, Reivindicações, Relatórios de Infração, Solicitações de Devolução e Estatísticas. Este guia foca no ciclo de vida das chaves, nas reivindicações e na conciliação. As operações com escopo de conta exigem o cabeçalho X-Account-Id.

​
Entradas e chaves

Uma entrada é uma chave Pix registrada em uma de suas contas. O plugin resolve a conta subjacente e os dados do titular a partir do CRM, então você cria entradas por tipo de chave em vez de fornecer os detalhes da conta diretamente. Tipos de chave suportados:
TipoOrigem do valor
CPFDerivado automaticamente do documento do titular no CRM (não envie key)
CNPJDerivado automaticamente do documento do titular no CRM (não envie key)
EMAILFornecido na requisição (e-mail válido, ≤ 77 caracteres)
PHONEFornecido na requisição (^\+[1-9]\d{1,14}$)
EVPUUID 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/exclusão de entradas valida contra reivindicações ativas e a consistência entre a chave e o 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 o cliente concluiu essas etapas antes da chamada. Consulte o guia de integração para os pré-requisitos.
Consultas de chave (GET /v1/dict/keys/{key}) resolvem uma chave para fins de pagamento — retornando o titular atual e a conta para que você possa iniciar um pagamento. Use o cabeçalho opcional X-EndToEnd-Id para rastreamento de pagamento e POST /v1/dict/keys/check para verificar a existência em lote. O plugin retorna os dados como recebidos do BTG; mascarar campos sensíveis antes da exibição é responsabilidade do cliente. 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). Os dados de conta do reivindicador são obtidos do CRM via X-Account-Id; claimerParticipant e donorParticipant são definidos automaticamente pelo BTG.

​
Ciclo de vida da reivindicação

StatusSignificado
OPENReivindicação criada; aguardando o reconhecimento do doador
WAITING_RESOLUTIONDoador reconheceu; período de resolução em andamento (D+7)
CONFIRMEDDoador confirmou; a chave está bloqueada aguardando a conclusão
COMPLETEDTransferência da chave finalizada
CANCELLEDCancelada pelo doador ou reivindicador
Enquanto uma reivindicação está ativa (OPEN, WAITING_RESOLUTION ou CONFIRMED), a chave fica bloqueada: novas entradas e exclusões são impedidas. Durante OPEN/WAITING_RESOLUTION, o doador ainda pode atualizar os dados da conta e as consultas de chave retornam os dados do doador; uma vez CONFIRMED, as consultas retornam “chave não encontrada” até que a reivindicação esteja COMPLETED ou CANCELLED.
  • PORTABILITY pode ser concluída imediatamente após a confirmação.
  • OWNERSHIP tem uma janela de conclusão — resolutionPeriodEnd é D+7 e completionPeriodEnd é D+30.

​
Operações de reivindicação

OperaçãoPapelEndpoint
CriarReivindicadorPOST /v1/dict/claims
ReconhecerDoadorPOST /v1/dict/claims/{id}/acknowledge
ConfirmarDoadorPOST /v1/dict/claims/{id}/confirm
ConcluirReivindicadorPOST /v1/dict/claims/{id}/complete
CancelarDoador ou reivindicadorPOST /v1/dict/claims/{id}/cancel
As mudanças de status da reivindicação são entregues ao seu sistema por meio de webhooks de saída CLAIM. 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 é construída sobre 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 formado pelo XOR de todos os CIDs de um tipo de chave. Como o XOR é comutativo, comparar seu VSync com o do BTG/BACEN revela se o seu conjunto de entradas está sincronizado 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, permitindo que você avalie uma contraparte antes de liquidar um pagamento. Ambos os endpoints consultam o provedor diretamente e não armazenam dados localmente, então trate cada chamada como uma consulta nova, em tempo real. Eles são marcados sob a API MED e exigem autenticação bearer.
EndpointEscopoUse 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 PixAvaliar 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 em 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 tanto as estatísticas em nível de chave (dados ligados à chave como entidade, independentes do seu titular atual) quanto as estatísticas em nível de titular (equivalentes às estatísticas de pessoa do titular atual da chave) em uma única chamada. 
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 estiver prestes a pagar uma chave específica, e as estatísticas de pessoa para uma visão mais ampla do risco da contraparte. Como nenhuma é persistida, faça cache com responsabilidade do seu lado se precisar reutilizar o 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 notifica o PSP da contraparte de que uma transação está sendo contestada como fraude. Ele só pode ser aberto dentro de 90 dias da data da transação, e segue um ciclo de vida create → acknowledge → close/cancel:
EtapaPapelEndpoint
CreateRelator (PSP do pagador)POST /v1/dict/infraction-reports
AcknowledgePSP da contrapartePOST /v1/dict/infraction-reports/{id}/acknowledge
ClosePSP do beneficiário/pagadorPOST /v1/dict/infraction-reports/{id}/close
CancelRelatorPOST /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 que recebeu o relatório.
  • Close — o PSP respondente envia seu resultado de análise (por exemplo TOTALLY_ACCEPTED) dentro de 7 dias. Infrações REFUND_REQUEST são fechadas pelo PSP do beneficiário; infrações REFUND_CANCELLED, pelo PSP do pagador. Uma vez fechado, o relatório é 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:
EtapaEndpoint
CreatePOST /v1/dict/refund-requests
Retrieve / ListGET /v1/dict/refund-requests/{id} · GET /v1/dict/refund-requests
ClosePOST /v1/dict/refund-requests/{id}/close
CancelPOST /v1/dict/refund-requests/{id}/cancel
Close registra o resultado da análise e finaliza a solicitação; cancel retira uma solicitação pendente. As mudanças de status tanto dos relatórios de infração quanto das solicitações de devolução são entregues por webhooks de saída — 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