> ## 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.
# 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**](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction) 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**](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction-with-an-unparsed-de43) endpoint. See an example of a raw DE43 string below:
```json theme={null}
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](https://regex101.com/r/UU2gIo/1).
### 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 [support@spade.com](mailto:support@spade.com).
Below is a generic example of the field mapping to use our [cards/enrich](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction) 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 occasionally 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 |
| **programId** | optional | `p-1234` | Identifier for the program associated with the transaction, used to scope action triggers at the program level. |
| **cardId** | optional | `c-1234` | Unique identifier for the card (do not use actual card numbers). |
| **userId** | required | `u-1234` | Unique user identifier 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 occasionally 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** | optional | `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 |
| **programId** | optional | `p-1234` | Identifier for the program associated with the transaction, used to scope action triggers at the program level. |
| **cardId** | optional | `c-1234` | Unique identifier for the card (do not use actual card numbers). |
| **userId** | required | `u-1234` | Unique user identifier 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](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction). 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](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction-with-an-unparsed-de43). 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** | optional |
| 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](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction). 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](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction). 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](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction). 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](https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction). 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` and `programId`, however none of these fields should include any PII data. Each of these identifiers has a maximum length of 512 characters.
For premium features such as recurrence and category personalization a unique`userId` 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**](https://docs.spade.com/reference/batch-enrichment-guide).
### Example request and response
Below are example requests for both the /enrich and /enrich/parse endpoints:
```json Enrich theme={null}
{
"merchantName": "WMSUPERCENTER#582",
"acquirerId": "123456789",
"userId": "user123",
"cardId": "card123",
"programId": "program123",
"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"
}
```
```json Parse theme={null}
{
"de43": "WMSUPERCENTER#582 PORT ORANGE FL",
"userId": "user_id_123456789",
"programId": "program_id_123",
"amount": "25.23",
"currencyCode": "USD",
"occurredAt": "2025-06-15 18:27:51Z",
"categoryType": "MCC",
"categoryCode": "5812",
"cardId": "card_id_123456789",
"cardFirstSix": "123456",
"cardLastFour": "7890",
"transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
"acquirerId": "123456789",
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
}
```
**Example response:**
```json expandable theme={null}
{
"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"
}
}
```
The example response includes premium data fields for [Risk Insights ](/reference/risk-insights)and [Mobile App Data](/reference/mobile-app-data). If you don’t have access to these features, those fields will not be included in your enrichment response.
If you would like access to any premium features, please reach out to [sales@spade.com](mailto:sales@spade.com).
### Error handling
Typically requests fail due to missing required fields and we will provide details in the error response:
```json theme={null}
{
"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](/reference/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](/reference/improved-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](/reference/mobile-app-data) - detailed information about mobile app and in-app purchases
* [Recurrence](/reference/recurring-transaction-guide) - identify recurring payments
* [Risk Insights](/reference/risk-insights) - merchant-level flags to identify the riskiness of a merchant
To get access to our premium data fields, please reach out to [sales@spade.com](mailto:sales@spade.com).