Spade’s enriched data—including clean names, logos, and merchant contact details—can be used to power user experiences that can provide clarity, increase engagement, and reduce disputes. There are two ways to integrate Spade's data in your UI:
- Build custom display logic using Spade's counterparty, third party and industry names and graphics
- Leverage Spade's recommended display information with the
display
object
Examples
To illustrate how this works we've provided two examples of transactions with the same counterparty but different third parties and how this can impact the recommended display.name
.
Description | Counterparty | Third Party | Display Name | Display Logo |
---|---|---|---|---|
SQ*SPADE PIZZA | Spade Pizza | Square | Spade Pizza | Spade Pizza |
DD*SPADEPIZZA | Spade Pizza | DoorDash | DoorDash - Spade Pizza | Spade Pizza |
{"transactionInfo":{
"display": {
"name": "Spade Pizza",
"categoryName": "Restaurant",
"graphic": "https://static.v2.spadeapi.com/logos/....png",
"graphicSource": "counterparty"
},
"thirdParties": [{
"id": "ab345...",
"name": "Square",
"type": "payment_processor",
"logo": "https://v1.spadeapi.com/logos/....png"
}]},
"counterparty": [{
"name": "Spade Pizza",
"logo": "https://static.v2.spadeapi.com/logos/....png",
"industry": [{
"id": "005-006-000-000",
"name": "Restaurants",
"icon": "https://static.v2.spadeapi.com/categories/....png"
}]}]}
{"transactionInfo":{
"display": {
"name": "Spade Pizza",
"categoryName": "Restaurant",
"graphic": "https://static.v2.spadeapi.com/logos/....png",
"graphicSource": "counterparty"
},
"thirdParties": [{
"id": "ac48cef2...",
"name": "DoorDash",
"type": "delivery_service",
"logo": "https://v1.spadeapi.com/logos/....png"
}]},
"counterparty": [{
"name": "Spade Pizza",
"logo": "https://static.v2.spadeapi.com/logos/....png",
"industry": [{
"id": "005-006-000-000",
"name": "Restaurants",
"icon": "https://static.v2.spadeapi.com/categories/....png"
}]}]}
In these examples, the user knows they made a purchase from Spade Pizza, but may not recognize the payment processor used at the restaurant’s POS system (e.g., Square). In contrast, a user ordering through DoorDash may be more likely to recognize the delivery service when reviewing their past purchases.
How to use the display object
Spade has created the display
object to easily surface the information most recognizable to a user for you to plug into your UI. The display
object consists of a combination of information from the counterparty and third party sections of the response. Provided below is the display
object returned from the previous example of a user ordering Spade Pizza via DoorDash.
{
"display": {
"name": "DoorDash - Spade Pizza",
"categoryName": "Restaurants",
"graphic": "https://static.v2.spadeapi.com/logos/...png",
"graphicSource": "counterparty"
}}
The display
object can be found in the transactionInfo
of both card and transfer enrichments.
name
- The recommended display namecategoryName
- The best description of the category, usually this is the counterparty industry, but it may also reflect some third parties, MCC, etc.graphic
- The recommended logo or icon to displaygraphicSource
- Indicates whether the graphic was sourced from either acounterparty
,third_party
, orcategory
. This is helpful if for example you use your own category iconography
Spade graphics
For more information on displaying logos and icons, see Spade graphics.
Additional display details
Location data
When Spade matches the transaction to a location we will provide both address details as well as latitude and longitude information which allows you to display a detailed map of where the transaction took place.
Note: We recommend only displaying location data when
spendingChannel = physical
to avoid confusion for online purchases that will show corporate locations that end users may not be familiar with.
Displaying addresses
Spade will return the full street address in location.address
. The street address will be parsed and will always return a value in addressLine1
but will only return a value in addressLine2
if the address has multiple lines.
In the first example below the address should be shown as:
1234 W 5th Ave
Suite 100 New York, NY 10001
{
"location": [{
"id": "fdf79470-3deb-4638-956a-6859e473b9d8",
"address": "1234 W 5th Ave Suite 100",
"addressLine1": "1234 W 5th Ave",
"addressLine2": "Suite 100",
"city": "New York",
"region": "NY",
"country": "USA",
"postalCode": "10001",
"latitude": 45,
"longitude": 120,
"phoneNumber": "+18664862360",
"matchScore": 93.5
}]}
For addresses with a single line you would simply use the address
field:
1234 W 5th Ave
New York, NY 10001
{
"location": [{
"id": "fdf79470-3deb-4638-956a-6859e473b9d8",
"address": "1234 W 5th Ave",
"addressLine1": "1234 W 5th Ave",
"addressLine2": null,
"city": "New York",
"region": "NY",
"country": "USA",
"postalCode": "10001",
"latitude": 45,
"longitude": 120,
"phoneNumber": "+18664862360",
"matchScore": 93.5
}]}
Displaying geolocation
By showing a transaction’s location on a map, users can more easily confirm purchases and identify potentially fraudulent activity. When available we will provide thelocation.latitude
and location.longitude
for you to use to generate a map in your UI.
Phone numbers
We recommend using the counterparty.phoneNumber
when it is present and falling back to counterparty.location.phoneNumber
. When the counterparty is a corporation, such as WalMart, the counterparty phone number represents the corporate phone number and the location phone number is the phone number for the specific store location.
Original description
In addition to the enriched transaction description, we recommend displaying a field with the original descriptor (e.g., APPEARS ON STATEMENT: SBX1234) to ensure parity with statements.