# PIX Concepts

Fundamental concepts of the Brazilian PIX instant payment ecosystem as implemented by FluxiQ PIX.

## Prerequisites

- Basic understanding of payment systems
- Familiarity with Brazilian financial regulations is helpful but not required

## PIX Ecosystem Overview

PIX is Brazil's instant payment system, operated by the Banco Central do Brasil (BCB) since November 2020. It enables 24/7/365 real-time transfers between any bank accounts in under 10 seconds.

```mermaid
graph TB
    BCB[Banco Central do Brasil]
    BCB --> DICT_SYS[DICT<br/>Key Directory]
    BCB --> SPI_SYS[SPI<br/>Instant Payments]
    BCB --> MED_SYS[MED 2.0<br/>Fraud Recovery]

    DICT_SYS --> PART_A[Participant A<br/>Direct]
    DICT_SYS --> PART_B[Participant B<br/>Indirect via PSP]
    SPI_SYS --> PART_A
    SPI_SYS --> PART_B
```

## Key Terminology

### DICT (Transactional Account Identifier Directory)

The DICT is the centralized directory that maps PIX keys to bank accounts. It supports 5 key types:

| Key Type | Format | Example |
|----------|--------|---------|
| CPF | 11 digits | `12345678901` |
| CNPJ | 14 digits | `12345678000199` |
| PHONE | +55 + area code + number | `+5511999887766` |
| EMAIL | Email address | `user@example.com` |
| EVP | Random UUID v4 | `a1b2c3d4-e5f6-...` |

Operations: **Create**, **Read** (lookup), **Delete**, **Claim** (ownership dispute), **Portability** (move between institutions).

### SPI (Instant Payment System)

The SPI processes the actual payment messages using ISO 20022 format:

| Message | Code | Purpose |
|---------|------|---------|
| Credit Transfer | pacs.008 | Send a PIX payment |
| Status Report | pacs.002 | Confirm or reject a payment |
| Return | pacs.004 | Return (refund) a payment |
| Status Inquiry | pacs.028 | Query payment status |
| Balance Query | camt.060 | Query settlement balance |
| Echo Request | pibr.001 | Connectivity test |
| Echo Response | pibr.002 | Connectivity test response |

### ANS (Service Level Agreement)

BCB requires PIX settlement within **1.6 seconds** (1,600 ms) measured from operation acceptance to settlement confirmation. FluxiQ PIX tracks this as the delta between `operation_time` and `settlement_time`.

- **OK**: delta <= 1,600 ms (compliant)
- **EXCEEDED**: delta > 1,600 ms (non-compliant, may incur penalties)

### MED 2.0 (Special Return Mechanism)

MED 2.0 is the BCB framework for fraud recovery in PIX transactions. It allows the debtor's institution to request return of funds through infraction reports.

| Status | Description |
|--------|-------------|
| OPEN | Report created, awaiting creditor acknowledgment |
| AWAITING_ANALYSIS | Creditor acknowledged, pending analysis |
| ANALYSED | Analysis complete (AGREED or DISAGREED) |
| CLOSED | Report closed with resolution |
| CANCELLED | Report cancelled |

### ISPB (Participant Identifier)

The ISPB is an 8-digit code assigned by BCB to each financial institution participating in the Brazilian payment system. Example: `12345678`.

### Transaction Statuses

| Code | Name | Description |
|------|------|-------------|
| PDNG | Pending | Transaction created, awaiting processing |
| ACSP | Accepted for Processing | Being processed by SPI |
| ACCC | Accepted | Accepted by creditor's institution |
| ACSC | Accepted Settlement Completed | Settlement confirmed |
| ACTC | Accepted Technical | Technical validation passed |
| ACWC | Accepted with Change | Accepted with modifications |
| STLD | Settled | Fully settled (final state) |
| RJCT | Rejected | Rejected by creditor or BCB |
| CANC | Cancelled | Cancelled by debtor |
| RTRN | Returned | Returned via pacs.004 |

### Settlement and Netting

PIX settlement occurs in real-time for individual transactions, but BCB also performs periodic **netting** -- aggregating bilateral positions between participants to minimize liquidity requirements.

### COSIF (Chart of Accounts)

COSIF is the standardized chart of accounts mandated by BCB (Circular 4010). FluxiQ PIX implements 44 COSIF accounts for proper accounting of PIX operations, including double-entry journal postings.

## FluxiQ PIX Mapping

| BCB Component | FluxiQ Module | Service |
|---------------|---------------|---------|
| DICT v2.10.0 | `DictService` | dict_service (:4001) |
| SPI (ISO 20022) | `SpiService` | spi_service (:4002) |
| Settlement | `SettlementService` | settlement_service (:4003) |
| MED 2.0 | `DictService.InfractionReports` | dict_service (proxied via Settlement) |
| Auth / Crypto | `Shared.Auth`, `Shared.Crypto` | shared (library) |
| BACEN Client | `Shared.Bacen` | shared (library) |

## Expected Outcome

After reading this page, you should understand:

- The role of DICT, SPI, and MED 2.0 in the PIX ecosystem
- PIX key types and transaction message formats
- The ANS settlement SLA and its measurement
- How FluxiQ PIX maps to BCB specifications