SynCCFD

Synthetic Credit Card Fraud Detection — a transaction & fraud data simulator.

SynCCFD generates realistic synthetic credit card transaction data with labelled fraud, for research and benchmarking of fraud-detection models. It produces customer profiles, terminal profiles, and a fully labelled transaction stream — no real cardholder data required.

📖 Documentation: https://synccfd.readthedocs.io/en/latest/

The simulator is a direct evolution of the one in the Reproducible Machine Learning for Credit Card Fraud Detection handbook (Le Borgne et al., 2022), extended for the work described in our SBSeg 2024 paper with three contributions:

• Transaction type — Card-Present (CP) vs Card-Not-Present (CNP), affecting timing, locations, and fraud behaviour.
• A realistic geography — locations are sampled from Brazilian municipalities, weighted by population, instead of a uniform grid.
• A new fraud scenario — lost/stolen physical card, plus billing / terminal / shipping locations per transaction.

Installation

pip install synccfd

From source, for development:

git clone https://github.com/alexandreclem/synccfd
cd synccfd
pip install -e ".[dev]"

Optional extras: .[examples] (plotting + notebooks), .[docs] (Sphinx).

Quickstart

from synccfd import DatasetGenerator

generator = DatasetGenerator(
    n_customers=1000,
    n_terminals=2000,
    nb_days=30,
    start_date="2025-01-01",
    random_state=42,
)

customer_profiles, terminal_profiles, transactions = generator.generate()

print(transactions.shape)
print(f"Fraud rate: {100 * transactions.TX_FRAUD.mean():.2f}%")

generate() returns three DataFrames and does not touch the disk. Persist a dataset explicitly when you want it (day-partitioned files, following the handbook convention):

generator.save(output_dir="data", save_format="parquet")

# ...later, load a date range back:
txs = generator.read_transactions(
    begin_date="2025-01-01",
    end_date="2025-01-30",
    save_format="parquet",
    data_dir="data",
)

See examples/simulator.ipynb for a full walkthrough with plots.

Output schema

transactions

customer_profiles: CUSTOMER_ID, billing_lat, billing_long, mean_amount, std_amount, mean_nb_tx_per_day, cnp_prob.

terminal_profiles: TERMINAL_ID, terminal_lat, terminal_long.

Fraud scenarios

Reproducibility & scope

• Passing random_state makes a run fully reproducible.
• Locations are drawn from Brazilian municipality data bundled with the package (population-weighted). SynCCFD currently models a Brazil-based network.

Citation

If you use SynCCFD in academic work, please cite the paper it is based on (a machine-readable CITATION.cff is included):

A. C. B. dos Santos, R. de S. Passos, L. D. T. J. Tarrataca, D. de O. Cardoso, D. B. Haddad, F. da R. Henriques. Construção de um Modelo Orientado a Dados para Detecção de Fraudes em Cartões de Crédito utilizando Dados Sintéticos. Anais do SBSeg 2024 (Artigos Curtos). https://sol.sbc.org.br/index.php/sbseg/article/view/30067/29874

Contributing

Contributions are welcome. Please open an issue to discuss substantial changes first, run ruff check . and pytest before submitting, and update tests as appropriate.

License

MIT