Skip to main content
DICT (Diretório de Identificadores de Contas Transacionais) is BACEN’s directory that maps Pix keys to transactional accounts. The Pix Indirect Plugin (BTG) acts as an intermediary to DICT through BTG, letting you register and resolve keys, transfer keys between institutions via claims, keep your local data reconciled with BACEN, and manage MED fraud markers. The DICT module is organized into six domains: Entries, Keys, Claims, Infraction Reports, Refund Requests, and Statistics. This guide focuses on key lifecycle, claims, and reconciliation. Account-scoped operations require the X-Account-Id header.

​
Entries and keys

An entry is a Pix key registered to one of your accounts. The plugin resolves the underlying account and holder data from CRM, so you create entries by key type rather than supplying account details directly. Supported key types:
TypeValue source
CPFAuto-derived from the CRM holder document (do not send key)
CNPJAuto-derived from the CRM holder document (do not send key)
EMAILProvided in the request (valid email, ≤ 77 chars)
PHONEProvided in the request (^\+[1-9]\d{1,14}$)
EVPRandom UUID generated by the system (do not send key)
POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "john.doe@example.com" }
Manage entries with create / list / retrieve / update / delete (/v1/dict/entries). Entry create/delete validate against active claims and the key/holder document consistency (for example, a CPF key must match the holder’s CPF).
The plugin does not validate keys with Receita Federal or perform MFA ownership checks — it assumes the client completed those before calling. See the integration guide for prerequisites.
Key queries (GET /v1/dict/keys/{key}) resolve a key for payment purposes — returning the current owner and account so you can initiate a payment. Use the optional X-EndToEnd-Id header for payment tracking, and POST /v1/dict/keys/check to check existence in bulk. The plugin returns data as received from BTG; masking sensitive fields before display is the client’s responsibility. Reference: Create entry · List · Retrieve · Update · Delete · Retrieve a key · Check keys

​
Claims: portability and ownership

A claim transfers a Pix key between institutions. There are two kinds:
  • PORTABILITY — moves a key to another bank for the same holder. Allowed for CPF, CNPJ, PHONE, and EMAIL.
  • OWNERSHIP — claims a key from a different person. Allowed only for PHONE.
The two parties are the donor (the participant currently holding the key) and the claimer (the participant requesting it). The claimer’s account data is pulled from CRM via X-Account-Id; claimerParticipant and donorParticipant are set automatically by BTG.

​
Claim lifecycle

StatusMeaning
OPENClaim created; awaiting the donor’s acknowledgment
WAITING_RESOLUTIONDonor acknowledged; resolution period running (D+7)
CONFIRMEDDonor confirmed; key is blocked pending completion
COMPLETEDKey transfer finalized
CANCELLEDCancelled by donor or claimer
While a claim is active (OPEN, WAITING_RESOLUTION, or CONFIRMED) the key is locked: new entries and deletes are blocked. During OPEN/WAITING_RESOLUTION the donor may still update account data and key queries return the donor’s data; once CONFIRMED, queries return “key not found” until the claim is COMPLETED or CANCELLED.
  • PORTABILITY can complete immediately after confirmation.
  • OWNERSHIP has a completion window — resolutionPeriodEnd is D+7 and completionPeriodEnd is D+30.

​
Claim operations

OperationRoleEndpoint
CreateClaimerPOST /v1/dict/claims
AcknowledgeDonorPOST /v1/dict/claims/{id}/acknowledge
ConfirmDonorPOST /v1/dict/claims/{id}/confirm
CompleteClaimerPOST /v1/dict/claims/{id}/complete
CancelDonor or claimerPOST /v1/dict/claims/{id}/cancel
Claim status changes are delivered to your system through CLAIM outbound webhooks. See the Webhooks guide. Reference: Create a claim · List · Retrieve · Acknowledge · Confirm · Complete · Cancel

​
Reconciliation (VSync)

Reconciliation keeps your local DICT data consistent with BACEN’s authoritative records. It is built on two concepts:
  • CID (Content Identifier) — a 256-bit HMAC-SHA256 hash of an entry’s attributes (key type, key, owner, participant, branch, account, etc.).
  • VSync — a single checksum formed by XOR-ing every CID of a key type. Because XOR is commutative, comparing your VSync to BTG/BACEN’s reveals whether your set of entries is in sync without exchanging every record.
There are two paths:
  • Manual / administrative API — operators trigger on-demand checks, download CID files, and investigate inconsistencies. Use Start full reconciliation and List reconciliation jobs.
  • VSync worker — an automated background process that periodically compares internal entries against DICT and reconciles drift without user intervention.
Configure the reconciliation worker’s time window and the DICT write-block window in the integration guide.
During the write-block window the database temporarily blocks writes to prevent inconsistencies with BACEN. Anchor the window to America/Sao_Paulo and schedule it during low-traffic periods.

​
Fraud markers (MED)

DICT also exposes BACEN’s MED (Mecanismo Especial de Devolução) fraud-prevention tools. Fraud markers flag a key or account as associated with fraud; you can create and cancel them, and related infraction reports and refund requests drive the dispute and recovery workflow. Reference: Create a fraud marker · Cancel a fraud marker · List fraud markers · Create an infraction report For the full dispute and fund-recovery flows, see Refund operations and MED 2.0 — Funds Recovery.

​
Next steps

  • QR Codes — Generating QR Codes on registered keys
  • Webhooks — Claim, infraction, and refund notifications
  • Integration — DICT reconciliation and worker configuration