> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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) 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:**

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

```json theme={null}
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).

<Note>
  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](/en/rails/pix/btg/indirect-pix-integration) for prerequisites.
</Note>

**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](/en/reference/midaz/plugins/indirect-pix/create-entry) · [List](/en/reference/midaz/plugins/indirect-pix/list-entries) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-an-entry) · [Update](/en/reference/midaz/plugins/indirect-pix/update-an-entry) · [Delete](/en/reference/midaz/plugins/indirect-pix/delete-an-entry) · [Retrieve a key](/en/reference/midaz/plugins/indirect-pix/retrieve-a-key) · [Check keys](/en/reference/midaz/plugins/indirect-pix/check-keys-existence)

# 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

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

| 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 status changes are delivered to your system through **CLAIM** outbound webhooks. See the [Webhooks guide](/en/rails/pix/btg/indirect-pix-webhooks).

**Reference:** [Create a claim](/en/reference/midaz/plugins/indirect-pix/create-a-claim) · [List](/en/reference/midaz/plugins/indirect-pix/list-claims) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-a-claim) · [Acknowledge](/en/reference/midaz/plugins/indirect-pix/acknowledge-a-claim) · [Confirm](/en/reference/midaz/plugins/indirect-pix/confirm-a-claim) · [Complete](/en/reference/midaz/plugins/indirect-pix/complete-a-claim) · [Cancel](/en/reference/midaz/plugins/indirect-pix/cancel-a-claim)

# 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](/en/reference/midaz/plugins/indirect-pix/start-full-reconciliation) and [List reconciliation jobs](/en/reference/midaz/plugins/indirect-pix/list-all-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](/en/rails/pix/btg/indirect-pix-integration#7-dict-reconciliation-vsync).

<Warning>
  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.
</Warning>

# Statistics

***

The **Statistics** domain exposes BACEN's Pix risk and usage aggregates, letting you assess a counterparty **before** settling a payment. Both endpoints query the provider directly and **do not store data locally**, so treat every call as a fresh, real-time lookup. They are tagged under the MED API and 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 over three rolling windows: **d90** (last 90 days), **m12** (last 12 months), and **m60** (last 60 months).

```json theme={null}
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 **both** key-level statistics (data tied to the key as an entity, independent of its current owner) and owner-level statistics (equivalent to the person statistics for the key's current owner) in a single call.

```json theme={null}
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 } }
}
```

<Note>
  Use key statistics when you are about to pay a specific key, and person statistics for a broader counterparty risk view. Because neither is persisted, cache responsibly on your side if you need to reuse the result within a request flow.
</Note>

**Reference:** [Retrieve person statistics](/en/reference/midaz/plugins/indirect-pix/retrieve-person-statistics) · [Retrieve key statistics](/en/reference/midaz/plugins/indirect-pix/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](/en/reference/midaz/plugins/indirect-pix/create-a-fraud-marker) · [Cancel a fraud marker](/en/reference/midaz/plugins/indirect-pix/cancel-a-fraud-marker) · [List fraud markers](/en/reference/midaz/plugins/indirect-pix/list-fraud-markers)

## Infraction reports

An **infraction report** notifies the counterparty PSP that a transaction is disputed as fraud. It can only be opened within **90 days** of the transaction date, and 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 it has received the report.
* **Close** — the responding PSP submits its analysis result (for example `TOTALLY_ACCEPTED`) within **7 days**. `REFUND_REQUEST` infractions are closed by the payee's PSP; `REFUND_CANCELLED` infractions by the payer's PSP. Once closed, the report is immutable.
* **Cancel** — the reporter withdraws a report it opened.

```json theme={null}
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. Status changes for both infraction reports and refund requests are delivered through outbound webhooks — see the [Webhooks guide](/en/rails/pix/btg/indirect-pix-webhooks).

**Reference:** [Create an infraction report](/en/reference/midaz/plugins/indirect-pix/create-an-infraction-report) · [Acknowledge](/en/reference/midaz/plugins/indirect-pix/acknowledge-an-infraction-report) · [Close](/en/reference/midaz/plugins/indirect-pix/close-an-infraction-report) · [Cancel](/en/reference/midaz/plugins/indirect-pix/cancel-an-infraction-report) · [Create a refund request](/en/reference/midaz/plugins/indirect-pix/create-a-refund-request)

For the fund-recovery flows, see [Refund operations](/en/rails/pix/btg/indirect-pix-refund-operations) and [MED 2.0 — Funds Recovery](/en/rails/pix/btg/indirect-pix-med-2-funds-recovery).

# Next steps

***

* [QR Codes](/en/rails/pix/btg/indirect-pix-qrcodes) — Generating QR Codes on registered keys
* [Webhooks](/en/rails/pix/btg/indirect-pix-webhooks) — Claim, infraction, and refund notifications
* [Integration](/en/rails/pix/btg/indirect-pix-integration) — DICT reconciliation and worker configuration