ofxstatement-paypal-2 3.3.0

Plugin for ofxstatement that supports conversion from PayPal CSV to OFX

ofxstatement-paypal

PayPal CSV → OFX converter plugin for ofxstatement.

This repository is a maintained fork of the original project, created so the plugin can continue evolving and staying compatible with recent PayPal exports.

1. What this project is for

Use this plugin if you:

• export your account activity from PayPal as CSV,
• want to import it into software that understands OFX,
• already use tools such as GnuCash, HomeBank, Odoo, Tryton, or any other application that accepts OFX bank statements.

In short: this plugin reads a PayPal CSV export, parses the transactions, and produces an OFX statement that downstream finance tools can import.

More details: audience, scope, and supported behavior

Who this is aimed at

This project is primarily for end users who want to move PayPal transactions into personal finance or accounting software, and for maintainers who want a reliable, scriptable CSV → OFX conversion flow.

What it does

• plugs into ofxstatement, the generic bank-statement conversion tool,
• parses PayPal “Bank statements” CSV exports,
• infers the date format when possible,
• infers the statement currency when the CSV contains exactly one currency,
• sorts rows chronologically before processing,
• handles PayPal currency-conversion groups so foreign-currency purchases do not break OFX balances.

What it does not do

• it does not download statements from PayPal for you,
• it does not replace ofxstatement; it extends it,
• it does not produce one multi-currency OFX file, because OFX statements are single-currency by design.

Project background

The original project was based on earlier work by gerasiov: https://github.com/gerasiov/ofxstatement-paypal/.

2. Install and configure it minimally

For most users, install the package and run it with no manual configuration:

pip3 install ofxstatement-paypal-2
ofxstatement convert -t paypal-convert input.csv output.ofx

If you already use an ofxstatement config file, create a section that points to this plugin:

[paypal-convert]
plugin = paypal-convert

Then use that section name with -t.

More details: installation, configuration, auto-detection, and multi-currency exports

Install from PyPI

pip3 install ofxstatement-paypal-2

Install from source

git clone https://github.com/Alfystar/ofxstatement-paypal-2.git
cd ofxstatement-paypal-2
python3 -m pip install --upgrade build
python3 -m build --sdist --wheel
python3 -m pip install dist/ofxstatement_paypal_2-<version>.tar.gz

Replace <version> with the version you just built.

When config is optional

If no config.ini is loaded, you can call the plugin directly by its registered name:

ofxstatement convert -t paypal-convert input.csv output.ofx

If a personal ofxstatement config file exists, -t is interpreted as a section name in that file, so the most stable setup is a section such as:

[paypal-convert]
plugin = paypal-convert

What the plugin auto-detects

When you omit settings, the plugin tries to infer them from the CSV:

Setting	Inferred from	Fallback
dataformat	Date column: . → %d.%m.%Y, - → %Y-%m-%d, / → DMY/MDY decided by the file contents	Raises if the separator is not recognized
default_currency	The CSV's only currency, when there is just one	Raises if there are zero currencies or more than one
default_account	—	"PayPal"
charset	—	UTF-8

The inferred values are logged at INFO level so you can check what the parser decided.

Multi-currency exports

PayPal mixes all balances into one CSV, but OFX is single-currency. That means:

• if the CSV contains only one currency, the plugin exports it directly;
• if the CSV contains multiple currencies and default_currency is not set, parsing stops and asks you to choose one.

To export each currency separately, define one config section per currency:

[paypal-convert-eur]
plugin = paypal-convert
default_currency = EUR

[paypal-convert-gbp]
plugin = paypal-convert
default_currency = GBP

[paypal-convert-usd]
plugin = paypal-convert
default_currency = USD

Then run the conversion once per section:

ofxstatement convert -t paypal-convert-eur input.csv output.eur.ofx
ofxstatement convert -t paypal-convert-gbp input.csv output.gbp.ofx
ofxstatement convert -t paypal-convert-usd input.csv output.usd.ofx

Overriding inferred settings

Run:

ofxstatement edit-config

Then add a section like:

[paypal-convert-custom]
plugin = paypal-convert
encoding = utf-8
dataformat = %%d/%%m/%%Y
default_currency = EUR
default_account = Paypal Personal

Useful fields:

• dataformat: the strptime format matching your CSV date column,
• default_currency: target statement currency (EUR, USD, GBP, ...),
• default_account: account label written into the OFX output.

Existing configurations that already say plugin = paypal-convert keep working unchanged after upgrade.

3. Use it with the minimal workflow

1. In PayPal, download a CSV from History → Download → customized → Bank statements.
2. Open a terminal in the folder that contains the CSV.
3. Convert it:

ofxstatement convert -t paypal-convert input.csv output.ofx

If you use a named config section instead, replace paypal-convert with your section name.

More details: where to get the CSV, aliases, anonymizing, and OFX consumers

Where to get the CSV in PayPal

From the PayPal web interface, download a CSV of Bank statements for the report period you want.

Optional shell alias

If you want a shorter command, add an alias. Example for bash:

printf '\n# Paypal CSV convert to OFX format\nalias ofxPaypal="ofxstatement convert -t paypal-convert"\n' >> ~/.bash_aliases

After reloading your shell, you can run:

ofxPaypal Paypal.csv Paypal.ofx

If your shell does not load ~/.bash_aliases, make sure your ~/.bashrc contains something like:

if [ -f ~/.bash_aliases ]; then
    . ~/.bash_aliases
fi

Foreign-currency purchases

PayPal often exports a foreign-currency purchase as a four-row group. The plugin collapses the redundant rows and annotates the statement-currency leg with <ORIGCURRENCY>, so OFX consumers can still display the original amount.

Anonymizing a PayPal CSV before sharing it

If you need to attach a real CSV to a bug report, you can scrub it with:

python3 scripts/anonymize_paypal.py input.csv output.csv [--seed N]

The script removes personally identifying data while preserving the structure, locale, arithmetic, and transaction cross-references that the parser needs.

What to do with the generated OFX file

Once you have the OFX file, you can import it into software that accepts OFX. One good open-source option is HomeBank, which works well with the generated files.

4. For maintainers

Release packages to PyPI

If you are publishing a new release:

1. Update the version in pyproject.toml.
2. Run tests and any checks you want before release.
3. Remove old build artifacts.
4. Build the package.
5. Optionally validate the artifacts with twine check.
6. Upload them to PyPI.

With Pipenv

pipenv install --dev
pipenv run python -m unittest discover -s tests
rm -rf dist/
pipenv run python -m build
pipenv run python -m twine check dist/*
pipenv run python -m twine upload dist/*

With a plain virtualenv

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m unittest discover -s tests
rm -rf dist/
.venv/bin/python -m build
.venv/bin/python -m twine check dist/*
.venv/bin/python -m twine upload dist/*

TestPyPI first

pipenv run python -m twine upload --repository testpypi dist/*

twine authentication is usually handled via an API token stored in the environment or in ~/.pypirc.