Card Enrichment

Enrich a card transaction with an unparsed de43

Enrich a card transaction where parsed de43 data takes precedence over the other fields in the request body. This otherwise endpoint is identical to /transactions/cards/enrich except that city and merchantName are now optional, but only when de43 is included. Note: Because DE43 format is not consistent between sources, we recommend parsing your own data and using /transactions/cards/enrich/ if possible.

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

post/transactions/cards/enrich/parse

Request

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

Request body

merchantNamestring

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.

de43string

A well formatted de43 message. If parsable the parsed data (merchantName, city, state) will take precedence over the corresponding fields in the request body. The parser expects an unedited de43, please do not remove special characters or spaces. Our parser currently only supports US transactions.

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"
  },
  "de43": "WALMART.COM            BENTONVILLE  ARUS"
}

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.