Skip to content
DescriptorAPI
Get API key

Building with transaction data

Transaction enrichment: from a raw line to a merchant

What enrichment returns, what it cannot know from one line, and how to judge an answer. Written for teams putting merchant names and logos in front of customers.

Written for: Developers 4 min read Updated

Transaction enrichment turns a raw statement line into something a person recognises: a merchant name, a logo, a category, a location. It is the difference between "SQ *BLUE BOTTLE COF SAN FRANCISCO CA" and "Blue Bottle Coffee, coffee shops, San Francisco". This guide is for teams putting that in front of customers: what enrichment can and cannot know, and how to judge an answer.

What an enrichment result contains

A useful result separates the line into the facts it actually carries, and adds what can be looked up from them:

  • The merchant: the brand a customer would recognise, its website, logo and category.
  • The location: city and country, when the line or the context gives them.
  • The payment provider: Square, PayPal, a marketplace or a pay-later service, kept separate from the merchant.
  • What kind of line it is: a purchase, a refund, a transfer, a bank fee or a declined payment. Not every line is a purchase; see why that matters.
  • How sure it is: a confidence, and whether a person has verified the merchant.

POS 9921 CAREEM HALA RIDE DUBAI AE

CAREEM
Merchant: Careem, transportation, ride hailing, with its website and logo.
HALA RIDE
A product name, kept out of the merchant name.
DUBAI AE
Location: Dubai, United Arab Emirates.
What enrichment adds is not in the line: the logo, the category and the website come from knowing who Careem is.

What one line cannot tell you

Be wary of anyone who promises perfect answers. A descriptor is short, lossy text, and some information is simply not there:

  • What was bought. A supermarket line does not say whether it was food or a phone.
  • The seller behind a marketplace, when the marketplace does not print it.
  • Which bill a payment network paid, when only the network's name is on the line.
  • Very short names. Four letters and a country code can belong to many businesses.

The honest response to these is "unknown" or a low confidence, not a confident guess. A wrong logo next to a customer's transaction does more damage to trust than a plain descriptor.

Context improves the answer

The same short name can be a different business in a different country. Send what you know alongside the line:

  • The card or account country, so a name is read in the right market.
  • The transaction currency, which says where the card was used: a dirham payment was almost certainly made in the Emirates, even on a card issued elsewhere.
  • The MCC, which helps with short or shared names (see MCCs).

Send the line exactly as you received it. Cleaning it yourself (removing numbers, cutting prefixes) usually throws away the parts that identify the provider or the place.

How to judge an enrichment provider

Test on your own data, not a demo set. Take a few hundred real lines from your customers, in the regions you serve, and look at:

  1. Coverage in your markets. A provider strong in the US can be weak in the Gulf or North Africa, where processors, transliteration and local chains differ.
  2. Precision when it answers. Of the merchants it returns, how many are right? This matters more than how many it answers.
  3. Calibration. Are its high-confidence answers really more often right than its low-confidence ones? If not, the confidence is decoration.
  4. How it handles non-purchases. Transfers with personal names, refunds and bank fees should never come back as a merchant.
  5. Privacy. What it stores, for how long, and what it does with personal names in transfer lines.
  6. Cost per useful answer. Pricing per request punishes you for lines nobody can identify. Prefer pricing per found merchant.

Field note

The test that tells you most about a provider is not the famous brands, which everyone gets right. It is a hundred lines from small local businesses in your market. That is where coverage, honesty about uncertainty and regional knowledge show up, and where the difference between providers is largest.

Showing results to customers

  • Show the merchant with its logo when confidence is high and it is verified.
  • Below that, show the merchant with less emphasis and keep the original line visible.
  • With no merchant, show the cleaned line, not a guess.
  • Let customers correct a merchant or category, and remember it for them.

The confidence guide suggests thresholds to start from.

Try it

Paste a few of your own lines into the playground, or get a free API key and run a batch of up to 100 in one call with the batch endpoint. You are billed only for lines where we find a merchant.

Read next