---
title: "Understanding PIX Data"
output: rmarkdown::html_vignette
vignette: >
 %\VignetteIndexEntry{Understanding PIX Data}
 %\VignetteEngine{knitr::rmarkdown}
 %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
 collapse = TRUE,
 comment = "#>",
 eval = FALSE
)
```

## What is PIX?

PIX is Brazil's instant payment system created and managed by the Brazilian Central Bank (Banco Central do Brasil - BCB). Launched on November 16, 2020, it enables instantaneous payments and transfers in Brazilian Real (BRL) 24 hours a day, 7 days a week, including holidays and weekends.

Key features of PIX:

- **Instant**: Transactions complete in seconds (typically under 10 seconds)
- **Free for individuals**: No fees for personal transfers
- **Available 24/7**: Works any time, including weekends and holidays
- **Multiple key types**: Simplifies payments with easy-to-remember identifiers

## The PIX Ecosystem

### System Components

1. **SPI (Sistema de Pagamentos Instantâneos)**: The instant payment settlement system operated by the BCB. It is the only infrastructure for instant payment settlement in Brazil.

2. **DICT (Diretório de Identificadores de Contas Transacionais)**: The Transaction Account Identifier Directory. A centralized database managed by BCB that stores PIX key registrations and links them to bank accounts.

3. **PSP (Prestador de Serviços de Pagamento)**: Payment Service Providers - financial institutions that offer PIX to their customers.

### PIX Key Types

Users can register PIX keys to simplify receiving payments. Instead of sharing full bank details, they share just a key. Available key types:

| Key Type | Portuguese | Description | Example |
|----------|------------|-------------|---------|
| CPF | CPF | Individual taxpayer ID (11 digits) | 123.456.789-00 |
| CNPJ | CNPJ | Company taxpayer ID (14 digits) | 12.345.678/0001-00 |
| Phone | Celular | Mobile phone with country code | +5511999999999 |
| Email | e-mail | Email address | user@example.com |
| Random Key | Aleatória (EVP) | UUID generated by the system | a1b2c3d4-e5f6-7890-... |

**Key limits:**
- Individuals: Up to 5 keys per bank account
- Companies: Up to 20 keys per bank account

## Data Available Through pixr

The BCB provides four main datasets through the PIX Open Data API:

### 1. PIX Keys Stock (ChavesPix)

Monthly snapshot of registered PIX keys, broken down by participant (financial institution), user type (PF/PJ), and key type.

**API Parameter:** `Data` in `YYYY-MM-DD` format

```{r keys-data}
library(pixr)

# View available columns
pix_columns("keys")

# Retrieve data - note: date uses YYYY-MM-DD format
keys <- get_pix_keys(date = "2025-12-01")

# Filter by key type using OData filter
cpf_keys <- get_pix_keys(
  date = "2025-12-01",
  filter = "TipoChave eq 'CPF'"
)
```

#### Column Descriptions

| Column | Description |
|--------|-------------|
| `Data` | Reference date (last day of month, YYYY-MM-DD format) |
| `ISPB` | 8-digit code identifying the financial institution |
| `Nome` | Name of the PIX participant (financial institution) |
| `NaturezaUsuario` | User type: PF (Individual) or PJ (Legal Entity) |
| `TipoChave` | Key type: CPF, CNPJ, Celular, e-mail, or Aleatória |
| `qtdChaves` | Number of registered keys |

### 2. Transactions by Municipality (TransacoesPixPorMunicipio)

Monthly transaction statistics aggregated by Brazilian municipality, showing transaction counts and values from both payer and receiver perspectives.

**API Parameter:** `DataBase` in `YYYYMM` format

```{r municipality-data}
# View available columns
pix_columns("municipality")

# Retrieve data - note: database uses YYYYMM format
transactions <- get_pix_transactions_by_municipality(database = "202512")

# Filter by state using OData filter
sp_data <- get_pix_transactions_by_municipality(
  database = "202512",
  filter = "Estado eq 'SÃO PAULO'"
)
```

#### Column Descriptions

| Column | Description |
|--------|-------------|
| `AnoMes` | Reference year-month in YYYYMM format |
| `Municipio_Ibge` | IBGE municipality code |
| `Municipio` | Municipality name |
| `Estado_Ibge` | IBGE state code |
| `Estado` | State name |
| `Sigla_Regiao` | Region abbreviation (NE, SE, S, CO, N) |
| `Regiao` | Region name (NORDESTE, SUDESTE, SUL, CENTRO-OESTE, NORTE) |
| `VL_PagadorPF` | Total value (BRL) paid by individuals |
| `QT_PagadorPF` | Count of transactions with individual payers |
| `VL_PagadorPJ` | Total value (BRL) paid by legal entities |
| `QT_PagadorPJ` | Count of transactions with legal entity payers |
| `VL_RecebedorPF` | Total value (BRL) received by individuals |
| `QT_RecebedorPF` | Count of transactions with individual receivers |
| `VL_RecebedorPJ` | Total value (BRL) received by legal entities |
| `QT_RecebedorPJ` | Count of transactions with legal entity receivers |
| `QT_PES_PagadorPF` | Distinct individual payers |
| `QT_PES_PagadorPJ` | Distinct legal entity payers |
| `QT_PES_RecebedorPF` | Distinct individual receivers |
| `QT_PES_RecebedorPJ` | Distinct legal entity receivers |

**Note:** Values are in Brazilian Real (BRL). Use `format_brl()` for currency formatting.

### 3. Transaction Statistics (EstatisticasTransacoesPix)

Detailed statistics on PIX transactions with breakdowns by payer/receiver type, region, age group, initiation method, and transaction nature.

**API Parameter:** `Database` in `YYYYMM` format

```{r stats-data}
# View available columns
pix_columns("stats")

# Retrieve data
stats <- get_pix_transaction_stats(database = "202509")

# Filter by transaction nature
p2p_stats <- get_pix_transaction_stats(
  database = "202509",
  filter = "NATUREZA eq 'P2P'"
)
```

#### Column Descriptions

| Column | Description |
|--------|-------------|
| `AnoMes` | Reference year-month in YYYYMM format |
| `PAG_PFPJ` | Payer type: PF (Individual) or PJ (Legal Entity) |
| `REC_PFPJ` | Receiver type: PF or PJ |
| `PAG_REGIAO` | Payer region (NORTE, NORDESTE, SUDESTE, SUL, CENTRO-OESTE) |
| `REC_REGIAO` | Receiver region |
| `PAG_IDADE` | Payer age group |
| `REC_IDADE` | Receiver age group |
| `FORMAINICIACAO` | Initiation method (DICT, QRDN, QRES, MANU, INIC) |
| `NATUREZA` | Transaction nature (P2P, P2B, B2P, B2B, P2G, G2P) |
| `FINALIDADE` | Transaction purpose (Pix, Pix Saque, Pix Troco) |
| `VALOR` | Total transaction value (BRL) |
| `QUANTIDADE` | Number of transactions |

#### Transaction Nature Codes

| Code | Description |
|------|-------------|
| P2P | Person to Person |
| P2B | Person to Business |
| B2P | Business to Person |
| B2B | Business to Business |
| P2G | Person to Government |
| G2P | Government to Person |

#### Initiation Methods

| Code | Description |
|------|-------------|
| DICT | PIX Key lookup |
| QRDN | Dynamic QR Code |
| QRES | Static QR Code |
| MANU | Manual entry (bank details) |
| INIC | Payment Initiator |

### 4. Fraud Statistics (EstatisticasFraudesPix)

Statistics on PIX fraud reported through the Special Return Mechanism (MED - Mecanismo Especial de Devolução).

**API Parameter:** `Database` in `YYYYMM` format

```{r fraud-data}
# View available columns
pix_columns("fraud")

# Retrieve data
fraud <- get_pix_fraud_stats(database = "202509")
```

## API Parameters Summary

Each endpoint requires a specific date parameter with a specific format:

| Endpoint | Parameter | Format | R Function |
|----------|-----------|--------|------------|
| ChavesPix | `Data` | YYYY-MM-DD | `get_pix_keys(date = "2025-12-01")` |
| TransacoesPixPorMunicipio | `DataBase` | YYYYMM | `get_pix_transactions_by_municipality(database = "202512")` |
| EstatisticasTransacoesPix | `Database` | YYYYMM | `get_pix_transaction_stats(database = "202509")` |
| EstatisticasFraudesPix | `Database` | YYYYMM | `get_pix_fraud_stats(database = "202509")` |

## OData Filter Examples

All functions support OData filters:

```{r filter-examples}
# Filter by state
get_pix_transactions_by_municipality(
  database = "202512",
  filter = "Estado eq 'SÃO PAULO'"
)

# Filter by region
get_pix_transactions_by_municipality(
  database = "202512",
  filter = "Sigla_Regiao eq 'NE'"
)

# Filter by transaction nature
get_pix_transaction_stats(
  database = "202509",
  filter = "NATUREZA eq 'P2P'"
)

# Filter by key type
get_pix_keys(
  date = "2025-12-01",
  filter = "TipoChave eq 'CPF'"
)

# Multiple filters with 'and'
get_pix_transaction_stats(
  database = "202509",
  filter = "NATUREZA eq 'P2P' and PAG_REGIAO eq 'SUDESTE'"
)

# Order by column
get_pix_keys(
  date = "2025-12-01",
  filter = "TipoChave eq 'CPF'",
  orderby = "qtdChaves desc",
  top = 100
)
```

## Data Quality Notes

### Coverage

- Data starts from November 2020 (PIX launch)
- Updated monthly by the BCB
- Typically available with a 1-2 month lag

### Exclusions

The transaction statistics do **not** include:
- Transactions settled on participants' internal books (not sent to SPI)
- PIX scheduled for future dates
- Failed or rejected transactions

### Geographic Data

Municipality codes follow the IBGE (Brazilian Institute of Geography and Statistics) standard.

## Working with Dates

The API uses different date formats for different endpoints:

```{r date-helpers}
# ChavesPix uses YYYY-MM-DD
get_pix_keys(date = "2025-12-01")

# Other endpoints use YYYYMM
get_pix_transaction_stats(database = "202509")

# Convert YYYYMM to Date object (first day of month)
year_month_to_date("202312")
# [1] "2023-12-01"

# Works with vectors
year_month_to_date(c("202301", "202306", "202312"))
# [1] "2023-01-01" "2023-06-01" "2023-12-01"
```

## Currency Formatting

Format values as Brazilian Real:

```{r currency-helpers}
# Format as BRL
format_brl(1234567.89)
# [1] "R$ 1.234.567,89"

# Without prefix
format_brl(1234567.89, prefix = FALSE)
# [1] "1.234.567,89"
```

## Understanding Participant Identifiers

Financial institutions in Brazil are identified by their **ISPB** (Identificador do Sistema de Pagamentos Brasileiro), an 8-digit code. Major banks include:

| ISPB | Institution |
|------|-------------|
| 00000000 | Banco do Brasil |
| 60701190 | Itaú Unibanco |
| 60746948 | Bradesco |
| 90400888 | Santander |
| 18236120 | Nu Pagamentos (Nubank) |

```{r ispb-example}
# Filter by institution name
bb_keys <- get_pix_keys(
  date = "2025-12-01",
  filter = "contains(Nome, 'BANCO DO BRASIL')"
)
```

## See Also

- [Working with OData Queries](odata-queries.html) - Advanced query techniques with filters
- [Data Analysis Examples](analysis-examples.html) - Practical examples

## References

- [PIX Official Regulations](https://www.bcb.gov.br/estabilidadefinanceira/pix)
- [DICT API Documentation](https://www.bcb.gov.br/content/estabilidadefinanceira/pix/API-DICT.html)
- [SPI Technical Documentation](https://www.bcb.gov.br/estabilidadefinanceira/comunicacaodados)
- [BCB PIX Open Data Portal](https://dadosabertos.bcb.gov.br/dataset/pix)