# Understanding PIX Data

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

    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

    # 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

    # 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

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

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

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

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

    # 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 - Advanced query techniques with filters
- Data Analysis Examples - Practical examples

## References

- PIX Official Regulations
- DICT API Documentation
- SPI Technical Documentation
- BCB PIX Open Data Portal