> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prefetch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Card transactions

> Turn a card transaction descriptor into the merchant behind it: name, website, logo, processor and location. 3 credits, 1 for a line seen in the last week.

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`](https://docs.prefetch.io/company-data/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](https://docs.prefetch.io/company-data/logo-cdn.md), with your publishable token, ready for an `<img>` tag. `include_brand=true` adds the merchant's full brand (logos, colors, fonts) as [`/brand`](https://docs.prefetch.io/company-data/brand) returns it.

## Example requests

```bash cURL theme={"theme":"css-variables"}
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"
```

```bash POST, with the brand theme={"theme":"css-variables"}
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 }'
```

```javascript Node.js theme={"theme":"css-variables"}
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);
}
```

```python Python theme={"theme":"css-variables"}
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

```json theme={"theme":"css-variables"}
{
  "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.

> [!NOTE]
>
> 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.

## Next

> [card] [Build a merchant feed](https://docs.prefetch.io/recipes/merchant-feed.md)
>
> A recipe for readable transaction rows with logos.

> [card] [API reference](https://docs.prefetch.io/api-reference/endpoint/transaction.md)
>
> Every parameter, and a playground to try it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.