DoDataThings / distilbert-us-transaction-classifier-v2

DistilBERT US Bank Transaction Classifier v2

A fine-tuned DistilBERT model that classifies US bank transaction descriptions into 17 spending categories. Uses a [debit] / [credit] sign prefix to disambiguate transaction direction — a payroll deposit and a Venmo payment look similar in text but mean opposite things financially.

Successor to v1 , which classified on description text alone. v2 adds sign-aware input, expanded merchant coverage (500+), multi-format training across 8 bank statement structures, and PayPal as a first-class format.

How It Works

The model takes a sign prefix + transaction description and outputs one of 17 categories:

Input:  "[debit] STARBUCKS #1234 SAN FRANCISCO CA"
Output: Restaurants (0.99)

Input:  "[credit] Patelco CU       PAYROLL                    PPD ID: 321076470"
Output: Income (1.00)

Input:  "[debit] CHASE CREDIT CRD AUTOPAY                    PPD ID: 4760039224"
Output: Transfer (1.00)

Input:  "[debit] PreApproved Payment Bill User Payment: Netflix"
Output: Subscription (1.00)

The sign prefix encodes the transaction direction from the cardholder's perspective:

• [debit] — money left the account (purchases, payments out, fees)
• [credit] — money entered the account (income, refunds, payments received)

This is critical for distinguishing Income from Transfer. [credit] VENMO CASHOUT is Income (money arriving). [debit] VENMO PAYMENT TO JOHN SMITH is Transfer (money leaving). The description alone can't tell you which.

Categories (17)

Account-Type-Implied Categories

If you know the account type, some categories can be assigned without the model:

For checking, savings, and credit card accounts, use the model.

Training

Model:       DistilBERT-base-uncased + LoRA (r=32, alpha=64)
Dataset:     68,000 synthetic samples (4,000 per category)
Trainable:   1.8M / 68.7M parameters (2.6%)
Training:    20 epochs, best at epoch 16
Validation:  99.9% accuracy (15 of 17 categories at 100%)

Multi-Format Training

The model is trained on 8 bank statement formats so it classifies correctly regardless of which bank produced the description:

PayPal formats appear across all spending categories at meaningful rates, reflecting that people use PayPal cards at any merchant.

Honest Assessment

The 99.9% validation accuracy is on synthetic data. On ~2,000 real transactions:

• 96.1% of model classifications at 0.90+ confidence
• < 0.5% below 0.50 confidence
• 17 bank-category fallbacks (obscure merchants where the model defers)
• Shopping is the weakest category due to overlap with Subscription and Groceries
• Niche/unknown merchants may classify with lower confidence — use merchant rules for known edge cases

Usage

Python

from transformers import pipeline

classifier = pipeline("text-classification", model="DoDataThings/distilbert-us-transaction-classifier-v2")

# Sign prefix required
result = classifier("[debit] STARBUCKS #1234 SAN FRANCISCO CA")
print(result)  # [{'label': 'Restaurants', 'score': 0.99}]

# Sign matters for ambiguous transactions
classifier("[credit] VENMO CASHOUT PPD ID: 12345678")
# [{'label': 'Income', 'score': 0.95}]

classifier("[debit] VENMO PAYMENT TO JOHN SMITH")
# [{'label': 'Transfer', 'score': 0.97}]

# Works across all bank formats
classifier("[debit] PreApproved Payment Bill User Payment: Netflix")
# [{'label': 'Subscription', 'score': 1.00}]

classifier("[debit] PP*SAFEWAY")
# [{'label': 'Groceries', 'score': 1.00}]

JavaScript (Transformers.js)

const { pipeline } = require('@xenova/transformers');

const classifier = await pipeline(
  'text-classification',
  'DoDataThings/distilbert-us-transaction-classifier-v2'
);

const result = await classifier('[debit] STARBUCKS #1234');
// [{ label: 'Restaurants', score: 0.99 }]

An ONNX export is included in the onnx/ subdirectory.

Design Decisions

• Sign prefix, not account type. We considered passing account type (checking, credit, etc.) as a feature but concluded that sign alone provides the disambiguation signal. Account type is an upstream routing concern — it determines which classifier runs, not what the classifier outputs.
• 17 model categories + 6 account-type categories. Mortgage is both a model category (for classifying mortgage descriptions on checking accounts) and an account-type-implied category (for mortgage account transactions). This serves both use cases — people with account type metadata and people with just transaction descriptions.
• PayPal as a bank format, not a wrapper. PayPal is a card issuer. People use PayPal cards at restaurants, grocery stores, and everywhere else. The training data treats PayPal formats as first-class bank statement structures across all categories.
• Synthetic data with real formats. The training data is synthetic but models real bank statement patterns — Chase ACH padding, Apple Card address formats, Capital One action prefixes, Mercury's minimal format. The generator is open source so you can extend it.

Training Data

The dataset is published at DoDataThings/us-bank-transaction-categories-v2 .

Generator

The synthetic data generator is open source:

node scripts/generate-training-data.js --count 4000  # 4,000 per category

Available at github.com/wnstnb/foliome .

Limitations

• US bank formats only — Trained on Chase, Apple Card, PayPal, Capital One, Mercury, and US Bank patterns
• Synthetic training data — May miss patterns from banks not represented
• Shopping is the weakest category due to overlap with Subscription and Groceries
• Sign prefix required — Passing raw descriptions without [debit] / [credit] will degrade accuracy
• Not a standalone solution — Best results come from combining with merchant rules and account-type classification

License

Apache 2.0