| Title: | Access Brazilian Central Bank 'PIX' Open Data 'API' |
|---|---|
| Description: | Provides a 'tidyverse'-style interface to the Brazilian Central Bank ('BCB') 'PIX' Open Data 'API'. Retrieve statistics on 'PIX' keys, transactions by municipality, and monthly transaction summaries. All functions return 'tibbles' and support 'OData' query parameters for filtering, selecting, and ordering data. |
| Authors: | Andre Leite [aut, cre], Marcos Wasilew [aut], Hugo Vasconcelos [aut], Diogo Bezerra [aut] |
| Maintainer: | Andre Leite <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-06-01 11:26:57 UTC |
| Source: | https://github.com/strategicprojects/pixr |
Formats a numeric value as Brazilian Real (BRL) currency.
format_brl(x, prefix = TRUE, decimal_mark = ",", big_mark = ".")format_brl(x, prefix = TRUE, decimal_mark = ",", big_mark = ".")
x |
Numeric vector. |
prefix |
Logical; if TRUE (default), includes "R$" prefix. |
decimal_mark |
Character to use as decimal separator. |
big_mark |
Character to use as thousands separator. |
A character vector with formatted currency values.
format_brl(1234567.89) format_brl(c(1000, 2000, 3000))format_brl(1234567.89) format_brl(c(1000, 2000, 3000))
Retrieves fraud statistics for PIX transactions reported through the Special Return Mechanism (MED - Mecanismo Especial de Devolução).
get_pix_fraud_stats( database, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )get_pix_fraud_stats( database, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )
database |
Character string in "YYYYMM" format specifying which month's data to retrieve. This parameter is required. |
filter |
OData filter expression as a character string. |
columns |
Character vector of columns to return. If NULL, returns all columns. |
top |
Integer; maximum number of records to return. |
skip |
Integer; number of records to skip (for pagination). |
orderby |
Character string specifying the column to sort by. Use
|
verbose |
Logical; if TRUE (default), prints progress messages. |
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
A tibble::tibble with PIX fraud statistics.
## 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)## 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)
Retrieves fraud statistics for multiple months and combines them into a single tibble.
get_pix_fraud_stats_multi(databases, ...)get_pix_fraud_stats_multi(databases, ...)
databases |
Character vector of year-months in "YYYYMM" format. |
... |
Additional arguments passed to |
A tibble::tibble with combined fraud statistics.
## Not run: # 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") ) ## End(Not run)## Not run: # 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") ) ## End(Not run)
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.
get_pix_keys( date, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )get_pix_keys( date, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )
date |
Character string in "YYYY-MM-DD" format specifying the reference date. This parameter is required. The API returns data for the last day of the specified month. |
filter |
OData filter expression as a character string. Examples:
|
columns |
Character vector of columns to return. If NULL, returns all columns. See "Available Columns" section. |
top |
Integer; maximum number of records to return. |
skip |
Integer; number of records to skip (for pagination). |
orderby |
Character string specifying the column to sort by. Use
|
verbose |
Logical; if TRUE (default), prints progress messages. |
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.
A tibble::tibble with PIX keys data.
Reference date (last day of month, YYYY-MM-DD format)
8-digit code identifying the financial institution
Name of the PIX participant (financial institution)
User type: PF (Individual) or PJ (Legal Entity)
Key type: CPF, CNPJ, Celular, e-mail, or Aleatória
Number of registered keys
## Not run: # 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.'" ) ## End(Not run)## Not run: # 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.'" ) ## End(Not run)
Retrieves PIX keys data and returns a summary by key type.
get_pix_keys_by_type(date, verbose = TRUE)get_pix_keys_by_type(date, verbose = TRUE)
date |
Character string in "YYYY-MM-DD" format specifying the reference date. This parameter is required. The API returns data for the last day of the specified month. |
verbose |
Logical; if TRUE (default), prints progress messages. |
A tibble::tibble with summary data by key type.
## Not run: # It usually takes much longer than 5 seconds. # Get summary by key type get_pix_keys_by_type(date = "2025-12-01") ## End(Not run)## Not run: # It usually takes much longer than 5 seconds. # Get summary by key type get_pix_keys_by_type(date = "2025-12-01") ## End(Not run)
Retrieves PIX keys data and returns a summary showing total keys by institution, sorted by total keys.
get_pix_keys_summary(date, n_top = 20, verbose = TRUE)get_pix_keys_summary(date, n_top = 20, verbose = TRUE)
date |
Character string in "YYYY-MM-DD" format specifying the reference date. This parameter is required. The API returns data for the last day of the specified month. |
n_top |
Integer; number of top institutions to return. Default is 20. |
verbose |
Logical; if TRUE (default), prints progress messages. |
A tibble::tibble with summary data by institution.
## Not run: # 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) ## End(Not run)## Not run: # 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) ## End(Not run)
Retrieves transaction statistics and aggregates them by specified grouping variables. This is a convenience function that fetches data and performs common aggregations.
get_pix_summary(database, group_by = "NATUREZA", verbose = TRUE)get_pix_summary(database, group_by = "NATUREZA", verbose = TRUE)
database |
Character string in "YYYYMM" format specifying which month's data to retrieve. This parameter is required. |
group_by |
Character vector of columns to group by. Common choices: "NATUREZA", "PAG_REGIAO", "REC_REGIAO", "FORMAINICIACAO". |
verbose |
Logical; if TRUE (default), prints progress messages. |
A tibble::tibble with aggregated transaction statistics.
## Not run: # 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")) ## End(Not run)## Not run: # 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")) ## End(Not run)
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.
get_pix_transaction_stats( database, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )get_pix_transaction_stats( database, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )
database |
Character string in "YYYYMM" format specifying which month's data to retrieve. This parameter is required. |
filter |
OData filter expression as a character string. Examples:
|
columns |
Character vector of columns to return. If NULL, returns all columns. See "Available Columns" section. |
top |
Integer; maximum number of records to return. |
skip |
Integer; number of records to skip (for pagination). |
orderby |
Character string specifying the column to sort by. Use
|
verbose |
Logical; if TRUE (default), prints progress messages. |
The BCB PIX API requires a database parameter specifying which month's
data to retrieve. The data provides granular breakdowns of PIX transactions.
P2P: Person to Person
P2B: Person to Business
B2P: Business to Person
B2B: Business to Business
P2G: Person to Government
G2P: Government to Person
DICT: PIX Key lookup
QRDN: Dynamic QR Code
QRES: Static QR Code
MANU: Manual entry (bank details)
INIC: Payment Initiator
A tibble::tibble with PIX transaction statistics.
Reference year-month as integer (YYYYMM format)
Payer type: PF (Individual) or PJ (Legal Entity)
Receiver type: PF (Individual) or PJ (Legal Entity)
Payer region (NORTE, NORDESTE, SUDESTE, SUL, CENTRO-OESTE)
Receiver region
Payer age group
Receiver age group
Initiation method (DICT, QRDN, QRES, MANU, INIC)
Transaction nature (P2P, P2B, B2P, B2B, P2G, G2P)
Transaction purpose (Pix, Pix Saque, Pix Troco, etc.)
Total transaction value (in BRL)
Number of transactions
## Not run: # 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'" ) ## End(Not run)## Not run: # 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'" ) ## End(Not run)
Retrieves transaction statistics for multiple months and combines them into a single tibble.
get_pix_transaction_stats_multi(databases, ...)get_pix_transaction_stats_multi(databases, ...)
databases |
Character vector of year-months in "YYYYMM" format. |
... |
Additional arguments passed to |
A tibble::tibble with combined transaction statistics.
## Not run: # 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") ) ## End(Not run)## Not run: # 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") ) ## End(Not run)
Retrieves PIX transaction statistics aggregated by municipality, showing the number and value of transactions from the perspective of both payers and receivers.
get_pix_transactions_by_municipality( database, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )get_pix_transactions_by_municipality( database, filter = NULL, columns = NULL, top = NULL, skip = NULL, orderby = NULL, verbose = TRUE )
database |
Character string in "YYYYMM" format specifying which month's data to retrieve. This parameter is required. |
filter |
OData filter expression as a character string. Examples:
|
columns |
Character vector of columns to return. If NULL, returns all columns. See "Available Columns" section. |
top |
Integer; maximum number of records to return. |
skip |
Integer; number of records to skip (for pagination). |
orderby |
Character string specifying the column to sort by. Use
|
verbose |
Logical; if TRUE (default), prints progress messages. |
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).
A tibble::tibble with PIX transaction data by municipality.
Reference year-month in YYYYMM format
IBGE municipality code
Municipality name
IBGE state code
State name
Region abbreviation (NE, SE, S, CO, N)
Region name (NORDESTE, SUDESTE, SUL, CENTRO-OESTE, NORTE)
Total value paid by individuals (BRL)
Number of transactions where individuals were payers
Total value paid by legal entities (BRL)
Number of transactions where legal entities were payers
Total value received by individuals (BRL)
Number of transactions where individuals were receivers
Total value received by legal entities (BRL)
Number of transactions where legal entities were receivers
Number of distinct individual payers
Number of distinct legal entity payers
Number of distinct individual receivers
Number of distinct legal entity receivers
## Not run: # 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 ) ## End(Not run)## Not run: # 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 ) ## End(Not run)
A convenience wrapper that aggregates municipality data at the region level.
get_pix_transactions_by_region(database, verbose = TRUE)get_pix_transactions_by_region(database, verbose = TRUE)
database |
Character string in "YYYYMM" format specifying which month's data to retrieve. This parameter is required. |
verbose |
Logical; if TRUE (default), prints progress messages. |
A tibble::tibble with PIX transaction data aggregated by region.
## Not run: # It usually takes much longer than 5 seconds. # Get region-level aggregates regions <- get_pix_transactions_by_region(database = "202512") ## End(Not run)## Not run: # It usually takes much longer than 5 seconds. # Get region-level aggregates regions <- get_pix_transactions_by_region(database = "202512") ## End(Not run)
A convenience wrapper around get_pix_transactions_by_municipality() that
aggregates data at the state level.
get_pix_transactions_by_state(database, verbose = TRUE)get_pix_transactions_by_state(database, verbose = TRUE)
database |
Character string in "YYYYMM" format specifying which month's data to retrieve. This parameter is required. |
verbose |
Logical; if TRUE (default), prints progress messages. |
A tibble::tibble with PIX transaction data aggregated by state.
## Not run: # It usually takes much longer than 5 seconds. # Get state-level aggregates for December 2025 states <- get_pix_transactions_by_state(database = "202512") ## End(Not run)## Not run: # It usually takes much longer than 5 seconds. # Get state-level aggregates for December 2025 states <- get_pix_transactions_by_state(database = "202512") ## End(Not run)
Returns detailed information about the columns available for a specific endpoint.
pix_columns(endpoint = c("keys", "municipality", "stats", "fraud"))pix_columns(endpoint = c("keys", "municipality", "stats", "fraud"))
endpoint |
Character string specifying the endpoint. One of: "keys", "municipality", "stats", or "fraud". |
A tibble::tibble with column names, types, and descriptions.
pix_columns("keys") pix_columns("municipality") pix_columns("stats") pix_columns("fraud")pix_columns("keys") pix_columns("municipality") pix_columns("stats") pix_columns("fraud")
Returns information about all available endpoints in the BCB PIX Open Data API.
pix_endpoints()pix_endpoints()
A tibble::tibble with endpoint names, descriptions, parameters, and associated functions.
pix_endpoints()pix_endpoints()
Tests the connection to all BCB PIX Open Data API endpoints. Each endpoint is tested with a single record request (top=1).
pix_ping()pix_ping()
A tibble (invisibly) with columns:
Name of the endpoint tested
Result: "OK" or error message
Time taken for the request in seconds
## 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)## 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)
Low-level function to fetch data from any PIX API endpoint with custom parameters.
pix_query( endpoint, params = NULL, filter = NULL, select = NULL, orderby = NULL, top = NULL, skip = NULL, format = "json", verbose = TRUE )pix_query( endpoint, params = NULL, filter = NULL, select = NULL, orderby = NULL, top = NULL, skip = NULL, format = "json", verbose = TRUE )
endpoint |
Character string specifying the endpoint name. |
params |
Named list of endpoint parameters. Each endpoint requires different parameters:
|
filter |
OData filter expression as a character string. |
select |
Character vector of columns to select. |
orderby |
OData orderby expression as a character string. |
top |
Integer; maximum number of records to return. |
skip |
Integer; number of records to skip. |
format |
Response format: "json" (default), "xml", "csv", or "html". |
verbose |
Logical; if TRUE, prints progress messages. |
A tibble::tibble with the raw API response data.
## 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)## 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 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.
pix_timeout(seconds = NULL)pix_timeout(seconds = NULL)
seconds |
Integer; timeout in seconds. If NULL, returns the current timeout. |
pix_timeout(): Returns the current timeout in seconds (invisibly when setting).
When called with seconds, sets the timeout and returns the new value invisibly.
# 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)# 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)
Builds and returns the URL that would be called by a PIX API function. Useful for debugging and testing.
pix_url( endpoint, params = NULL, filter = NULL, select = NULL, orderby = NULL, top = NULL, skip = NULL, format = "json" )pix_url( endpoint, params = NULL, filter = NULL, select = NULL, orderby = NULL, top = NULL, skip = NULL, format = "json" )
endpoint |
Character string specifying the endpoint name. |
params |
Named list of endpoint parameters. Each endpoint requires different parameters:
|
filter |
OData filter expression as a character string. |
select |
Character vector of columns to select. |
orderby |
OData orderby expression (e.g., "Column asc" or "Column desc"). |
top |
Integer; maximum number of records to return. |
skip |
Integer; number of records to skip. |
format |
Response format: "json" (default), "xml", "csv", or "html". |
Character string with the full API URL.
# 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)# 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)
Converts a year-month string in "YYYYMM" format to a Date object (first day of the month).
year_month_to_date(year_month)year_month_to_date(year_month)
year_month |
Character vector of year-month strings in "YYYYMM" format. |
A Date vector.
year_month_to_date("202312") year_month_to_date(c("202301", "202302", "202303"))year_month_to_date("202312") year_month_to_date(c("202301", "202302", "202303"))