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

# Merchant-locked cards

> Use Spade to lock cards to specific merchants

## Overview

Merchant-locked cards restrict spending to a predefined set of merchants — useful for corporate expense cards, benefits/stipend cards, and fleet cards. Spade handles the hard part: identifying which merchant a transaction belongs to and returning an allow or block recommendation in real time. Your system registers the allowed merchants with Spade, and Spade tells you whether each incoming transaction should be approved or denied.

<Info>
  Merchant-locked cards require the action triggers feature. Contact your Spade
  representative if you need access.
</Info>

## How it works

<img src="https://mintcdn.com/spade-90e401c6/eYmAPrj1Ylf6-9cS/images/reference/merchant_locked_card_flow.png?fit=max&auto=format&n=eYmAPrj1Ylf6-9cS&q=85&s=2f85acb0d6f84d40c499156f81650a00" alt="Merchant-locked card flow: search, select, register, receive recommendation" width="1536" height="442" data-path="images/reference/merchant_locked_card_flow.png" />

1. **Search** — Query Spade's merchant database for autocomplete results
2. **Select** — The user picks one or more merchants
3. **Register** — Send selected merchants to Spade as `ALLOW_ONLY` action triggers
4. **Receive** — Spade returns an `authRecommendation` with each enrichment

## Step 1: Search Spade's merchant database

Use `GET /corporations` to power a merchant autocomplete widget. The endpoint returns the merchant `name`, `logo`, and `website` for each match.

```json theme={null}
{
  "corporations": [
    {
      "name": "OpenAI",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "openai.com"
    },
    {
      "name": "OpenTable",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "opentable.com"
    },
    ...
  ]
}
```

<img src="https://mintcdn.com/spade-90e401c6/eYmAPrj1Ylf6-9cS/images/reference/merchant_search_mobile_screenshot.png?fit=max&auto=format&n=eYmAPrj1Ylf6-9cS&q=85&s=96213ef6bceddc63b685a6657b4bc750" alt="Autocomplete UI powered by GET /corporations" style={{ maxWidth: "500px", display: "block", margin: "0 auto" }} width="1024" height="1536" data-path="images/reference/merchant_search_mobile_screenshot.png" />

## Step 2: Select merchants

The user or admin selects one or more merchants from the search results. The `name` and `website` from Step 1 are all you need for the next step.

## Step 3: Register allowed merchants

Send the selected merchants to Spade using the card-scoped action triggers endpoint. Set each merchant's action type to `ALLOW_ONLY` so that only transactions at these merchants are recommended for approval.

```json theme={null}
PUT /users/{userId}/cards/{cardId}/merchant-action-triggers

{
  "merchantTriggers": [
    {
      "id": "trigger-1",
      "merchantName": "OpenAI",
      "website": "https://www.openai.com",
      "action": {
        "type": "ALLOW_ONLY"
      }
    },
    {
      "id": "trigger-2",
      "merchantName": "Anthropic",
      "website": "https://www.anthropic.com",
      "action": {
        "type": "ALLOW_ONLY"
      }
    }
  ]
}
```

For full integration details — including registration scopes, status polling, and batch processing — see the [Merchant action triggers guide](/reference/merchant-action-triggers-guide).

## Step 4: Receive auth recommendations

When a transaction is enriched, Spade checks it against the registered triggers and returns an `authRecommendation` inside the `action` object.

<Columns cols={2}>
  <Card title="Matched merchant — ALLOW">
    Transaction at a locked merchant (e.g., OpenAI):

    ```json theme={null}
    {
      "actions": [
        {
          "id": "trigger-1",
          "type": "ALLOW_ONLY",
          "action": {
            "type": "ALLOW_ONLY",
            "authRecommendation": "ALLOW"
          },
          "scope": "card"
        }
      ]
    }
    ```
  </Card>

  <Card title="Unmatched merchant — BLOCK">
    Transaction at any other merchant (e.g., Gemini):

    ```json theme={null}
    {
      "actions": [
        {
          "id": "trigger-1",
          "type": "ALLOW_ONLY",
          "action": {
            "type": "ALLOW_ONLY",
            "authRecommendation": "BLOCK"
          },
          "scope": "card"
        }
      ]
    }
    ```
  </Card>
</Columns>

<Note>
  Spade returns a **recommendation**, not an enforcement decision. Your system
  is responsible for approving or declining the transaction based on the
  `authRecommendation` value.
</Note>

## Use cases

* **Corporate expense cards** — Lock cards to approved vendors so employees can only spend at authorized merchants
* **Benefits and stipend cards** — Restrict wellness, meal, or commuter cards to relevant merchants
* **Fleet cards** — Limit fuel cards to gas stations and approved service providers