POST
/
transactions
/
cards
/
enrich
/
parse
Enrich a card transaction with an unparsed de43
curl --request POST \
  --url https://east.sandbox.spade.com/transactions/cards/enrich/parse \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "merchantName": "Amazon",
  "userId": "user_id_123456789",
  "cardId": "card_id_123456789",
  "cardFirstSix": "123456",
  "cardLastFour": "7890",
  "transactionId": "transaction_id_123456789",
  "acquirerId": "000000000123456",
  "amount": "25.23",
  "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
  },
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  },
  "de43": "WALMART.COM            BENTONVILLE  ARUS"
}'
{
  "transactionInfo": {
    "transferInfo": null,
    "isAccountVerification": false,
    "isPeerToPeer": false,
    "isDigitalWallet": false,
    "type": "spending",
    "subType": null,
    "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/"
      }
    ],
    "spendingInfo": {
      "channel": {
        "value": "digital"
      }
    },
    "atmInfo": null,
    "transactionId": "transaction_id_123456789",
    "recurrenceInfo": {
      "intervalType": "weekly",
      "intervalDays": 30,
      "nextPaymentExpected": "2024-08-07",
      "recentRecurrences": [
        [
          "<any>"
        ]
      ]
    },
    "riskInsights": {
      "irregularWebPresenceDetected": false,
      "negativeOnlineSentiment": false,
      "highRiskEntity": false,
      "riskyIndustry": false,
      "cardAcceptanceHistory": "extensive"
    }
  },
  "enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "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",
    "hasGamblingOrRewards": false,
    "hasSimulatedGambling": false,
    "ageRating": "Teen"
  },
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  }
}

Authorizations

​
X-Api-Key
string
header
required

Body

application/json
​
userId
string
required

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

Maximum length: 512
Examples:

"user_id_123456789"

​
amount
required

Value of the transaction in the given currency. Negative values indicate incoming money.

Examples:

"25.23"

​
currencyCode
string
required
Maximum length: 16
Examples:

"USD"

​
occurredAt
string<date-time>
required

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

Examples:

"2022-06-15 18:27:51Z"

​
categoryCode
string
required

Category code for the given categoryType

Maximum length: 32
Examples:

"5812"

​
categoryType
enum<string>
required

The category system that categoryCode is a part of

Available options:
MCC
Examples:

"MCC"

​
location
object
required
​
merchantName
string

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

Maximum length: 1024
Examples:

"Amazon"

​
cardId
string

Anonymous ID representing the card of the user.

Maximum length: 512
Examples:

"card_id_123456789"

​
cardFirstSix
string

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

Required string length: 6
Examples:

"123456"

​
cardLastFour
string

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

Required string length: 4
Examples:

"7890"

​
transactionId
string

Your ID representing this transaction

Maximum length: 512
Examples:

"transaction_id_123456789"

​
acquirerId
string

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)

Maximum length: 256
Examples:

"000000000123456"

​
customAttributes
object

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.

Examples:
{
  "custom_attribute_1": "value_1",
  "custom_attribute_2": "value_2"
}
​
de43
string

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.

Maximum length: 100
Examples:

"WALMART.COM BENTONVILLE ARUS"

Response

Successful operation

​
transactionInfo
object
​
enrichmentId
string<uuid>

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

​
counterparty
object[]

An array of counterparties matched to the transaction, ordered by descending match score.

​
mobileAppInfo
object | null

The mobile app information for the transaction. This object is only non-null if the transaction was matched to a mobile app.

This is a premium Spade field available depending on your product package.

​
customAttributes
object

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

Examples:
{
  "custom_attribute_1": "value_1",
  "custom_attribute_2": "value_2"
}