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.
DescriptionCounterpartyThird PartyDisplay NameDisplay Logo
SQ*SPADE PIZZASpade PizzaSquareSpade PizzaSpade Pizza
DD*SPADEPIZZASpade PizzaDoorDashDoorDash - Spade PizzaSpade 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"
                }
            ]
        }
    ]
}
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 name
  • categoryName - 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 display
  • graphicSource - Indicates whether the graphic was sourced from either acounterparty, third_party, or category. This is helpful if for example you use your own category iconography
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.