The following outlines the major concepts you will encounter while integrating with the Spade Card Transaction Enrichment API. Our goal is to enrich your transactions with high quality data, providing as much insight and clarity as possible.
We do this through a data-driven approach to transaction enrichment. When you send us a transaction, we work to match it with a merchant in our database covering 99.9% of all places you can swipe or type a card in the US. Once we match, we return granular merchant, category, and geolocation information. If we are not able to match, we will clean and return the information provided in the original transaction (e.g., merchant name, city/state, category).
Counterparty
A counterparty is the entity that you interact with directly when you make a purchase (in most cases, a merchant). In our API, counterparty is represented as a list, typically this list will contain a single matched counterparty, however in a small percentage of cases, multiple results may be returned if there is a lower degree of certainty.
For large merchants, a counterparty can be thought of as a brand, e.g. all Starbucks locations fall under the same counterparty regardless of which location you purchase from.
Accompanying a matched counterparty is a match_score which represents how strongly correlated the returned counterparty with the transaction (see Match Score section for more details).
Additionally, regardless of the counterparty results, we may also return third parties (see below).
Counterparty ID
Every time we match on a counterparty, we return a counterparty ID. The counterparty ID is consistent between transactions regardless of the location. During implementation, we recommend building rules and/or mappings using counterparty ID, not merchant name.
When we do not return a counterparty ID, this indicates we did not find a counterparty match in our database. However, we still return cleaned information derived from the original request, and we may also have matched on a third party (see below).
Location
Spade also includes precise geographic information underneath our counterparty objects, down to the latitude and longitude. When matched to our backing data a location object will include a locationId, which is a unique id for that specific location. e.g. each Starbucks shop will have a different locationId.
As with counterparties, we return a list of possible locations. This list can currently contain up to one location.
Industry
This field represents the primary industry that a given counterparty does business in (not the particular transaction). Our custom industry classification system is built as a tree where tree nodes are sub-industries of their parents – the deeper into the tree you go, the more specific the industry is.
For instance, Walmart's industry is:
[
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-018-000-000",
"name": "General Goods",
"icon": "/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-018-002-000",
"name": "Department Stores",
"icon": "/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
}
]
In this example, Retail is the most general industry. Moving down the tree, we see that General Goods is the sub-industry of Retail to which Walmart belongs (notice that it is more specific). Other sub-industries of Retail include Gas Stations, Pharmacies, and Office Supplies.
Moving down the tree further, we see that Department Stores is the sub-industry of General Goods to which Walmart belongs (notice that this is yet more specific). Other sub-industries of General Goods include Discount Stores, Flea Markets, and Pawn Shops.
To obtain a full list of industries, please reach out to [email protected].
Website & Phone Number
In addition to location data, certain merchants have their website and phone number available. This data is either returned from our database, or extracted automatically from raw transactions in the merchantName or city fields.
Match Score
When we connect your transaction with one of the millions of merchants in our database, we also return a score between 0 and 100 called the match score. This score indicates how strongly correlated the matched counterparty is to the transaction. The match score is not probabilistic.
A null match score indicates we did not find a match in our database.
To learn more about match scores and how to interpret them, please read understanding match scores.
Third Parties
A third party is any entity besides the counterparty involved in a transaction, but not the direct recipient of the payment (buy-now-pay-later providers, delivery services, marketplaces, payment processors, POS systems, etc). Multiple third parties can be involved with a single transaction. When a third party is involved in a transaction, we will return that information in the thirdParties field. We will also attempt to match on a counterparty – however, different third parties provide varying levels of information on counterparties in their transactions. When we are able to identify a counterparty or clean the text sufficiently, we will return that information in the counterparty object in addition to the third party object.
In implementation, we recommend always checking the third party field, even if no counterparty ID is returned, as there may be cases where only the third party is identified (e.g., for UberEats or other food delivery services).
Third Party ID
As with counterparties, each third party is returned with a third party ID. When a given entity (e.g. Instacart, Walmart, Apple) shows up in a transaction, it will have the same ID regardless of whether or not it is acting as a third party or a counterparty. During implementation, we recommend building rules and/or mappings using third party ID, not third party name.
Spending Controls
Spending controls provide a mechanism for issuing cards that can only be used at specific merchants (allowOnly), or for issuing cards that cannot be used at specific merchants (block).
To learn more about spending controls, please read the Spending Controls Guide