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

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.
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.
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')"
)

Understanding PIX Data

What is PIX?

The PIX Ecosystem

System Components

PIX Key Types

Data Available Through pixr

1. PIX Keys Stock (ChavesPix)

Column Descriptions

2. Transactions by Municipality (TransacoesPixPorMunicipio)

Column Descriptions

3. Transaction Statistics (EstatisticasTransacoesPix)

Column Descriptions

Transaction Nature Codes

Initiation Methods

4. Fraud Statistics (EstatisticasFraudesPix)

API Parameters Summary

OData Filter Examples

Data Quality Notes

Coverage

Exclusions

Geographic Data

Working with Dates

Currency Formatting

Understanding Participant Identifiers

See Also

References