DEV Community: Violet Vault Team

From raw bank descriptors to spending charts: merchant names, categories and a review queue in JavaScript

Violet Vault Team — Mon, 26 Oct 2026 21:16:51 +0000

Disclosure: this post is written by the team that builds Merchant Cleanup API, the service used below. All merchants in it are made up.

A spending chart is only as good as its labels. Group raw bank lines and a user who bought coffee twice at one shop sees two bars, neither saying "coffee". This post builds the pipeline between a transactions table and a chart: clean each descriptor into a merchant and category, aggregate, queue the unsure lines for review, and never look up the same descriptor twice.

For what SQ *, TST* and the trailing numbers mean, the first post in this series covers that plus a DIY regex cleaner.

The input

Fourteen made-up rows of {date, description, amount}, some with an optional mcc, as they'd arrive from a bank export. The descriptions:

SQ *MAPLE STREET COFFEE 1234 OAKLAND CA   (x2)
TST* JOES DINER #0042 AUSTIN TX           (x2)
MAPLE STREET MARKET 0091                  (x2, MCC 5411)
RIVERSIDE FUEL 00123 DENVER CO            (MCC 5541)
BRAMBLEGATE PHARMACY #212 PORTLAND OR
OAKHOLLOW FITNESS MONTHLY DUES
LANTERNWOOD CINEMA 8 SPOKANE WA
QUILLBROOK WATER UTIL ONLINE PMT
PINEHILLBOOK 4029357733 CA
ZPHR*KT 88412 WWW
GLIMMERBY BAKERY 0007 BOISE ID

Only eleven are distinct. That gap is the first optimization.

What one call returns

Get a free key at /signup (email only) and keep it server-side. A batch call with two of the lines above:

curl -X POST https://merchantcleanup.pages.dev/v1/clean \
  -H "Authorization: Bearer $MERCHANT_CLEANUP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"descriptors": ["OAKHOLLOW FITNESS MONTHLY DUES", "PINEHILLBOOK 4029357733 CA"]}'

Real response:

{
  "results": [
    {"input": "OAKHOLLOW FITNESS MONTHLY DUES", "merchant": "Oakhollow Fitness Monthly Dues", "category": "other", "confidence": 0.6, "match": "keyword", "processor": null, "is_subscription": true},
    {"input": "PINEHILLBOOK 4029357733 CA", "merchant": "Pine Hill Book", "category": "other", "confidence": 0.45, "match": "cleaned_text", "processor": null, "is_subscription": false}
  ],
  "count": 2
}

Three fields matter for charts:

category is one of 23 fixed values (meals, groceries, health...), so map each to a color once.
confidence is a heuristic score (0.6 for a keyword rule, about 0.7 with an MCC, 0.45 or lower for cleaned raw text). It measures evidence strength, not how often results are right, but it makes a good threshold.
is_subscription flags recurring-looking charges: the gym line is other but true here, which suits a "recurring charges" widget.

The pipeline

Node 18+, no dependencies. It dedupes, checks a cache, batches up to 10 per request (the Free plan limit) and backs off on 429:

import { readFile } from "node:fs/promises";

const API = "https://merchantcleanup.pages.dev/v1/clean";
const BATCH = 10;         // Free plan: up to 10 descriptors per request
const REVIEW_BELOW = 0.5; // confidence threshold for the review queue
const keyOf = (d) => d.trim().toUpperCase().replace(/\s+/g, " ");

async function cleanBatch(items) {
  const res = await fetch(API, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MERCHANT_CLEANUP_KEY}`,
      "Content-Type": "application/json",
      "User-Agent": "budget-demo/1.0",
    },
    body: JSON.stringify({ descriptors: items }),
  });
  if (res.status === 429) {
    const wait = Number(res.headers.get("retry-after") || 30);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return cleanBatch(items);
  }
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return (await res.json()).results; // same order as items
}

// cache: any Map-like store keyed by normalized descriptor
export async function enrich(txns, cache) {
  const todo = new Map();
  for (const t of txns) {
    const k = keyOf(t.description);
    if (!cache.has(k) && !todo.has(k))
      todo.set(k, t.mcc ? { descriptor: t.description, mcc: t.mcc } : t.description);
  }
  const keys = [...todo.keys()];
  for (let i = 0; i < keys.length; i += BATCH) {
    const chunk = keys.slice(i, i + BATCH);
    const results = await cleanBatch(chunk.map((k) => todo.get(k)));
    chunk.forEach((k, j) => cache.set(k, results[j]));
  }
  console.error(`looked up: ${keys.length}, requests: ${Math.ceil(keys.length / BATCH)}`);
  return txns.map((t) => ({ ...t, clean: cache.get(keyOf(t.description)) }));
}

Results come back in input order, so zipping them with chunk is safe. An unreadable line returns an error in its slot instead of failing the batch.

Aggregate into chart-ready JSON

Anything below the threshold goes into a needs_review bucket instead of polluting a real category:

export function toChart(rows) {
  const buckets = new Map();
  const review = [];
  for (const { date, description, amount, clean } of rows) {
    const unsure = clean.error || clean.confidence < REVIEW_BELOW;
    if (unsure) review.push({ date, description, amount, suggestion: clean.merchant ?? null,
                              category: clean.category ?? null, confidence: clean.confidence ?? null });
    const cat = unsure ? "needs_review" : clean.category;
    const b = buckets.get(cat) ?? { category: cat, total: 0, count: 0, merchants: new Set() };
    b.total += -amount; b.count++; b.merchants.add(clean.merchant ?? description);
    buckets.set(cat, b);
  }
  const series = [...buckets.values()]
    .map((b) => ({ ...b, total: Math.round(b.total * 100) / 100, merchants: [...b.merchants] }))
    .sort((a, b) => b.total - a.total);
  return { series, review };
}

const txns = JSON.parse(await readFile("./transactions.json", "utf8"));
const cache = new Map();
console.log(JSON.stringify(toChart(await enrich(txns, cache)), null, 2));
await enrich(txns, cache); // the same import again

Real stderr, first import then repeat:

looked up: 11, requests: 2
looked up: 0, requests: 0

Real stdout (review trimmed to one of five entries):

{
  "series": [
    { "category": "groceries", "total": 109.95, "count": 2, "merchants": ["Maple Street Market"] },
    { "category": "needs_review", "total": 83.89, "count": 5,
      "merchants": ["Bramblegate Pharmacy", "Lanternwood Cinema", "Pine Hill Book", "Zphr Kt", "Glimmerby Bakery"] },
    { "category": "meals", "total": 64.7, "count": 4, "merchants": ["Maple Street Coffee", "Joes Diner"] },
    { "category": "utilities_and_phone", "total": 61.33, "count": 1, "merchants": ["Quillbrook Water Util"] },
    { "category": "auto_and_transport", "total": 38.2, "count": 1, "merchants": ["Riverside Fuel"] },
    { "category": "other", "total": 35, "count": 1, "merchants": ["Oakhollow Fitness Monthly Dues"] }
  ],
  "review": [
    { "date": "2026-10-11", "description": "ZPHR*KT 88412 WWW", "amount": -12,
      "suggestion": "Zphr Kt", "category": "other", "confidence": 0.45 }
  ]
}

series maps straight onto most chart libraries: labels = series.map(s => s.category) and data = series.map(s => s.total). The two coffee visits and two diner visits merged into one meals bar.

The second import hit the cache for everything, so nothing went over the network. In production, back it with a table keyed on the normalized descriptor; merchants repeat month to month, so the cache does most of the work after the first import.

Working the review queue

Five rows landed in review, all at 0.45 with match: "cleaned_text": the name was cleaned, but nothing said what kind of business it was. Two ways to shrink the queue.

Send the MCC when you have it. If your data source gives a merchant category code, include it. Resending the pharmacy and cinema lines with MCCs 5912 and 7832 gave this real response (trimmed to the relevant fields):

[
  { "merchant": "Bramblegate Pharmacy", "category": "health", "confidence": 0.7,
    "match": "cleaned_text+mcc", "mcc_description": "Drug Stores and Pharmacies" },
  { "merchant": "Lanternwood Cinema", "category": "entertainment", "confidence": 0.7,
    "match": "cleaned_text+mcc", "mcc_description": "Motion Picture Theaters" }
]

Let the user decide, then remember it. Show review items with the suggested name prefilled and a category picker. Save the confirmed answer under the same cache key with source: "user", and never overwrite it with an API result. Only the buyer can label ZPHR*KT 88412 WWW.

Limits worth knowing

Sending 11 descriptors on the Free plan returned 413 batch_too_large ("At most 10 descriptors per request on this plan."). Chunk first.
Per-minute numbers are fair-use guidelines, not caps. Going well over can return 429 with Retry-After, which the code honors.
Results are automated suggestions; keep the review step for anything tax-related.

Pricing

The Free plan is available now: a free key with just an email, up to 10 descriptors per request. Paid plans are coming soon. Full reference is in the docs, and statement-code explainers are in the guides.

How does your app handle low-confidence lines? Share a made-up or scrubbed descriptor that trips your categorizer in the comments.

How to clean messy bank transaction descriptions (SQ , TST, PAYPAL *) into merchant names and categories

Violet Vault Team — Mon, 26 Oct 2026 16:18:42 +0000

Canonical note: this tutorial is published by the Merchant Cleanup team, who build the API shown in part 3. The reference docs live at merchantcleanup.pages.dev/docs.

If you've built a budgeting app, a bookkeeping export or a spending report, you've seen bank lines like these:

POS PURCHASE SQ *MAPLE STREET COFFEE 1234 OAKLAND CA
TST* JOES DINER #0042 AUSTIN TX
PAYPAL *PINEHILLBOOK 4029357733 CA
RIVERSIDE FUEL 00123 DENVER CO

Your users want to see "Maple Street Coffee: meals", not the raw string. This post covers what that noise is, a do-it-yourself cleaner, where the DIY version falls short, and an API option.

(All merchants in this post are made up.)

1. What the prefixes mean

A card descriptor is assembled by the merchant's payment processor and the card network, not by the merchant. The common pieces:

Piece	Example	Meaning
Processor prefix	`SQ `, `TST`, `PAYPAL *`	The payment processor or platform that took the payment (a point-of-sale provider, a restaurant POS, a wallet)
Channel words	`POS PURCHASE`, `DEBIT CARD`	How the bank recorded it
Store/terminal number	`#0042`, `1234`, `00123`	Location or terminal ID
Phone number	`4029357733`	Often the merchant's support line for online payments
City and state	`AUSTIN TX`	Where the terminal is registered

Descriptors are usually capped at around 22 to 25 characters for the merchant part, so names get truncated or squashed together (PINEHILLBOOK).

2. The DIY approach: a regex cleaner

For a first pass, strip known noise and title-case what's left:

const PREFIXES = /^(POS PURCHASE|DEBIT CARD PURCHASE|POS)\s+/i;
const PROCESSOR = /^(SQ \*|TST\* ?|PAYPAL \*)/i;
const TRAILING = /\s+(#?\d{3,}|\d{10})(\s+.*)?$/; // store numbers, phones, then city/state

function cleanDescriptor(raw) {
  let s = raw.trim().replace(PREFIXES, "");
  const processor = (s.match(PROCESSOR) || [null])[0];
  s = s.replace(PROCESSOR, "").replace(TRAILING, "");
  const merchant = s.toLowerCase().replace(/\b\w/g, c => c.toUpperCase());
  return { merchant, processor };
}

cleanDescriptor("TST* JOES DINER #0042 AUSTIN TX");
// { merchant: "Joes Diner", processor: "TST* " }

This gets you surprisingly far on a handful of known formats. Its limits show up quickly:

Prefix lists drift. Every processor has its own format, and new ones appear. You'll maintain the list forever.
No trailing number means no cut. MAPLE STREET MARKET OAKLAND CA keeps the city, because the regex only trims after a number.
Squashed names stay squashed. PINEHILLBOOK needs word knowledge, not a regex.
No category. A regex can tell you the text, not that it's a fuel station or a diner. For that you need keyword rules, a merchant list, or the merchant category code (MCC) if your data source provides one.

If your volume is small and your formats are fixed, the regex may be all you need. If not, read on.

3. Using the Merchant Cleanup API

Merchant Cleanup is a small REST/JSON API: send descriptors, get back a cleaned merchant name, one of 23 categories, the detected processor and a confidence score from 0 to 1. The confidence is a rough guide to how much evidence there was, not a measured accuracy rate, and results are automated suggestions, so check anything that matters for taxes or bookkeeping.

Try one line without a key using the demo endpoint (one descriptor per request, limited per IP per day):

curl "https://merchantcleanup.pages.dev/v1/demo?q=TST*%20JOES%20DINER%20%230042%20AUSTIN%20TX"

For real use, get a free key at /signup (email only, no card). Keys start with mcl_; keep them server-side.

curl

curl -X POST https://merchantcleanup.pages.dev/v1/clean \
  -H "Authorization: Bearer $MCL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"descriptor": "POS PURCHASE SQ *MAPLE STREET COFFEE 1234 OAKLAND CA"}'

Real response:

{
  "input": "POS PURCHASE SQ *MAPLE STREET COFFEE 1234 OAKLAND CA",
  "merchant": "Maple Street Coffee",
  "category": "meals",
  "confidence": 0.6,
  "match": "keyword",
  "processor": "Square"
}

match tells you how the result was reached: merchant_list, keyword, mcc, processor_hint, cleaned_text or none.

JavaScript (Node 18+, built-in fetch)

Batch requests take up to 10 descriptors on the Free plan. Each item can be a string or an object with an optional mcc and amount:

const res = await fetch("https://merchantcleanup.pages.dev/v1/clean", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MCL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    descriptors: [
      "TST* JOES DINER #0042 AUSTIN TX",
      "PAYPAL *PINEHILLBOOK 4029357733 CA",
      { descriptor: "RIVERSIDE FUEL 00123 DENVER CO", mcc: "5541", amount: -38.2 },
    ],
  }),
});
const { results } = await res.json();
for (const r of results) console.log(r.merchant, "->", r.category, r.confidence);

Real output:

Joes Diner -> meals 0.5
Pinehillbook -> other 0.45
Riverside Fuel -> auto_and_transport 0.7

Two things worth noticing. Sending the MCC helped: the fuel line came back as keyword+mcc with an mcc_description of "Service Stations". And the squashed PINEHILLBOOK came back as Pinehillbook with category other and a lower confidence. That's the API being honest about thin evidence, and it's a good place to set a threshold and let users correct the result.

Python (requests)

import os, requests

resp = requests.post(
    "https://merchantcleanup.pages.dev/v1/clean",
    headers={"Authorization": f"Bearer {os.environ['MCL_KEY']}"},
    json={"descriptors": [
        "TST* JOES DINER #0042 AUSTIN TX",
        {"descriptor": "RIVERSIDE FUEL 00123 DENVER CO", "mcc": "5541"},
    ]},
    timeout=10,
)
resp.raise_for_status()
for r in resp.json()["results"]:
    if "error" in r:
        print("could not read:", r["input"], r["error"])
    elif r["confidence"] < 0.5:
        print("review:", r["input"], "->", r["merchant"])
    else:
        print(r["merchant"], r["category"])

Batch results come back in input order, and a line that can't be read returns an error in its slot instead of failing the whole batch.

Errors to handle

401: missing or invalid key
413: batch larger than your plan allows (more than 10 descriptors on the Free plan)
429: you went well over the fair-use rate; back off and retry

Pricing, briefly

The Free plan is available now: get a free key with just an email (no card) and send up to 10 descriptors per request. Batch size is the only hard limit. The per-minute number (about 10 requests a minute on Free) is a fair-use guideline, not a cap or a guarantee. Paid plans are coming soon.

Details are in the docs.

Wrap-up

Processor prefixes like SQ *, TST* and PAYPAL * name who processed the payment, not the merchant.
A regex cleaner handles fixed formats but needs constant upkeep and can't assign categories.
An API call gives you a name, a category, the processor and a confidence you can threshold on.

The OpenAPI spec works with most client generators. Questions or a descriptor it handles badly? Leave it in the comments (with any real merchant details removed).