Why pdfplumber or Tabula output breaks on bank statements, and the layout rules, Decimal amount parsing, running-balance checks and safe de-duplication that fix it.
A bank statement can look like a clean table and still extract as a pile of unrelated words. If you've tried pdfplumber, Tabula or Camelot and received descriptions in the balance column, the problem may be the document's structure rather than your library choice.
I approach statement parsing as reconstruction: recover candidate rows from positioned text, interpret them using layout rules, and check the result against accounting constraints. A plausible spreadsheet is only the beginning. The numbers need to explain each other.
Every example below is synthetic. Names such as ACME SUPPLY CO and ZELLE PAYMENT TO J SMITH represent invented transactions.
1. Why generic table extraction fails
Start with a typical US checking statement: Date | Description | Amount | Balance. Even this familiar structure might exist only visually. There are no ruling lines, and columns are implied by text positions. A long description wraps underneath itself; a right-aligned amount starts at a different x-coordinate depending on its length.
Deposits, withdrawals and checks may also live in separate sections. A check list might use check numbers and amounts without a balance on every row. Section headings can determine transaction direction when the amount itself has no sign.
Meanwhile, repeating headers, page numbers, footers and summary blocks compete with transactions. An opening balance contains money but isn't a deposit. A monthly total contains money but isn't another withdrawal. Extracting everything that resembles a row creates a convincing, incorrect result.
These heuristics assume a PDF with extractable text. An image-only scan needs OCR first, and OCR adds another source of uncertainty.
2. Reconstruct rows using layout heuristics
I first look for a header containing keywords such as date, description, amount and balance. Matching should tolerate capitalization and known alternatives, but stay scoped to a section: a summary can contain the same words.
Header x-coordinates provide initial column anchors. Midpoints between adjacent anchors are a useful first approximation for boundaries. Check those against body text and expected alignment; centered headings and right-aligned numbers often need layout-specific adjustments. Assign words to columns before deciding what a line means.
Here's a small sketch of the geometry step. The header finder assumes single-word headings; compound headings need explicit aliases or phrase matching.
import re import pdfplumber DATE = re.compile(r"\d{1,2}/\d{1,2}(?:/\d{2,4})?\Z") def group_lines(words, tolerance=3): lines = [] for word in sorted(words, key=lambda w: (w["top"], w["x0"])): if not lines or abs(word["top"] - lines[-1][0]["top"]) > tolerance: lines.append([word]) else: lines[-1].append(word) return [sorted(line, key=lambda w: w["x0"]) for line in lines] def header_boundaries(line): required = ("date", "description", "amount", "balance") anchors = {} for word in line: key = word["text"].lower().strip(":") if key in required: anchors[key] = (word["x0"] + word["x1"]) / 2 if not all(key in anchors for key in required): return None positions = [anchors[key] for key in required] if positions != sorted(positions) or len(set(positions)) != 4: return None return [(a + b) / 2 for a, b in zip(positions, positions[1:])] def columns(line, boundaries): cells = [[], [], [], []] for word in line: center = (word["x0"] + word["x1"]) / 2 index = sum(center >= edge for edge in boundaries) cells[index].append(word["text"]) return [" ".join(cell) for cell in cells] # Inside a PDF-reading function: # with pdfplumber.open(path) as pdf: # lines = group_lines(pdf.pages[0].extract_words()) Classify lines after removing recognized noise. A transaction-start has a date token in the left date column. A continuation has no date and no amount; append its description to the pending transaction. A repeated header, Page 2 of 5, disclaimer or opening/closing summary line is noise for transaction extraction. Capture summary balances separately for validation.
Don't append every dateless line automatically: first restrict it to the transaction region and reject known noise. A dateless line containing money is an unresolved fragment, not a safe continuation. Keep it for review.
The date regex recognizes shape, not meaning. Parse actual dates using the statement's configured convention and period. US 03/04/2026 normally means March 4; UK/AU DD/MM/YYYY means 3 April. When both readings are possible and the layout is unknown, require confirmation. Infer omitted years from the statement period, including December-to-January transitions.
3. Parse amounts without losing meaning
Use Decimal, never float, for money. Parentheses, trailing minus and CR/DR suffixes can encode direction. Strip currency symbols and validate grouping before removing commas, including Indian lakh grouping such as 1,00,000.00.
This parser assumes a decimal point and comma grouping. It treats CR as positive and DR as negative in transaction amounts; balance labels and account types may require different semantics.
from decimal import Decimal import re NUMBER = re.compile( r"(?:\d+|\d{1,3}(?:,\d{3})+|" r"\d{1,2}(?:,\d{2})*,\d{3})(?:\.\d+)?\Z" ) def parse_amount(raw): text = raw.strip().upper() signs = [] if text.endswith(("CR", "DR")): signs.append(1 if text[-2:] == "CR" else -1) text = text[:-2].strip() if text.startswith("(") and text.endswith(")"): signs.append(-1) text = text[1:-1].strip() if text.endswith("-"): signs.append(-1) text = text[:-1].strip() text = re.sub(r"[$£₹€]", "", text).strip() if text.startswith(("+", "-")): signs.append(-1 if text[0] == "-" else 1) text = text[1:].strip() if len(set(signs)) > 1: raise ValueError("Conflicting amount signs") if not NUMBER.fullmatch(text): raise ValueError(f"Invalid amount: {raw!r}") return Decimal(text.replace(",", "")) * (signs[0] if signs else 1) For an unsigned US withdrawal section, the section supplies direction. For an Indian statement with separate Dr/Cr columns, map their magnitudes to debit and credit explicitly. Don't negate a DR value twice. Preserve the raw token and its column so interpretation remains inspectable.
4. Let balances challenge the extraction
Normalize transactions into nonnegative credit and debit fields plus an optional signed balance. For a conventional checking account, the invariant is:
previous balance + credit - debit == current balance
ZERO = Decimal("0") def balance_errors(rows, opening, closing): previous = opening errors = [] for index, row in enumerate(rows): if row["credit"] < ZERO or row["debit"] < ZERO: raise ValueError("Credit and debit must be nonnegative") expected = previous + row["credit"] - row["debit"] actual = row.get("balance") if actual is not None and expected != actual: errors.append((index, expected, actual)) previous = expected if previous != closing: errors.append(("closing", previous, closing)) return errors This keeps the computed chain anchored to the opening balance. If rows lack individual balances, it accumulates amounts until the next available checkpoint. The closing comparison also checks opening + credits - debits == closing.
A mismatch can suggest a missed row, split row, sign flip or wrong column. It doesn't identify the cause by itself. A difference of twice a transaction amount suggests a reversed sign; an isolated amount-sized difference suggests an omission. Investigate instead of automatically repairing either.
Separate sections may need ordering from explicit sequence information before running checks. Dates alone cannot order same-day transactions. Where the statement supplies only section totals and opening/closing balances, validate those constraints and acknowledge the weaker evidence.
5. Handle page breaks as boundaries, not resets

Page breaks are where rows go missing (Parse Statement blog).
Keep the pending transaction across pages. If page N ends with a description and page N+1 starts with description text, remove the new page's header and footer, then consider joining the fragment. Check column alignment and whether another transaction has started before committing the join.
“Balance brought forward†and “balance carried forward†lines are checkpoints, not transactions. Compare their balances with the chain; don't add their amounts to credits or debits.
Some layouts repeat the last transaction from page N at the top of page N+1. A global drop_duplicates() can erase legitimate repeated payments, especially when individual balances aren't available.
I would only drop a candidate if all four normalized fields match exactly: date, description, signed amount and balance. Both balances must be present. The rows must also straddle an actual page boundary, with one the last transaction on N and the other the first on N+1.
Finally, tentatively remove the repeated copy and rerun the balance checks across that boundary and through the closing balance. Remove it only when the balance chain still validates. Retain provenance for the removed copy. If ordering, missing balances or other mismatches prevent that proof, flag the candidate for human review instead of silently deleting it.
6. Combine layout parsers, AI and review
My preference is dedicated per-layout parsers for known formats, an AI fallback for unknown layouts, and a human review screen. Layout rules make assumptions explicit. A fallback helps with unfamiliar structures, but its output should enter the same normalized schema and face the same checks.
Validate dates, amount syntax, required fields and balances regardless of which path produced the rows. Preserve page references and raw text so a reviewer can resolve uncertainty against the source. A fluent description and tidy JSON aren't evidence that every transaction was found.
Review should expose mismatches and ambiguous fragments, with enough context to correct them before export.
7. Test the awkward cases
Build golden files from synthetic or carefully redacted statements, pairing each PDF with expected normalized rows and validation results. Never commit real customer statements. Redaction must remove underlying text and metadata, not just cover visible names with rectangles.
Keep regression cases per layout variant: wrapped descriptions, repeated headers, missing balances, separate check sections, year boundaries, Dr/Cr columns and lakh grouping. Include genuine identical payments alongside page-boundary repeats so deduplication can't pass by deleting both indiscriminately.
Small tests can exercise the code without PDFs: (12.50) becomes -12.50, 1,00,000.00 CR becomes 100000.00, and an opening balance of 100 plus a credit of 25 minus a debit of 10 closes at 115. Also test malformed grouping and conflicting signs. Golden PDF tests then cover the geometry those unit tests can't reach.
8. Before exporting
I build Parse Statement, a web app that converts bank and credit card statement PDFs to Excel, CSV, QuickBooks CSV and Xero CSV. It combines dedicated parsers for known formats, generic fallback parsing, AI fallback and review screens. Gap checks and running-balance validation act as review signals before download, and the first 5 pages are free.
Disclosure: I build Parse Statement.
Which statement edge cases have you hit, and what finally made them parse correctly?
