Card transactions

Bank statement lines are written for card networks, not people: SQ *BLUE BOTTLE COFFE OAKLAND CA, PAYPAL *SPOTIFYAB, AMZN Mktp US*2K4LX9B12. /transaction reads one and tells you who was paid:

Descriptor	Merchant	Website	Processor	Where
`SQ *BLUE BOTTLE COFFE OAKLAND CA`	Blue Bottle Coffee	bluebottlecoffee.com	Square	Oakland, CA
`PAYPAL *SPOTIFYAB`	Spotify	spotify.com	PayPal
`AMZN Mktp US*2K4LX9B12`	Amazon	amazon.com
`CHECKCARD 0412 STARBUCKS STORE 12345 SEATTLE WA`	Starbucks	starbucks.com		Seattle, WA
`VENMO *JOHN SMITH`	A payment to a person		Venmo
`MONTHLY MAINTENANCE FEE`	A bank fee

Cut-off words are completed (card networks truncate descriptors at 22 characters), and processor prefixes and store numbers are dropped. Lines that aren’t purchases say so in kind: person, transfer, fee, atm or refund. The merchant’s name is then resolved to its website the way /resolve does it: the name index first, then a live lookup that checks each candidate against its homepage, using the line’s city to tell local businesses apart. logo_url points at the merchant’s logo on the logo CDN, with your publishable token, ready for an <img> tag. include_brand=true adds the merchant’s full brand (logos, colors, fonts) as /brand returns it.

Example requests

curl -G "https://api.prefetch.io/transaction" \
  --data-urlencode "descriptor=SQ *BLUE BOTTLE COFFE OAKLAND CA" \
  --data-urlencode "country=US" \
  -H "X-API-Key: $PREFETCH_API_KEY"

curl -X POST "https://api.prefetch.io/transaction" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "descriptor": "PAYPAL *SPOTIFYAB", "mcc": "5815", "include_brand": true }'

const lines = ["SQ *BLUE BOTTLE COFFE OAKLAND CA", "NETFLIX.COM 866-579-7172 CA", "VENMO *JOHN SMITH"];

for (const descriptor of lines) {
  const res = await fetch("https://api.prefetch.io/transaction", {
    method: "POST",
    headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ descriptor, country: "US" }),
  });
  const { data } = await res.json();
  const who = data.kind === "merchant" ? `${data.merchant.name} (${data.merchant.domain ?? "no website"})` : data.kind;
  console.log(descriptor, "→", who);
}

import os, requests

lines = ["SQ *BLUE BOTTLE COFFE OAKLAND CA", "NETFLIX.COM 866-579-7172 CA", "VENMO *JOHN SMITH"]

for descriptor in lines:
    r = requests.post(
        "https://api.prefetch.io/transaction",
        headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
        json={"descriptor": descriptor, "country": "US"},
    )
    data = r.json()["data"]
    who = data["merchant"]["name"] if data["kind"] == "merchant" else data["kind"]
    print(descriptor, "→", who)

Example response

{
  "success": true,
  "data": {
    "descriptor": "SQ *BLUE BOTTLE COFFE OAKLAND CA",
    "kind": "merchant",
    "merchant": {
      "name": "Blue Bottle Coffee",
      "domain": "bluebottlecoffee.com",
      "url": "https://bluebottlecoffee.com",
      "confidence": 0.88,
      "source": "live"
    },
    "candidates": [
      { "name": "Blue Bottle Coffee", "domain": "bluebottlecoffee.com", "url": "https://bluebottlecoffee.com", "confidence": 0.88, "source": "live" }
    ],
    "payment_processor": "Square",
    "location": { "city": "Oakland", "region": "CA", "country": "US" },
    "category": "Coffee shop",
    "logo_url": "https://logo.prefetch.io/bluebottlecoffee.com?token=pk_4f1c9e2b7a0d4c3e8b6a1f2d3c4b5a69",
    "parsed_by": "model",
    "warnings": []
  },
  "meta": { "requestId": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "durationMs": 1577 }
}

Reading the response

Field	Meaning
`kind`	`merchant`, or what else the line is. Only a `merchant` has a `merchant` object.
`merchant.name`	The trading name, even when no website was found. Many local businesses have none.
`merchant.domain`	The website, when one was found with a confidence of at least 0.6. At 0.8 or above, treat it as the answer. Below 0.6 it appears only in `candidates`.
`candidates`	Every domain considered, best first, including low-confidence ones.
`logo_url`	`null` when no website was found, or for keys without a logo token (RapidAPI).
`parsed_by`	`rules` when the language model was unavailable and the line was read by pattern alone. That reading is less reliable, and `warnings` says so.

country (where the card was used) and mcc (the merchant category code from your card data) are optional hints that help with ambiguous lines.

Credits

Outcome	Credits
A line read and resolved	3
The same line, country and MCC looked up in the last 7 days	1
`include_brand=true`, and a brand was returned	+10
Failures	0

Statements repeat the same merchants every month, so after the first month most lines cost 1 credit.

Lines whose merchant is already in the name index answer in about a second. Others run a live lookup, which usually takes 2 to 5 seconds.

Build a merchant feed

A recipe for readable transaction rows with logos.

API reference

Every parameter, and a playground to try it.

Get started

Agents and MCP

Company data

Web data

Jobs and monitoring

Platform

Going to production

Example requests

Example response

Reading the response

Credits

Next

Build a merchant feed

API reference

​Example requests

​Example response

​Reading the response

​Credits

​Next

Build a merchant feed

API reference

Example requests

Example response

Reading the response

Credits

Next