DICT

How the Pix Indirect Plugin (BTG) manages Pix keys in DICT — entries, key queries, portability and ownership claims, reconciliation (VSync), and fraud markers.

DICT (Diretório de Identificadores de Contas Transacionais) is BACEN’s directory that maps Pix keys to transactional accounts. The Pix Indirect Plugin (BTG) connects you to DICT through BTG. You register and resolve keys, transfer keys between institutions with claims, reconcile your local data with BACEN, and manage MED fraud markers.

The DICT API spans several domains: entries and keys, claims, reconciliation, statistics, and the MED fraud tools. This guide covers key lifecycle, claims, reconciliation, statistics, and MED. Account-scoped operations require the X-Account-Id header.

Entries and keys

---

An entry links a Pix key to one of your accounts. The plugin resolves the account and holder data from CRM. You create entries by key type instead of account details.

Supported key types:

Type	Value source
CPF	Provided in the request (must match the CRM holder’s CPF)
CNPJ	Provided in the request (must match the CRM holder’s CNPJ)
EMAIL	Provided in the request (valid email, ≤ 77 chars)
PHONE	Provided in the request (^\+[1-9][0-9]\d{1,14}$)
EVP	Random UUID generated by the system (do not send key)

POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "[e-mail]" }

Manage entries with create / list / retrieve / update / delete (/v1/dict/entries). Create and delete validate against active claims and check the key against the holder document. For example, a CPF key must match the holder’s CPF.

The plugin does not validate keys with Receita Federal and does not run MFA ownership checks. It assumes you completed those checks before you call it. See the integration guide for prerequisites.

Key queries (GET /v1/dict/keys/{key}) resolve a key for payment. The response returns the current owner and account, so you can start a payment. The query requires the X-End-To-End-Id header for payment tracking. Use POST /v1/dict/keys/check to check existence in bulk. The plugin returns the data as it receives it from BTG. Mask sensitive fields before you display them on your side.

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 that currently holds the key) and the claimer (the participant that requests it). The plugin pulls the claimer’s account data from CRM via X-Account-Id. BTG sets claimerParticipant and donorParticipant automatically.

Claim lifecycle

Status	Meaning
OPEN	Claim created; awaiting the donor’s acknowledgment
WAITING_RESOLUTION	Donor acknowledged; resolution period running (D+7)
CONFIRMED	Donor confirmed; key is blocked pending completion
COMPLETED	Key transfer finalized
CANCELLED	Cancelled by donor or claimer

While a claim is active (OPEN, WAITING_RESOLUTION, or CONFIRMED), the claim locks the key. The plugin blocks new entries and deletes. During OPEN and WAITING_RESOLUTION, the donor can still update account data, and key queries return the donor’s data. After CONFIRMED, queries return “key not found” until the claim reaches COMPLETED or CANCELLED.

• PORTABILITY can complete immediately after confirmation.
• OWNERSHIP adds a completion window. BTG returns resolutionPeriodEnd (D+7) and completionPeriodEnd on the claim.

Claim operations

Operation	Role	Endpoint
Create	Claimer	POST /v1/dict/claims
Acknowledge	Donor	POST /v1/dict/claims/{id}/acknowledge
Confirm	Donor	POST /v1/dict/claims/{id}/confirm
Complete	Claimer	POST /v1/dict/claims/{id}/complete
Cancel	Donor or claimer	POST /v1/dict/claims/{id}/cancel

CLAIM outbound webhooks deliver claim status changes to your system. 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 uses 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 that XORs every CID of a key type. Because XOR is commutative, you compare your VSync to BTG/BACEN’s to reveal whether your entries are 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.

Statistics

---

The Statistics domain exposes BACEN’s Pix risk and usage aggregates. You can assess a counterparty before you settle a payment. Both endpoints query the provider directly and do not store data locally. Treat every call as a fresh, real-time lookup. Both endpoints require bearer authentication.

Endpoint	Scope	Use it to
GET /v1/dict/statistics/persons/{tax_id}	A person (CPF or CNPJ)	Assess a payer/payee across all their keys and accounts
GET /v1/dict/statistics/keys/{key}	A single Pix key	Assess a specific key, plus its current owner

Person statistics

Pass the tax ID (CPF or CNPJ) in the path. The response aggregates settlement data, fraud markers, infraction reports, and entry information. It covers three rolling windows: d90 (last 90 days), m12 (last 12 months), and m60 (last 60 months).

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 }
  }
}

Key statistics

Pass the Pix key in the path. The response returns two statistics in a single call: key-level and owner-level. Key-level statistics tie to the key as an entity, independent of its current owner. Owner-level statistics match the person statistics for the key’s current owner.

GET /v1/dict/statistics/keys/[e-mail]
→ 200 OK
{
  "keyStatistics": { "settlements": { "d90": 12 }, "ownershipChanges": { "m12": 1 } },
  "ownerStatistics": { "fraudMarkers": { "d90": 0 }, "infractionReports": { "m12": 0 } }
}

Use key statistics when you pay a specific key. Use person statistics for a broader counterparty risk view. The plugin does not persist either result. Cache responsibly on your side if you reuse a result within a request flow.

Reference: Retrieve person statistics · Retrieve key statistics

Fraud markers and MED 1.0

---

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 (fraud types: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER). Related infraction reports and refund requests drive the MED 1.0 dispute workflow.

Reference: Create a fraud marker · Cancel a fraud marker · List fraud markers

Infraction reports

An infraction report tells the counterparty PSP that you dispute a transaction as fraud. You can open a report only within 90 days of the transaction date. The report follows a create → acknowledge → close/cancel lifecycle:

Step	Role	Endpoint
Create	Reporter (payer’s PSP)	POST /v1/dict/infraction-reports
Acknowledge	Counterparty PSP	POST /v1/dict/infraction-reports/{id}/acknowledge
Close	Payee’s/payer’s PSP	POST /v1/dict/infraction-reports/{id}/close
Cancel	Reporter	POST /v1/dict/infraction-reports/{id}/cancel

• Create — open the report against the disputed end-to-end ID, e.g. reason: REFUND_REQUEST, situationType: SCAM.
• Acknowledge — the receiving PSP confirms receipt of the report.
• Close — the responding PSP submits its analysis result (for example TOTALLY_ACCEPTED) within 7 days. The payee’s PSP closes REFUND_REQUEST infractions. The payer’s PSP closes REFUND_CANCELLED infractions. After close, the report becomes immutable.
• Cancel — the reporter withdraws a report it opened.

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

Refund requests

A refund request is the MED 1.0 mechanism to ask the counterparty PSP to return disputed funds. It mirrors the same create → acknowledge → close/cancel lifecycle:

Step	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 records the analysis result and finalizes the request. Cancel withdraws a pending request. Outbound webhooks deliver status changes for both infraction reports and refund requests. See the Webhooks guide.

Reference: Create an infraction report · Acknowledge · Close · Cancel · Create a refund request

For the 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