Raw transaction descriptors are not merchant records. They are processor output, card-network text, location hints, store numbers, billing wrappers, and sometimes a partial merchant name. Treating every cleanup as certain creates bad product behavior: wrong merchant names look official, support teams cannot explain the result, and fallback UI has no signal to work with.
Example descriptor:
SQ *JOES COFFEE 0421 TORONTOThis string gives useful evidence: a Square wrapper, a likely merchant phrase, a city, and a possible location or terminal suffix. It does not prove a reviewed legal entity, website, or logo. The response should show the cleaned name and the uncertainty.
Return shape
{
"display_name": "Joe's Coffee",
"category": "Food and Drink",
"confidence": 0.72,
"processor_hint": "square",
"signals": ["processor_square", "merchant_phrase", "location_token"],
"warnings": ["local_merchant_identity_not_verified"]
}The important part is not the exact score. It is the contract: confidence and warnings are first-class output fields. A client can show a clean merchant label while withholding stronger claims such as website, chain identity, or reviewed logo variants until the evidence supports them.
When to use it
Use warning-aware cleanup when a transaction feed powers end-user rows, expense review, categorization, cashback matching, accounting imports, or bank-statement analysis. These screens need readable merchants, but they also need a way to avoid pretending a local cafe, marketplace seller, or processor-wrapped descriptor has been fully resolved.
When not to use it
Do not use descriptor cleanup as proof of legal merchant identity, fraud attribution, sanctions screening, chargeback evidence, or tax classification. Merchant enrichment can improve display and routing. It should not be promoted into compliance evidence without a different verification process.
Privacy caveat
Warnings do not reduce the need for input hygiene. Reject card numbers, account numbers, full statements, customer names, emails, phone numbers, addresses, bank credentials, and customer PII before parsing or logging. TxnKit is designed so the online request path validates one descriptor and does not call LLMs, crawlers, logo providers, or third-party enrichment APIs during POST /v1/enrich.