pixr: Access Brazilian Central Bank PIX Open Data API

Description

The pixr package provides a tidyverse-style interface to the Brazilian Central Bank (BCB) PIX Open Data API. It allows you to retrieve statistics on PIX keys, transactions by municipality, transaction breakdowns, and fraud statistics.

Main Functions

• get_pix_keys(): Retrieve PIX keys stock by participant

• get_pix_transactions_by_municipality(): Get PIX transactions by municipality

• get_pix_transaction_stats(): Get detailed PIX transaction statistics

• get_pix_fraud_stats(): Get fraud statistics (MED)

API Endpoints

The package provides access to 4 endpoints, each with different parameters:

API Information

The PIX Open Data API is provided by the Brazilian Central Bank (Banco Central do Brasil - BCB) through the Olinda platform. The API follows the OData protocol and provides data in JSON, XML, CSV, or HTML formats.

Base URL: ⁠https://olinda.bcb.gov.br/olinda/servico/Pix_DadosAbertos/versao/v1/odata/⁠

Package Options

The following options can be set to customize package behavior:

pixr.timeout

Request timeout in seconds. Default is 120 seconds. The BCB API can be slow for large queries, so a generous timeout is recommended. Example: options(pixr.timeout = 180) for 3 minutes.

Timeout Configuration

The default timeout for API requests is 120 seconds. This can be changed using:

# Using the helper function
pix_timeout(180)  # Set timeout to 3 minutes

# Or via options
options(pixr.timeout = 180)

# Check current timeout
pix_timeout()

Author(s)

Maintainer: Andre Leite leite@castlab.org

Authors:

• Marcos Wasilew marcos.wasilew@gmail.com

• Hugo Vasconcelos hugo.vasconcelos@ufpe.br

• Diogo Bezerra diogo.bezerra@ufpe.br

See Also

Useful links:

• https://github.com/StrategicProjects/pixr

• Report bugs at https://github.com/StrategicProjects/pixr/issues

BCB PIX API Client Utilities

Description

Internal functions for making requests to the BCB PIX Open Data API

Format Currency Value

Description

Formats a numeric value as Brazilian Real (BRL) currency.

Usage

format_brl(x, prefix = TRUE, decimal_mark = ",", big_mark = ".")

Arguments

Value

A character vector with formatted currency values.

Examples

format_brl(1234567.89)
format_brl(c(1000, 2000, 3000))

Get PIX Fraud Statistics (MED)

Description

Retrieves fraud statistics for PIX transactions reported through the Special Return Mechanism (MED - Mecanismo Especial de Devolução).

Usage

get_pix_fraud_stats(
  database,
  filter = NULL,
  columns = NULL,
  top = NULL,
  skip = NULL,
  orderby = NULL,
  verbose = TRUE
)

Arguments

Details

The MED (Mecanismo Especial de Devolução) is a mechanism created by the Brazilian Central Bank to facilitate the return of funds in cases of fraud or operational errors in PIX transactions.

This endpoint provides statistics on:

• Number of fraud reports (notificações de infração)

• Number of return requests (pedidos de devolução)

• Values involved in fraud cases

Value

A tibble::tibble with PIX fraud statistics.

Examples

## Not run: # It usually takes much longer than 5 seconds.
# Get fraud statistics for September 2025
fraud <- get_pix_fraud_stats(database = "202509")

# Get top 100 records
fraud <- get_pix_fraud_stats(database = "202509", top = 100)

## End(Not run)

Get PIX Fraud Statistics for Multiple Months

Description

Retrieves fraud statistics for multiple months and combines them into a single tibble.

Usage

get_pix_fraud_stats_multi(databases, ...)

Arguments

Value

A tibble::tibble with combined fraud statistics.

Examples

# It usually takes much longer than 5 seconds.
# Get fraud data for Q3 2025
q3_fraud <- get_pix_fraud_stats_multi(
  databases = c("202507", "202508", "202509")
)

Get PIX Keys Stock by Participant

Description

Retrieves the stock of PIX keys registered in the Directory of Transactional Account Identifiers (DICT) at the end of each month, broken down by PIX participant and key type.

Usage

get_pix_keys(
  date,
  filter = NULL,
  columns = NULL,
  top = NULL,
  skip = NULL,
  orderby = NULL,
  verbose = TRUE
)

Arguments

Details

The BCB PIX API requires a date parameter specifying which date's data to retrieve. The data shows the number of PIX keys registered by each financial institution (participant).

Note: The API returns data for the last day of the month containing the specified date. For example, date = "2025-12-01" returns data for 2025-12-31.

Value

A tibble::tibble with PIX keys data.

Available Columns

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

Examples

# It usually takes much longer than 5 seconds.
# Get all PIX keys data for December 2025
keys <- get_pix_keys(date = "2025-12-01")

# Filter by key type and order by quantity
cpf_keys <- get_pix_keys(
  date = "2025-12-01",
  filter = "TipoChave eq 'CPF'",
  orderby = "qtdChaves desc",
  top = 100
)

# Filter by institution
bb_keys <- get_pix_keys(
  date = "2025-12-01",
  filter = "Nome eq 'BANCO DO BRASIL S.A.'"
)

Get PIX Keys by Key Type

Description

Retrieves PIX keys data and returns a summary by key type.

Usage

get_pix_keys_by_type(date, verbose = TRUE)

Arguments

Value

A tibble::tibble with summary data by key type.

Examples

# It usually takes much longer than 5 seconds.
# Get summary by key type
get_pix_keys_by_type(date = "2025-12-01")

Get PIX Keys Summary by Institution

Description

Retrieves PIX keys data and returns a summary showing total keys by institution, sorted by total keys.

Usage

get_pix_keys_summary(date, n_top = 20, verbose = TRUE)

Arguments

Value

A tibble::tibble with summary data by institution.

Examples

# It usually takes much longer than 5 seconds.
# Get top 20 institutions by total keys
get_pix_keys_summary(date = "2025-12-01")

# Get top 10 institutions
get_pix_keys_summary(date = "2025-12-01", n_top = 10)

Get PIX Transaction Summary

Description

Retrieves transaction statistics and aggregates them by specified grouping variables. This is a convenience function that fetches data and performs common aggregations.

Usage

get_pix_summary(database, group_by = "NATUREZA", verbose = TRUE)

Arguments

Value

A tibble::tibble with aggregated transaction statistics.

Examples

# It usually takes much longer than 5 seconds.
# Summary by transaction nature
get_pix_summary(database = "202509", group_by = "NATUREZA")

# Summary by payer region
get_pix_summary(database = "202509", group_by = "PAG_REGIAO")

# Summary by nature and initiation method
get_pix_summary(database = "202509", group_by = c("NATUREZA", "FORMAINICIACAO"))

Get PIX Transaction Statistics

Description

Retrieves detailed statistics on PIX transactions settled through the Instant Payment System (SPI), with breakdowns by payer/receiver type, region, age group, initiation method, and transaction nature.

Usage

get_pix_transaction_stats(
  database,
  filter = NULL,
  columns = NULL,
  top = NULL,
  skip = NULL,
  orderby = NULL,
  verbose = TRUE
)

Arguments

Details

The BCB PIX API requires a database parameter specifying which month's data to retrieve. The data provides granular breakdowns of PIX transactions.

Transaction Nature Codes

• 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

• DICT: PIX Key lookup

• QRDN: Dynamic QR Code

• QRES: Static QR Code

• MANU: Manual entry (bank details)

• INIC: Payment Initiator

Value

A tibble::tibble with PIX transaction statistics.

Available Columns

AnoMes

Reference year-month as integer (YYYYMM format)

PAG_PFPJ

Payer type: PF (Individual) or PJ (Legal Entity)

REC_PFPJ

Receiver type: PF (Individual) or PJ (Legal Entity)

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, etc.)

VALOR

Total transaction value (in BRL)

QUANTIDADE

Number of transactions

Examples

# It usually takes much longer than 5 seconds.
# Get transaction statistics for September 2025
stats <- get_pix_transaction_stats(database = "202509")

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

# Filter by region and order by value
sudeste <- get_pix_transaction_stats(
  database = "202509",
  filter = "PAG_REGIAO eq 'SUDESTE'",
  orderby = "VALOR desc",
  top = 100
)

# Multiple filters (use 'and')
filtered <- get_pix_transaction_stats(
  database = "202509",
  filter = "NATUREZA eq 'P2P' and PAG_REGIAO eq 'NORDESTE'"
)

Get PIX Transaction Statistics for Multiple Months

Description

Retrieves transaction statistics for multiple months and combines them into a single tibble.

Usage

get_pix_transaction_stats_multi(databases, ...)

Arguments

Value

A tibble::tibble with combined transaction statistics.

Examples

# It usually takes much longer than 5 seconds.
# Get data for Q3 2025
q3_data <- get_pix_transaction_stats_multi(
  databases = c("202507", "202508", "202509")
)

Get PIX Transactions by Municipality

Description

Retrieves PIX transaction statistics aggregated by municipality, showing the number and value of transactions from the perspective of both payers and receivers.

Usage

get_pix_transactions_by_municipality(
  database,
  filter = NULL,
  columns = NULL,
  top = NULL,
  skip = NULL,
  orderby = NULL,
  verbose = TRUE
)

Arguments

Details

The BCB PIX API requires a database parameter (YYYYMM format) specifying which month's data to retrieve. The data is broken down by municipality, person type (PF/PJ), and transaction direction (payer/receiver).

Value

A tibble::tibble with PIX transaction data by municipality.

Available Columns

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 paid by individuals (BRL)

QT_PagadorPF

Number of transactions where individuals were payers

VL_PagadorPJ

Total value paid by legal entities (BRL)

QT_PagadorPJ

Number of transactions where legal entities were payers

VL_RecebedorPF

Total value received by individuals (BRL)

QT_RecebedorPF

Number of transactions where individuals were receivers

VL_RecebedorPJ

Total value received by legal entities (BRL)

QT_RecebedorPJ

Number of transactions where legal entities were receivers

QT_PES_PagadorPF

Number of distinct individual payers

QT_PES_PagadorPJ

Number of distinct legal entity payers

QT_PES_RecebedorPF

Number of distinct individual receivers

QT_PES_RecebedorPJ

Number of distinct legal entity receivers

Examples

# It usually takes much longer than 5 seconds.
# Get municipality transaction data for December 2025
muni <- get_pix_transactions_by_municipality(database = "202512")

# Filter by state
maranhao <- get_pix_transactions_by_municipality(
  database = "202512",
  filter = "Estado eq 'MARANHÃO'",
  orderby = "Municipio desc",
  top = 10
)

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

# Order by value
top_value <- get_pix_transactions_by_municipality(
  database = "202512",
  orderby = "VL_PagadorPF desc",
  top = 100
)

Get PIX Transactions by Region

Description

A convenience wrapper that aggregates municipality data at the region level.

Usage

get_pix_transactions_by_region(database, verbose = TRUE)

Arguments

Value

A tibble::tibble with PIX transaction data aggregated by region.

Examples

# It usually takes much longer than 5 seconds.
# Get region-level aggregates
regions <- get_pix_transactions_by_region(database = "202512")

Get PIX Transactions by State

Description

A convenience wrapper around get_pix_transactions_by_municipality() that aggregates data at the state level.

Usage

get_pix_transactions_by_state(database, verbose = TRUE)

Arguments

Value

A tibble::tibble with PIX transaction data aggregated by state.

Examples

# It usually takes much longer than 5 seconds.
# Get state-level aggregates for December 2025
states <- get_pix_transactions_by_state(database = "202512")

Get Column Information for a PIX Endpoint

Description

Returns detailed information about the columns available for a specific endpoint.

Usage

pix_columns(endpoint = c("keys", "municipality", "stats", "fraud"))

Arguments

Value

A tibble::tibble with column names, types, and descriptions.

Examples

pix_columns("keys")
pix_columns("municipality")
pix_columns("stats")
pix_columns("fraud")

Get Available PIX API Endpoints

Description

Returns information about all available endpoints in the BCB PIX Open Data API.

Usage

pix_endpoints()

Value

A tibble::tibble with endpoint names, descriptions, parameters, and associated functions.

Examples

pix_endpoints()

Check API Connection

Description

Tests the connection to all BCB PIX Open Data API endpoints. Each endpoint is tested with a single record request (top=1).

Usage

pix_ping()

Value

A tibble (invisibly) with columns:

endpoint

Name of the endpoint tested

status

Result: "OK" or error message

time_seconds

Time taken for the request in seconds

Examples

## Not run: # It usually takes much longer than 5 seconds.
# Test all endpoints
pix_ping()

# Capture results
results <- pix_ping()
print(results)

## End(Not run)

Get Raw Data from PIX API

Description

Low-level function to fetch data from any PIX API endpoint with custom parameters.

Usage

pix_query(
  endpoint,
  params = NULL,
  filter = NULL,
  select = NULL,
  orderby = NULL,
  top = NULL,
  skip = NULL,
  format = "json",
  verbose = TRUE
)

Arguments

Value

A tibble::tibble with the raw API response data.

Examples

## Not run: # It usually takes much longer than 5 seconds.
# Custom query for keys
pix_query(
  endpoint = "ChavesPix",
  params = list(Data = "2025-12-01"),
  top = 10
)

# Custom query for transaction stats
pix_query(
  endpoint = "EstatisticasTransacoesPix",
  params = list(Database = "202509"),
  top = 10
)

## End(Not run)

Get or Set API Request Timeout

Description

Get or set the timeout for API requests. The default timeout is 120 seconds. The BCB API can be slow for large queries, so a generous timeout is recommended.

Usage

pix_timeout(seconds = NULL)

Arguments

Value

• pix_timeout(): Returns the current timeout in seconds (invisibly when setting).

• When called with seconds, sets the timeout and returns the new value invisibly.

Examples

# Get current timeout
pix_timeout()

# Set timeout to 180 seconds (3 minutes)
pix_timeout(180)

# Set timeout to 60 seconds
pix_timeout(60)

# Reset to default (120 seconds)
pix_timeout(120)

Build PIX API URL (for debugging)

Description

Builds and returns the URL that would be called by a PIX API function. Useful for debugging and testing.

Usage

pix_url(
  endpoint,
  params = NULL,
  filter = NULL,
  select = NULL,
  orderby = NULL,
  top = NULL,
  skip = NULL,
  format = "json"
)

Arguments

Value

Character string with the full API URL.

Examples

# See what URL would be called for each endpoint
pix_url("ChavesPix", params = list(Data = "2025-12-01"), top = 10)
pix_url("EstatisticasTransacoesPix", params = list(Database = "202509"), top = 10)
pix_url("TransacoesPixPorMunicipio", params = list(DataBase = "202512"), top = 10)

Utility Functions for pixr

Description

Helper functions for data transformation and validation

Convert Year-Month String to Date

Description

Converts a year-month string in "YYYYMM" format to a Date object (first day of the month).

Usage

year_month_to_date(year_month)

Arguments

Value

A Date vector.

Examples

year_month_to_date("202312")
year_month_to_date(c("202301", "202302", "202303"))