The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

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:

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

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

References

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.