SPspade
Card Enrichment

Enrich a card transaction

When working with this endpoint, note that several of the input fields are optional (region, acquirerId, etc.). However, we strongly recommend including all of the fields that you have available. Some optional fields can substantially improve performance.

Take care to ensure you are using unaltered and correct data in each field. Some fields go by multiple names, so if you have any questions regarding integration please feel free to reach out.

Note that some response fields may not be included in your product package, please reach out with any questions.

post/transactions/cards/enrich

Request

  • Base URL
    https://east.sandbox.spade.com
  • URL
    https://east.sandbox.spade.com/transactions/cards/enrich
  • Auth
    API key in header X-Api-Key

Request body

merchantNamestring required

The raw, unmodified merchant name (including asterisks, store numbers, etc...)

organizationIdstring

An ID representing the organization associated with this transaction. Use this field if you are enriching transactions on behalf of other organizations. Used for billing purposes and for scoping products such as action triggers and category personalizations at the organization-level. For more info, see Supporting multiple data sources and clients

programIdstring

An identifier for the program associated with this transaction. Programs can be used to group transactions and scope action triggers at the program level.

userIdstring required

Anonymous ID representing your user. This will be used for summary features, and recurrence flagging purposes.

cardIdstring

Anonymous ID representing the card of the user.

cardFirstSixstring

The first six digits of the card number associated with the transaction.

cardLastFourstring

The last four digits of the card number associated with the transaction.

transactionIdstring

Your ID representing this transaction

acquirerIdstring

An alphanumeric code generally with a maximum length of 15. It is also known as "Network ID", "Card Acceptor ID", or "Merchant ID". (Found in field 42 of ISO 8583)

currencyCodestring required
occurredAtstring date-time required

The time the transaction occurred. Formatted as an ISO 8601 date time.

categoryCodestring required

Category code for the given categoryType

categoryType'MCC'

The category system that categoryCode is a part of. Optional; if omitted it defaults to MCC. Do not send null or an empty string — when the field is present it must be a valid, non-empty value (MCC).

billingProfile'standard' | 'resell'

An optional billing profile for this transaction. When set to "resell", the organizationId field is required. For more information, see Supporting multiple data sources and clients

customAttributesCustomAttributesRequestField

A dictionary containing custom attributes that you would like to be returned in the response. Please ensure this object does not contain any PII. Restrictions include: customAttributes must be an object, up 30 custom attributes are allowed, each key must be a string <= 40 characters in length, and each value must be a string <= 250 characters in length.

Example request

{
  "merchantName": "Amazon",
  "organizationId": "organization_id_123",
  "programId": "program_id_123",
  "userId": "user_id_123456789",
  "cardId": "card_id_123456789",
  "cardFirstSix": "123456",
  "cardLastFour": "7890",
  "transactionId": "transaction_id_123456789",
  "acquirerId": "000000000123456",
  "currencyCode": "USD",
  "occurredAt": "2022-06-15 18:27:51Z",
  "categoryCode": "5812",
  "categoryType": "MCC",
  "location": {
    "address": "1234 W 5th Ave Suite 100",
    "city": "New York",
    "region": "NY",
    "country": "USA",
    "postalCode": "10001",
    "latitude": 45,
    "longitude": 120
  },
  "billingProfile": "standard",
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  }
}

Response

Successful operation

enrichmentIdstring uuid

Our ID representing the enrichment, not to be confused with your provided transactionId.

customAttributesCustomAttributesResponseField

A dictionary containing the custom attributes that were included in the enrichment request (if any).

Example response

{
  "transactionInfo": {
    "transferInfo": {
      "direction": "outgoing",
      "transferMethod": "ach",
      "transferType": "external"
    },
    "type": "spending",
    "display": {
      "name": "Amazon",
      "categoryName": "Online Marketplace",
      "graphic": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
      "graphicSource": "counterparty"
    },
    "thirdParties": [
      {
        "id": "ac48cef2-0d7f-4159-865e-e92b152262bc",
        "name": "Paypal",
        "type": "payment_processor",
        "logo": "https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png",
        "website": "https://www.paypal.com/"
      }
    ],
    "atmInfo": {
      "sponsorName": "Fiserv",
      "ownerName": "Wells Fargo"
    },
    "transactionId": "transaction_id_123456789",
    "recurrenceInfo": {
      "intervalDays": 30,
      "nextPaymentExpected": "2024-08-07"
    },
    "riskInsights": {
      "cardAcceptanceHistory": "extensive"
    }
  },
  "counterparty": [
    {
      "id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
      "name": "Amazon",
      "legalName": "Amazon Inc.",
      "industry": [
        {
          "id": "011-000-000-000",
          "name": "Retail",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        }
      ],
      "matchScore": 93.5,
      "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
        }
      ],
      "logo": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
      "phoneNumber": "+18664862360",
      "website": "https://www.amazon.com",
      "possibleCounterpartyAlternate": {
        "id": "49fd51a1-5a19-3e5d-8d28-eb056ecf8939",
        "similarity": 80
      }
    }
  ],
  "mobileAppInfo": {
    "id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
    "name": "Roblox",
    "url": "https://play.google.com/store/apps/details?id=com.roblox.client",
    "logo": "https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png",
    "developerName": "Roblox Corporation",
    "developerId": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
    "category": "Auto and Transportation",
    "ageRating": "Teen"
  },
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  },
  "actions": [
    {
      "id": "trigger-12345",
      "type": "merchant_trigger",
      "action": {
        "type": "REWARD",
        "rewardPercent": 5
      },
      "scope": "account",
      "source": "counterparty"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.