Skip to main content

​
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.
Merchant-locked cards require the action triggers feature. Contact your Spade representative if you need access.

​
How it works

Merchant-locked card flow: search, select, register, receive recommendation
  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. 
{
  "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"
    },
    ...
  ]
}
Autocomplete UI powered by GET /corporations

​
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. 
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 Realtime 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.

Matched merchant — ALLOW

Transaction at a locked merchant (e.g., OpenAI):
{
  "actions": [
    {
      "id": "trigger-1",
      "type": "ALLOW_ONLY",
      "action": {
        "type": "ALLOW_ONLY",
        "authRecommendation": "ALLOW"
      },
      "scope": "card"
    }
  ]
}

Unmatched merchant — BLOCK

Transaction at any other merchant (e.g., Gemini):
{
  "actions": [
    {
      "id": "trigger-1",
      "type": "ALLOW_ONLY",
      "action": {
        "type": "ALLOW_ONLY",
        "authRecommendation": "BLOCK"
      },
      "scope": "card"
    }
  ]
}
Spade returns a recommendation, not an enforcement decision. Your system is responsible for approving or declining the transaction based on the authRecommendation value.

​
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