> For the complete documentation index, see [llms.txt](https://docs.powens.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.powens.com/api-reference/products/data-aggregation/merchant-tagger.md).

# Merchant Tagger

Retrieve the company behind a transaction wording, and the payment intermediary when the wording names one.

The Merchant Tagger feature identifies the company behind the wording of a bank transaction.

> **This feature is not activated by default on your domain. Please contact us to request access.**

Upon activation, the properties `id_merchant`, `id_intermediary`, `merchant` and `intermediary` are available on Bank transactions through the `merchant_tagger` expand, and in the `ACCOUNT_MERCHANT_TAGGED` webhook.

For an overview of the feature, what it is used for and how to integrate it, see the [Merchant Tagger guide](https://docs.powens.com/documentation/integration-guides/transactions/merchant-tagger).

Raw transaction wordings are written for banking systems, not for people: they carry truncated names, terminal codes, city names and internal references. Merchant Tagger reads that wording and resolves it to a known company.

| Original wording                                  | Merchant | Intermediary |
| ------------------------------------------------- | -------- | ------------ |
| `PAIEMENT CB LIDL ARCONNAY`                       | Lidl     | —            |
| `CARTE 01/07/25 Google Play Apps CB*7733`         | Google   | —            |
| `Glovo 01OCT ZNTFS89GMQ\BARCELONA\ ES`            | Glovo    | —            |
| `PAIEMENT CB 2809 PARIS KLARNA* SHEIN CARTE 2234` | —        | Klarna       |
| `Payment to PayPal Inc.`                          | —        | PayPal       |

Two kinds of entity are detected, and a transaction can carry one, both or neither:

* **Merchant** — the business the money was actually spent with: Amazon, Carrefour, McDonald's, Spotify.
* **Intermediary** — the payment facilitator that appears in the wording: PayPal, Klarna, Alma, Scalapay, SumUp, Apple Pay.

The distinction matters: a payment made through PayPal to an online shop is a different commercial signal from a direct payment to that shop.

Detection is based on what the bank wrote in the transaction wording and on the amount of the transaction. Nothing about the account holder is involved, and no data leaves the Powens platform.

## List bank transactions with their merchant

**GET** `https://{domain}.biapi.pro/2.0/users/{userId}/transactions?expand=merchant_tagger`

List bank transactions with their associated merchant data. Merchant properties are **not returned by default**: the `merchant_tagger` expand has to be requested explicitly.

### Using the expand

The expand is accepted on every transactions endpoint:

```
GET /users/{userId}/transactions?expand=merchant_tagger
GET /users/{userId}/accounts/{accountId}/transactions?expand=merchant_tagger
GET /users/{userId}/connections/{connectionId}/transactions?expand=merchant_tagger
```

Several expands are combined with a comma, so merchant and category data can be retrieved in the same call:

```
GET /users/me/transactions?expand=merchant_tagger,categories
```

The expand combines with the usual query parameters of the endpoint:

```
GET /users/me/transactions?expand=merchant_tagger&limit=100&min_date=2026-01-01
```

See [Response expansion](https://docs.powens.com/api-reference/overview/api-design#responses-expansion) for the general mechanism.

Two things are worth knowing when the response does not look the way you expect:

* If `id_merchant` is **missing from the response entirely**, the expand did not reach the API — check the query string.
* If `id_merchant` is present but `null`, the expand worked and that transaction simply carries no merchant. See the limitations below.

### Response

Each transaction object gains four properties.

| Property          | Type             | Description                                                                                                       |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id_merchant`     | Integer or null  | ID of the detected merchant. `null` when no merchant was detected.                                                |
| `id_intermediary` | Integer or null  | ID of the detected intermediary. `null` when no intermediary was detected.                                        |
| `merchant`        | *Company* object | The detected merchant. Absent when `id_merchant` is `null`, and occasionally when the company cannot be resolved. |
| `intermediary`    | *Company* object | The detected intermediary. Absent when `id_intermediary` is `null`, under the same conditions.                    |

```json
{
  "transactions": [
    {
      "id": 4815162342,
      "id_account": 12345,
      "date": "2025-09-30",
      "value": -3.10,
      "wording": "Mcdonalds 449",
      "original_wording": "Mcdonalds 449",
      "id_merchant": 510,
      "id_intermediary": null,
      "merchant": {
        "id": 510,
        "name": "MCDONALD’S",
        "type": "merchant",
        "tickers": ["MCD"],
        "website_url": "https://www.mcdonalds.com",
        "logo_url": null,
        "icon_url": "https://assets.powens.com/mt/icons/510.svg"
      }
    },
    {
      "id": 4815162343,
      "id_account": 12345,
      "date": "2025-09-28",
      "value": -13.36,
      "wording": "PAIEMENT CB 2809 PARIS KLARNA* SHEIN CARTE 2234",
      "original_wording": "PAIEMENT CB 2809 PARIS KLARNA* SHEIN CARTE 2234",
      "id_merchant": null,
      "id_intermediary": 413,
      "intermediary": {
        "id": 413,
        "name": "KLARNA",
        "type": "intermediary",
        "tickers": ["KLAR"],
        "website_url": "https://www.klarna.com",
        "logo_url": null,
        "icon_url": "https://assets.powens.com/mt/icons/413.svg"
      }
    }
  ],
  "total": 2
}
```

The IDs and the nested objects come from different places: `id_merchant` and `id_intermediary` are stored on the transaction, while `merchant` and `intermediary` are resolved from the company catalogue when the response is built. If that resolution does not succeed, the IDs are still returned and the nested object is omitted.

**Read the ID as the reliable property and the nested object as optional.** An integration that reaches straight for `merchant.name` whenever `id_merchant` is set will break on that case; check that the object is present first.

## When tagging happens

Transactions are tagged **asynchronously, after each account synchronization**. Enabling the feature does not slow down connection creation or synchronization, and a transaction read immediately after `CONNECTION_SYNCED` may not be tagged yet.

Only transactions scraped since the previous successful synchronization are tagged; on the first synchronization of an account, all of its transactions are. Transactions already stored when the feature was activated on your domain are **not** tagged retroactively.

Use the `ACCOUNT_MERCHANT_TAGGED` webhook to know when the results of a synchronization are available, rather than polling the transactions endpoint. The webhook carries the transactions with their merchant data already expanded, so no follow-up call is needed.

## Data model

### *Company* object

| Property      | Type                         | Description                                                                                                        |
| ------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`          | Integer                      | Stable ID of the company. IDs are never reused.                                                                    |
| `name`        | String                       | Display name of the company, in its usual spelling.                                                                |
| `type`        | `merchant` or `intermediary` | Nature of the company.                                                                                             |
| `tickers`     | Array of strings, or null    | Stock tickers of the listed company or its parent group, when applicable. `null` for a company that is not listed. |
| `website_url` | String or null               | Official website of the company.                                                                                   |
| `logo_url`    | String or null               | Logo of the company, hosted by Powens. `null` when the company has no logo.                                        |
| `icon_url`    | String or null               | Square icon of the company, hosted by Powens. `null` when the company has no icon.                                 |

## Coverage

The catalogue is centred on the French and Spanish markets and covers the retail, food, transport, telecommunications, banking, insurance, energy, e-commerce and subscription sectors. Merchants make up the large majority of it; intermediaries are a short list of payment facilitators.

The catalogue grows over time. Company IDs are stable and are never reused, so they can safely be stored and relied on across releases. New companies are added at the end of the catalogue; an ID you have never seen before simply means the catalogue was extended.

Listed companies carry their stock tickers, which lets you group a transaction under its parent group.

If a brand your use case depends on is not recognised, contact us: adding a merchant is a routine operation.

## Notes and limitations

* **Tagging is asynchronous.** Drive your integration from the `ACCOUNT_MERCHANT_TAGGED` webhook rather than polling.
* **No retroactive tagging.** Activation tags transactions from that point forward. Existing transactions are not revisited, and neither are transactions that were tagged before a company was added to the catalogue.
* **Precision over coverage.** The engine is tuned to avoid naming the wrong merchant, so it leaves a wording untagged when the evidence is thin. Expect a significant share of `null` results, particularly on transfers, cash withdrawals, internal bank operations and fees.
* **One merchant and one intermediary per transaction.** The response carries at most one of each; a wording naming several brands resolves to the strongest match.
* **Visual assets are not available for every company.** `icon_url` and `logo_url` are `null` for a company with no asset, and the coverage of both grows over time. Always provide a fallback rather than assuming an icon is there.
* **The nested objects are best-effort.** `id_merchant` and `id_intermediary` are authoritative; `merchant` and `intermediary` can be missing even when the ID is set.
* **There is no endpoint to list the catalogue.** Companies are discovered through the transactions they appear on. If you need the full list — to build a local mapping, for instance — ask us for it.
* **Wordings are never modified.** Merchant Tagger only adds properties. `wording` and `original_wording` are returned exactly as the bank provided them.
