Card enrichment guide

Overview

This guide outlines best practices for integrating with our card enrichment endpoints and how to use the enriched data that is returned.

Best practices

Choosing the correct card endpoint

If you receive parsed data from your issuer, or parse the data yourself, you should send data to our /transactions/cards/enrich endpoint. See an example of parsed data below:

MerchantName: WMSUPERCENTER#582
City: PORT ORANGE
Region: FL
Country: US

If you receive raw DE43 data or an unparsed merchant data string from your issuer you should send data to our /transactions/cards/enrich/parse endpoint. See an example of a raw DE43 string below:

DE43: WMSUPERCENTER#582      PORT ORANGE   FL

If you’re unsure if your data follows the DE43 format you can validate it by pasting your string in this regex validator.

Mapping card data to required Spade fields

Below we’ve provided generic examples as well as example fields from common issuers to pass to Spade to enrich transactions.

We are issuer agnostic and can enrich any card data you may have. For assistance please work with your account team or contact [email protected].

Below is a generic example of the fields you field mapping to use our cards/enrich endpoint if you received parsed data from your issuer

Spade fields	Required	Example	Notes
merchantName	required	`WMSUPERCENTER#582`	Send raw merchant name information when possible such as in cases where your issuer cleanses or enriches merchant data
city	required	`PORT ORANGE`	May occassionally include a website or phone number
postalCode	optional	`32127`	Recommended to provide if it is present
region	optional	`FL`	Recommended to provide if it is present
country	required	`USA` or `840`	Supports 3 letter country code or 3 digit country code
acquirerId	optional	`444590000`	May be called merchant ID or acceptor. Typically 8-16 characters
categoryCode	required	`1234`	Required. If you do not receive one on the transaction you can use a fallback of `1111` however this will negatively impact performance
amount	required	`12.34`	Use negative amounts for credit and positive amounts for debits
currencyCode	required	`USD`	Use the currency code that matches to the amount you’re providing
occurredAt	required	`2025-12-01`
transactionId	required	`t-1234`	Unique identifier for the transaction
cardId	optional	`c-1234`	Unique identifier for the card (do not use actual card numbers)
userId	required	`u-1234`	Unique user identifer associated with the transaction

Below is an example field mapping if you received unparsed data from your issuer:

Spade fields	Required	Example	Notes
DE43	required	`WMSUPERCENTER#582 PORT ORANGE FL`	Send raw merchant name information when possible such as in cases where your issuer cleanses or enriches merchant data.
location.city	optional	`PORT ORANGE`	This field may not be available as it is in the DE43 field. May occassionally include a website or phone number
location.postalCode	optional	`32127`	Recommended to provide if present
location.region	optional	`FL`	Recommended to provide if present
location.country	required	`USA` or `840`	Supports 3 letter country code or 3 digit country code
acquirerId	optional	`444590000`	May be called merchant ID or acceptor. Typically 8-16 characters
categoryCode	required	`1234`	Required. If you do not receive one on the transaction you can use a fallback of `1111` however this will negatively impact performance
amount	required	`12.34`	Use negative amounts for credit and positive amounts for debits
currencyCode	required	`USD`	Use the currency code that matches to the amount you’re providing
occurredAt	required	`2025-12-01`
transactionId	required	`t-1234`	Unique identifier for the transaction
cardId	optional	`c-1234`	Unique identifier for the card (do not use actual card numbers)
userId	required	`u-1234`	Unique user identifer associated with the transaction

Below is an example of which merchant-related fields we recommend you use from Marqeta to send to our /cards/enrich endpoint. We’ve omitted the fields for identifiers as you may choose to use your own. For more information on using identifiers see the section below.

Marqeta fields	Spade fields	Required
card_acceptor.name	merchantName	required
card_acceptor.city	location.city	required
card_acceptor.postal_code	location.postalCode	optional
card_acceptor.state	location.region	optional
card_acceptor.country_code	location.country	required
card_acceptor.mid	acquirerId	optional
card_acceptor.mcc	categoryCode	required

Below is an example of which merchant-related fields we recommend you use from Galileo to send to our /cards/enrich/parse endpoint. We’ve omitted the fields for identifiers as you may choose to use your own. For more information on using identifiers see the section below.

Galileo	Spade fields	Required
merchant.merchant_description	DE43	required
merchant.merchant_location	location.city	optional
merchant.merchant_postal_code	location.postalCode	optional
merchant.merchant_state	location.region	optional
merchant.merchant_country	location.country	required
merchant.merchant_number	acquirerId	optional
mcc	categoryCode	required

Below is an example of which merchant-related fields we recommend you use from Stripe to send to our /cards/enrich endpoint. We’ve omitted the fields for identifiers as you may choose to use your own. For more information on using identifiers see the section below.

Stripe Fields	/enrich fields	Required
merchant_data_name	merchantName	required
merchant_data_city	location.city	required
merchant_data_postal_code	location.postalCode	optional
merchant_data_state	location.region	optional
merchant_data_country	location.country	required
merchant_data_network_id	acquirerId	optional
merchant_data_category_code	categoryCode	required

Below is an example of which merchant-related fields we recommend you use from Lithic to send to our /cards/enrich endpoint. We’ve omitted the fields for identifiers as you may choose to use your own. For more information on using identifiers see the section below.

Lithic Fields	/enrich fields	Required
merchant.descriptor	merchantName	required
merchant.city	location.city	required
	location.postalCode	optional
merchant.state	location.region	optional
merchant.country	location.country	required
merchant.acceptor_id	acquirerId	optional
merchant.mcc	categoryCode	required

Below is an example of which merchant-related fields we recommend you use from Adyen to send to our /cards/enrich endpoint. We’ve omitted the fields for identifiers as you may choose to use your own. For more information on using identifiers see the section below.

Adyen Fields	/enrich fields	Required
merchantData.nameLocation.name	merchantName	required
merchantData.nameLocation.city	location.city	required
merchantData.postalCode	location.postalCode	optional
	location.region	optional
merchantData.nameLocation.country	location.country	required
merchantData.merchantId	acquirerId	optional
merchantData.mcc	categoryCode	required

Below is an example of which merchant-related fields we recommend you use from Fiserv to send to our /cards/enrich endpoint. We’ve omitted the fields for identifiers as you may choose to use your own. For more information on using identifiers see the section below.

Fiserv Fields	/enrich fields	Required
merchantName	merchantName	required
merchantCity	location.city	required
merchantZipCode	location.postalCode	optional
merchantStateProvince	location.region	optional
merchantCountryCode	location.country	required
merchantNumber	acquirerId	optional
merchantCategoryCode	categoryCode	required

It is common to receive a phone number or website in the city field. In these instances, you should still pass that data to Spade as we account for that when enriching transactions.

Using identifiers

We recommend providing a transactionId so that you can map our enrichment response and corresponding enrichmentId to your transaction-level data store. Additional metadata about the transaction or user can be provided in the customAttributes object and the enrichment response will return the original values provided. We require a userId for all enrichment endpoints and you can optionally provide a cardId , however neither of these fields should include any PII data.

For premium features such as recurrence and category personalization a uniqueuserId is required. If you don’t have the concept of a user on your platform you can use any identifier that groups transactions made by the same individual or organization.

Calling Spade in the authorization flow

We recommend calling Spade in the authorization flow which can improve match rates and to use the enriched data for authorization decisioning.

Batch vs real-time

Real time enrichment: send single transactions and received enhanced data with a p99 of under 50ms. Using real time enrichment is recommend for most use cases, especially those with low latency requirements or data models that receive transactions in single events.
Batch enrichment: send batches of up to 50,000 transactions at once for mass enrichment. Results can be retrieved through webhooks or endpoint polling. These endpoints are best for use cases with no latency requirements such as sending historical card data. Learn more about batch enrichment here.

Example request and response

Below are example requests for both the /enrich and /enrich/parse endpoints:

{
  "merchantName": "WMSUPERCENTER#582",
  "acquirerId": "123456789",
  "userId": "user123",
  "cardId": "card123",
  "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
  "amount": "42.00",
  "currencyCode": "USD",
  "location": {
    "city": "PORT ORANGE",
    "region": "FLORIDA",
    "country": "US"
  },
  "occurredAt": "2025-06-05T1:42:00Z",
  "categoryCode": "5469",
  "categoryType": "MCC"
}

Example response:

{
  "transactionInfo": {
    "type": "spending",
    "subType": null,
    "display": {
      "name": "Walmart",
      "categoryName": "Department Stores",
      "graphic": "https://static.v2.spadeapi.com/logos/d730906bf1a849f19939f27390170a6d/light.png",
      "graphicSource": "counterparty"
    },
    "thirdParties": [],
    "spendingInfo": {
      "channel": {
        "value": "physical"
      }
    },
    "transferInfo": null,
    "atmInfo": null,
    "isAccountVerification": null,
    "isPeerToPeer": null,
    "isDigitalWallet": null,
    "transactionId": "transaction_id_123456789",
    "recurrenceInfo": null,
    "riskInsights": {
      "irregularWebPresenceDetected": null,
      "negativeOnlineSentiment": null,
      "highRiskEntity": null,
      "riskyIndustry": false,
      "cardAcceptanceHistory": "extensive"
    }
  },
  "counterparty": [
    {
      "id": "d730906b-f1a8-49f1-9939-f27390170a6d",
      "name": "Walmart",
      "legalName": "Walmart Inc.",
      "industry": [
        {
          "id": "011-000-000-000",
          "name": "Retail",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        },
        {
          "id": "011-018-000-000",
          "name": "General Goods",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        },
        {
          "id": "011-018-002-000",
          "name": "Department Stores",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        }
      ],
      "location": [
        {
          "id": "380e18b7-bf9e-3545-b27e-80e36301c540",
          "address": "1590 Dunlawton Ave",
          "addressLine1": "1590 Dunlawton Ave",
          "addressLine2": null,
          "city": "Port Orange",
          "region": "FL",
          "postalCode": "32127",
          "country": "USA",
          "phoneNumber": "+13867562711",
          "latitude": 29.116727,
          "longitude": -81.019428,
          "matchScore": 77.43
        }
      ],
      "matchScore": 72.15,
      "logo": "https://static.v2.spadeapi.com/logos/d730906bf1a849f19939f27390170a6d/light.png",
      "medianSpendPerTransaction": null,
      "phoneNumber": "+14792734000",
      "website": "https://www.walmart.com/"
    }
  ],
  "enrichmentId": "050d3a73-c212-4f89-b9c0-0e75da0efeea",
  "mobileAppInfo": null,
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  }
}

Error handling

Typically requests fail due to missing required fields and we will provide details in the error response:

{
  "city": [
    "This field is required."
  ]
}

If you receive an error for a missing field, you should not attempt to retry the transaction without that field as it will fail again.

Using enriched card data

Counterparty, third party, and location info

We will always return a clean counterparty name in the enriched response, and if we match to a verified merchant in our database we will return a counterparty.id as well as details about the counterparty such as their logo and website. Additionally, if we match to a location associated with that counterparty we will return a location.id with address and geolocation information. If a third party is identified we will return a thirdParty.id as well as the third party name and type.

For more information on matching about Spade see our guide on understanding enriched data.

Spade industries

We always return an industry or category when enriching transactions. We can return up to four levels of industries (or categories) in the counterparty.industry array with the most granular industry returned as the last object in the array as well as in the display.categoryName.This level of granularity provides you the opportunity to more permissive or restrictive with category-level card controls or rewards. Below is an example of the industries that would be returned for an in-flight internet purchase.

Industry Name	Industry ID
Travel	014-000-000-000
Transportation	014-003-000-000
Airlines and Aviation	014-003-002-000
Inflight Internet and Entertainment	014-003-002-001

For example, if you want to issue a virtual card that could be used to only book an airline ticket you could choose to only authorize transactions with the Airlines and Aviation industry 014-003-002-000. But if you wanted to issue a card that could be used for any transportation related expense you could authorize any industry that falls below it by allowing any industry that starts with 014-003-*.

Display object

We provide everything need to make transactions easily identifiable to end users in our enriched response. The display object contains our recommendation for the name, logo and category name to use in your UI/UX based on the parties identified in the transaction.

For more information, see our guide on improving UI/UX with Spade.

Premium data fields

We offer additional premium data fields that are returned if enabled. These premium data fields include:

Mobile App Data - detailed information about mobile app and in-app purchases
Recurrence - identify recurring payments
Risk Insights - merchant-level flags to identify the riskiness of a merchant

To get access to our premium data fields, please reach out to [email protected].

Welcome

Enrichment Guides

Tooling Guides

More

Overview

Best practices

Choosing the correct card endpoint

Mapping card data to required Spade fields

Using identifiers

Calling Spade in the authorization flow

Batch vs real-time

Example request and response

Error handling

Using enriched card data

Counterparty, third party, and location info

Spade industries

Display object

Premium data fields

Welcome

Enrichment Guides

Tooling Guides

More

​Overview

​Best practices

​Choosing the correct card endpoint

​Mapping card data to required Spade fields

​Using identifiers

​Calling Spade in the authorization flow

​Batch vs real-time

​Example request and response

​Error handling

​Using enriched card data

​Counterparty, third party, and location info

​Spade industries

​Display object

​Premium data fields

Overview

Best practices

Choosing the correct card endpoint

Mapping card data to required Spade fields

Using identifiers

Calling Spade in the authorization flow

Batch vs real-time

Example request and response

Error handling

Using enriched card data

Counterparty, third party, and location info

Spade industries

Display object

Premium data fields