Show merchant logos in a transaction feed

Use case prompt

Build a transaction feed with merchant logos, following https://www.logo.dev/docs/use-cases/transaction-logos.md

Read that page and inspect this project's stack. Use this project's existing conventions.

Each row shows the merchant logo, a readable name, the date, and the amount, and keeps the original statement descriptor. If a transaction has a merchant domain, use it for the logo. If it has only a raw descriptor, resolve it on the server first. The Logo.dev Transaction endpoint is a private beta, so access can be off for the account. When it rejects the request, show the raw descriptor and do not retry. Store user corrections separately, and apply them before any lookup result.

For API details, read https://www.logo.dev/docs/logo-images/introduction.md and https://www.logo.dev/docs/transaction/introduction.md

A raw statement line like AMZN MKTP US*XX1234 means nothing to the person who reads it. A merchant logo and a clean name make every row recognizable. Your app keeps the original descriptor and any correction the user makes.

Choose the lookup from the data you have

A merchant domain: many card processors and open-banking providers return one. Use it with the Logo.dev CDN.
Only the raw descriptor: resolve it on your server with Transaction. It is a private beta, and it returns 403 until the beta is on for your account.
A clean merchant name: use a name lookup.

This server module picks the lookup for one transaction:

merchant-lookup.ts

type Transaction = {
  id: string;
  rawDescriptor: string;
  merchantName?: string;
  merchantDomain?: string;
  countryCode?: string;
};

export type Merchant = {
  status: "matched" | "cleaned" | "invalid" | "unavailable" | "error";
  name: string;
  domain: string | null;
};

export async function lookupMerchant(tx: Transaction): Promise<Merchant> {
  const domain = tx.merchantDomain?.trim().toLowerCase();
  if (domain) {
    // Use the processor's merchant name when it sends one.
    return { status: "matched", name: tx.merchantName ?? tx.rawDescriptor, domain };
  }

  const res = await fetch("https://www.logo.dev/api/transaction", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LOGO_DEV_TRANSACTION_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      transaction: tx.rawDescriptor,
      country_code: tx.countryCode,
    }),
  });
  if (res.status === 400) {
    // The input is wrong, such as an unsupported country code or an empty
    // descriptor. Retry after you correct the transaction.
    // https://www.logo.dev/docs/transaction/introduction#handle-errors
    return { status: "invalid", name: tx.rawDescriptor, domain: null };
  }
  if (res.status === 401 || res.status === 403) {
    // A bad key, or no beta access (403). Retrying gives the same answer.
    return { status: "unavailable", name: tx.rawDescriptor, domain: null };
  }
  if (!res.ok) {
    // Keep the raw descriptor on screen and retry later.
    return { status: "error", name: tx.rawDescriptor, domain: null };
  }

  const body: { status: "matched" | "cleaned"; name: string; domain: string | null } =
    await res.json();
  return { status: body.status, name: body.name, domain: body.domain };
}

Handle every row state

Store the lookup result with the transaction. Render each row from this table:

Result	Save	Show
`matched`	Name, domain, lookup time	The logo and the name
`cleaned`	Cleaned name	The name with a neutral placeholder. Don’t guess a logo.
`invalid`	The attempt time	The raw descriptor. Retry after you correct the transaction data.
`unavailable`	The attempt time	The raw descriptor. Do not retry until you fix the key or the beta is on.
Request failed	The attempt time	The raw descriptor. Retry later with backoff.
User correction	Name and domain, in a separate table	The correction, before any lookup result

Render the feed

A row with a domain shows the logo. A row without one shows a neutral placeholder:

type Row = {
  id: string;
  name: string;
  domain: string | null;
  date: string;
  amount: number; // negative for charges, positive for credits
};

const usd = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});

export function TransactionFeed({
  token,
  rows,
}: {
  token: string;
  rows: Row[];
}) {
  return (
    <ul className="max-w-md divide-y divide-zinc-950/5 dark:divide-white/5">
      {rows.map((row) => (
        <li className="flex items-center gap-3 py-3" key={row.id}>
          {row.domain ? (
            <img
              alt={`${row.name} logo`}
              className="h-10 w-10 rounded-full object-contain"
              height={40}
              loading="lazy"
              src={`https://img.logo.dev/${row.domain}?token=${token}&format=webp&retina=true&size=40`}
              width={40}
            />
          ) : (
            <div aria-hidden className="h-10 w-10 rounded-full bg-zinc-100 dark:bg-zinc-800" />
          )}
          <div className="min-w-0">
            <div className="truncate text-sm font-medium">{row.name}</div>
            <div className="text-xs text-zinc-500">{row.date}</div>
          </div>
          <div
            className={`ml-auto text-sm font-medium tabular-nums ${
              row.amount > 0 ? "text-emerald-600" : ""
            }`}
          >
            {row.amount > 0 ? "+" : ""}
            {usd.format(row.amount)}
          </div>
        </li>
      ))}
    </ul>
  );
}

import { TransactionFeed } from "./TransactionFeed";

export function RecentActivity() {
  return (
    <TransactionFeed
      rows={[
        { id: "t1", name: "Starbucks", domain: "starbucks.com", date: "Today", amount: -6.4 },
        { id: "t2", name: "Uber", domain: "uber.com", date: "Today", amount: -23.1 },
        { id: "t3", name: "Helga Lefse Hut", domain: null, date: "Jun 8", amount: -12.5 },
      ]}
      token="LOGO_DEV_PUBLISHABLE_KEY"
    />
  );
}

Show the original descriptor in the transaction details. Keep the amount, currency, and date from your ledger. A lookup result never replaces them.

Test the feed

Test with four rows: a merchant with a known domain, a raw descriptor that Transaction matches, a descriptor that comes back cleaned, and a row the user corrected. Then make one lookup fail, and send one with an account that does not have the beta. The corrected row and the original descriptor must not change, and the 403 must not retry.

Transaction

Identify merchants from raw card descriptors.

Stock watchlists

Build the same row pattern for trading and portfolio apps.

Start simple

Fintech

CRM and sales

Marketing and onboarding

Marketplaces

Branded content

Show merchant logos in a transaction feed

Choose the lookup from the data you have

Handle every row state

Render the feed

Test the feed

Transaction

Stock watchlists

​Choose the lookup from the data you have

​Handle every row state

​Render the feed

​Test the feed

Transaction

Stock watchlists

Choose the lookup from the data you have

Handle every row state

Render the feed

Test the feed