How to parse processor-wrapped transaction descriptors.

A processor-wrapped descriptor should be split into evidence layers before any merchant claim is made. A processor wrapper is routing context, not merchant identity. Store numbers, cities, service labels, and payment-event tokens can help interpretation, but none should silently become part of the merchant name.

SQ *JOES COFFEE 0421 TORONTO

This descriptor contains at least four possible layers: Square as the processor wrapper, JOES COFFEE as a merchant phrase, 0421 as a possible location or terminal token, and TORONTO as a location hint. The readable phrase is useful evidence. It is not proof that a reviewed merchant record, website, or logo has been found.

Parse evidence before choosing a display name

{
  "raw_description": "SQ *JOES COFFEE 0421 TORONTO",
  "processor_hint": "square",
  "identity_candidate": "JOES COFFEE",
  "location_hint": {"city": "Toronto"},
  "signals": ["processor_square", "merchant_phrase", "numeric_suffix"],
  "confidence_blockers": ["local_merchant_identity_not_verified"]
}

A useful parser preserves the path from raw text to evidence. The matching layer can then compare the identity candidate with reviewed records and aliases. If no reviewed match exists, the response can still return a clean fallback with a warning. That boundary makes the result explainable and keeps parser cleanup separate from entity resolution.

For a broader walkthrough, see the card descriptor cleanup guide. For concrete expected outputs, inspect the public benchmark.

When to use it

Use layered parsing when feeds contain Square, PayPal, Stripe, Shopify, Toast, wallet, marketplace, or other wrapper patterns. It is especially useful when the same merchant can appear with different store numbers or location suffixes and your UI needs a stable fallback label.

When not to use it

Do not treat wrapper removal as verified merchant identification. Do not attach a website, logo, legal entity, fraud attribution, or compliance decision merely because the remaining phrase looks plausible. Parsing extracts evidence; reviewed matching supports stronger claims.

Privacy caveat

Parse one bounded descriptor, not an entire statement. Reject card numbers, account numbers, bank credentials, customer names, emails, phone numbers, addresses, customer PII, and multi-transaction text before parsing or logging. TxnKit's online path does not call an LLM, crawler, logo provider, or third-party enrichment service during POST /v1/enrich.