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 '
{
  "userId": "<string>",
  "amount": 123,
  "currencyCode": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "categoryCode": "<string>",
  "categoryType": "MCC",
  "location": {
    "country": "<string>",
    "address": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postalCode": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "merchantName": "<string>",
  "cardId": "<string>",
  "cardFirstSix": "<string>",
  "cardLastFour": "<string>",
  "transactionId": "<string>",
  "acquirerId": "<string>",
  "customAttributes": {},
  "de43": "<string>"
}
'

{
  "transactionInfo": {
    "transferInfo": null,
    "isAccountVerification": false,
    "isPeerToPeer": false,
    "isDigitalWallet": false,
    "type": "account_verification",
    "subType": "alimony_or_child_support",
    "display": {
      "name": "<string>",
      "categoryName": "<string>",
      "graphic": "<string>",
      "graphicSource": "<string>"
    },
    "thirdParties": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "type": "bnpl",
        "logo": "<string>",
        "website": "<string>"
      }
    ],
    "spendingInfo": {
      "channel": {
        "value": "digital"
      }
    },
    "atmInfo": {
      "sponsorName": "<string>",
      "ownerName": "<string>"
    },
    "transactionId": "<string>",
    "recurrenceInfo": {
      "intervalType": "weekly",
      "intervalDays": 123,
      "nextPaymentExpected": "2023-12-25",
      "recentRecurrences": [
        "<array>"
      ]
    },
    "riskInsights": {
      "irregularWebPresenceDetected": true,
      "negativeOnlineSentiment": true,
      "highRiskEntity": true,
      "riskyIndustry": true,
      "cardAcceptanceHistory": "extensive"
    }
  },
  "enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "counterparty": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "legalName": "<string>",
      "industry": [
        {
          "id": "<string>",
          "name": "<string>",
          "icon": "<string>"
        }
      ],
      "matchScore": 123,
      "location": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "address": "<string>",
          "addressLine1": "<string>",
          "addressLine2": "<string>",
          "city": "<string>",
          "region": "<string>",
          "country": "<string>",
          "postalCode": "<string>",
          "latitude": 123,
          "longitude": 123,
          "phoneNumber": "<string>",
          "matchScore": 123
        }
      ],
      "logo": "<string>",
      "phoneNumber": "<string>",
      "website": "<string>",
      "possibleCounterpartyAlternate": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "similarity": 123
      }
    }
  ],
  "mobileAppInfo": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "url": "<string>",
    "logo": "<string>",
    "developerName": "<string>",
    "developerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "category": "<string>",
    "hasGamblingOrRewards": true,
    "hasSimulatedGambling": true,
    "ageRating": "<string>"
  },
  "customAttributes": {}
}

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 [email protected] with any questions.

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 '
{
  "userId": "<string>",
  "amount": 123,
  "currencyCode": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "categoryCode": "<string>",
  "categoryType": "MCC",
  "location": {
    "country": "<string>",
    "address": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postalCode": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "merchantName": "<string>",
  "cardId": "<string>",
  "cardFirstSix": "<string>",
  "cardLastFour": "<string>",
  "transactionId": "<string>",
  "acquirerId": "<string>",
  "customAttributes": {},
  "de43": "<string>"
}
'

{
  "transactionInfo": {
    "transferInfo": null,
    "isAccountVerification": false,
    "isPeerToPeer": false,
    "isDigitalWallet": false,
    "type": "account_verification",
    "subType": "alimony_or_child_support",
    "display": {
      "name": "<string>",
      "categoryName": "<string>",
      "graphic": "<string>",
      "graphicSource": "<string>"
    },
    "thirdParties": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "type": "bnpl",
        "logo": "<string>",
        "website": "<string>"
      }
    ],
    "spendingInfo": {
      "channel": {
        "value": "digital"
      }
    },
    "atmInfo": {
      "sponsorName": "<string>",
      "ownerName": "<string>"
    },
    "transactionId": "<string>",
    "recurrenceInfo": {
      "intervalType": "weekly",
      "intervalDays": 123,
      "nextPaymentExpected": "2023-12-25",
      "recentRecurrences": [
        "<array>"
      ]
    },
    "riskInsights": {
      "irregularWebPresenceDetected": true,
      "negativeOnlineSentiment": true,
      "highRiskEntity": true,
      "riskyIndustry": true,
      "cardAcceptanceHistory": "extensive"
    }
  },
  "enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "counterparty": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "legalName": "<string>",
      "industry": [
        {
          "id": "<string>",
          "name": "<string>",
          "icon": "<string>"
        }
      ],
      "matchScore": 123,
      "location": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "address": "<string>",
          "addressLine1": "<string>",
          "addressLine2": "<string>",
          "city": "<string>",
          "region": "<string>",
          "country": "<string>",
          "postalCode": "<string>",
          "latitude": 123,
          "longitude": 123,
          "phoneNumber": "<string>",
          "matchScore": 123
        }
      ],
      "logo": "<string>",
      "phoneNumber": "<string>",
      "website": "<string>",
      "possibleCounterpartyAlternate": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "similarity": 123
      }
    }
  ],
  "mobileAppInfo": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "url": "<string>",
    "logo": "<string>",
    "developerName": "<string>",
    "developerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "category": "<string>",
    "hasGamblingOrRewards": true,
    "hasSimulatedGambling": true,
    "ageRating": "<string>"
  },
  "customAttributes": {}
}

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 string length: 512

amount

required

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

currencyCode

string

required

Maximum string length: 16

occurredAt

string<date-time>

required

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

categoryCode

string

required

Category code for the given categoryType

Maximum string length: 32

categoryType

enum<string>

required

The category system that categoryCode is a part of

Available options:

MCC

Maximum string length: 32

location

object

required

Show child attributes

location.country

string

required

Three letter country code.

Maximum string length: 256

location.address

string

Maximum string length: 256

location.city

string

The city as it appears in the transaction data; in some cases this can be a phone number or website, which are also valid inputs.

Maximum string length: 256

location.region

string

Two letter code for state, province, territory, etc. For US states, ANSI codes may be provided instead (e.g. "15" for Hawaii). While standard two-letter or ANSI codes are preferred when available, full region names may also be provided (e.g. "Hawaii"). For an enhanced response, we *strongly* recommend including this field.

Maximum string length: 256

location.postalCode

string

A US zip code or other international postal code. In the case where a US zip code is provided and the state is missing, the state will be inferred from the zip code.

Maximum string length: 32

location.latitude

number | null

Additional latitude data related to the transaction being enriched.

location.longitude

number | null

Additional longitude data related to the transaction being enriched.

merchantName

string

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

Maximum string length: 1024

cardId

string

Anonymous ID representing the card of the user.

Maximum string length: 512

cardFirstSix

string

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

Required string length: 6

cardLastFour

string

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

Required string length: 4

transactionId

string

Your ID representing this transaction

Maximum string length: 512

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 string length: 256

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.

Show child attributes

customAttributes.{key}

string

Maximum string length: 250

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 string length: 100

Response

Successful operation

transactionInfo

object

Show child attributes

transactionInfo.transferInfo

object

Additional information about transfers. This field is null for card transactions.

Show child attributes

transactionInfo.transferInfo.direction

enum<string>

The transfer direction.

Available options:

outgoing,

incoming

transactionInfo.transferInfo.transferMethod

enum<string>

The transfer method.

Available options:

ach,

cash,

check,

intrabank,

rtp,

unknown,

wire

transactionInfo.transferInfo.transferType

enum<string>

The transfer type. "external" indicates that money is being sent to an external counterparty. "internal" indicates that money is being moved between accounts owned by the same entity.

Available options:

external,

internal,

unknown

transactionInfo.transferInfo.isAdjustmentOrRefund

boolean

Whether the transfer is an adjustment or refund.

Example:

null

transactionInfo.isAccountVerification

boolean | null

Whether the transfer is an account verification. Currently only available for transfers.

Example:

false

transactionInfo.isPeerToPeer

boolean | null

Whether the transaction is a peer-to-peer transaction. Currently only available for transfers.

Example:

false

transactionInfo.isDigitalWallet

boolean | null

Whether the transaction involves a digital wallet. Currently only available for transfers.

Example:

false

transactionInfo.type

enum<string>

The main type of the transaction. For card transactions, the type is always "spending".

Available options:

account_verification,

atm,

debt,

fee,

income,

other_money_movement,

reimbursement,

spending

transactionInfo.subType

enum<string> | null

The more specific type of the transaction, if applicable. For card transactions, the subType is always null.

Available options:

alimony_or_child_support,

atm,

bnpl,

business,

cash_advance,

deposit,

disbursements,

earned_income,

government_benefits,

insurance,

investment,

nsf,

other,

overdraft,

payment,

payout,

rental,

retirement,

tax_refund,

transfer,

withdrawal

transactionInfo.display

object

An object containing display information for the transaction. The fields in this object are pulled from other parts of the enrichment and surfaced here for convenience.

Show child attributes

transactionInfo.display.name

string

The best name for display.

transactionInfo.display.categoryName

string | null

The best category name for display.

transactionInfo.display.graphic

string<url> | null

The best graphic for display. Depending on the data available, this will be either a) the counterparty logo, b) the third party logo, or c) the category icon.

transactionInfo.display.graphicSource

string | null

The field from which the graphic was sourced. This will be either counterparty, third_party, or category.

transactionInfo.thirdParties

object[]

An array of third parties involved in the transaction, when applicable. Entities such as Toast, Square, Uber Eats, Doordash, etc. will appear here.

Show child attributes

transactionInfo.thirdParties.id

string<uuid>

transactionInfo.thirdParties.name

string

transactionInfo.thirdParties.type

enum<string>

Available options:

bnpl,

delivery_service,

payment_processor,

platform

transactionInfo.thirdParties.logo

string<url> | null

Third party logo.

transactionInfo.thirdParties.website

string<url> | null

Third party website.

transactionInfo.spendingInfo

object

Additional information about transactions whose type is "spending". This field is null for other types of transactions.

Show child attributes

transactionInfo.spendingInfo.channel

object

Show child attributes

transactionInfo.spendingInfo.channel.value

enum<string> | null

Spending channel value of digital or physical, null if we are unable to determine.

Available options:

digital,

physical,

transactionInfo.atmInfo

object

Additional information about ATM transactions. This field is null for other types of transactions.

Show child attributes

The name of the sponsor of the ATM involved in the transaction.

transactionInfo.atmInfo.ownerName

string

The name of the owner of the ATM involved in the transaction.

transactionInfo.transactionId

string

Your ID representing this transaction. This ID exactly matches the transactionId you provided in your enrichment request.

transactionInfo.recurrenceInfo

object

A recurring transaction is a repeated payment pattern to a counterparty, based on periodicty and amount. Premium Spade Signal available depending on your product package.

Show child attributes

transactionInfo.recurrenceInfo.intervalType

enum<string> | null

Recurrence cadence.

Available options:

weekly,

biweekly,

monthly,

quarterly,

annually

transactionInfo.recurrenceInfo.intervalDays

integer | null

Number of days between recurrences.

transactionInfo.recurrenceInfo.nextPaymentExpected

string<date> | null

Next expected payment date.

transactionInfo.recurrenceInfo.recentRecurrences

array[] | null

Array of recent recurrence objects, null if no recurrence exists.

transactionInfo.riskInsights

object

Risk insights provide visibility into the potential risk of a transaction and the merchants involved. Premium Spade Signal available depending on your product package.

Show child attributes

transactionInfo.riskInsights.irregularWebPresenceDetected

boolean | null

Has engaged in deceptive online practices or has irregular website structure or content.

transactionInfo.riskInsights.negativeOnlineSentiment

boolean | null

Negative online consumer feedback associated with the counterparty.

transactionInfo.riskInsights.highRiskEntity

boolean | null

The counterparty is known to engage in fraudulent practices.

transactionInfo.riskInsights.riskyIndustry

boolean | null

Industry is correlated with increased disputes (based on Spade industries).

transactionInfo.riskInsights.cardAcceptanceHistory

enum<string> | null

Counterparties with lower levels of card acceptance history have a higher likelihood of chargebacks or fraudulent activity.

Available options:

extensive,

established,

stable,

limited,

very_limited,

null

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.

Show child attributes

counterparty.id

string<uuid> | null

A unique identifier for this counterparty, regardless of specific location.

counterparty.name

string | null

Counterparty name.

counterparty.legalName

string | null

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

counterparty.industry

object[]

Array with increasingly specific category information.

Show child attributes

counterparty.industry.id

string

counterparty.industry.name

string

counterparty.industry.icon

string<url> | null

Category icon.

counterparty.matchScore

number | null

The matchScore predicts how well a transaction matches a Counterparty in our records. If no Counterparty was found, the matchScore is set to null. Otherwise, scores range between 50.00 and 100.00. We filter out results below this range to make sure that only high quality matches are returned. Generally, the higher the matchScore is the better the match between a transaction and a Counterparty. When multiple Counterparties match a transaction, matches are returned in decreasing order of matchScore. This is a premium Spade field available depending on your product package.

counterparty.location

object[]

An array of locations matched to the transaction (and associated with this counterparty). Can currently contain only one location. This is a premium Spade field available depending on your product package.

Show child attributes

counterparty.location.id

string<uuid> | null

A unique identifier for this location.

counterparty.location.address

string | null

Street number, name, and any secondary address information.

counterparty.location.addressLine1

string | null

Street number and name.

counterparty.location.addressLine2

string | null

Secondary address information.

counterparty.location.city

string | null

counterparty.location.region

string | null

Two letter region code.

counterparty.location.country

string

Three letter country code.

counterparty.location.postalCode

string | null

Location postal code or zip code.

counterparty.location.latitude

number | null

Location latitude.

counterparty.location.longitude

number | null

Location longitude.

counterparty.location.phoneNumber

string | null

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

counterparty.location.matchScore

number | null

The matchScore predicts how well a transaction matches a Location in our records. If no Location was found, the matchScore is set to null. Scores range between 0.00 and 100.0. Generally, a higher matchScore indicates a better match between a transaction and a Location. This is a premium Spade field available depending on your product package.

counterparty.logo

string<url> | null

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

counterparty.phoneNumber

string | null

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

counterparty.website

string<url> | null

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

counterparty.possibleCounterpartyAlternate

object

The possible alternate counterparty object represents a counterparty that may be matched to this transaction in other enrichment requests. Premium Spade Field available depending on your product package.

Show child attributes

counterparty.possibleCounterpartyAlternate.id

string<uuid>

The ID of the alternate counterparty.

counterparty.possibleCounterpartyAlternate.similarity

number

The similarity score indicates how closely this alternate counterparty matches the main counterparty. The score is a value between 0.0 and 100.0, where 100.0 is an exact match.

mobileAppInfo

object

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.

Show child attributes

mobileAppInfo.id

string<uuid>

A unique identifier for this mobile app.

mobileAppInfo.name

string

The name of the mobile app.

mobileAppInfo.url

string<url> | null

The URL of the mobile app in the app store.

mobileAppInfo.logo

string<url> | null

The URL of the mobile app's logo.

mobileAppInfo.developerName

string

The name of the developer of the mobile app.

mobileAppInfo.developerId

string<uuid>

The ID of the developer of the mobile app.

mobileAppInfo.category

string

The category of the mobile app. The possible values are:

Auto and Transportation
Creative and Design
Education and Parenting
Entertainment and Media
Finance and Business
Games
Health and Lifestyle
Shopping and Marketplaces
Social and Communication
Travel and Events
Utility and Tools

mobileAppInfo.hasGamblingOrRewards

boolean

Whether the mobile app has gambling or cash rewards.

mobileAppInfo.hasSimulatedGambling

boolean

Whether the mobile app has simulated gambling.

mobileAppInfo.ageRating

string

The age rating of the mobile app. The possible values are:

Children
Teen
Adult

customAttributes

object

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

Show child attributes

customAttributes.{key}

string

Enrich a card transaction Enrich a card transaction (deprecated)

⌘I

Card Enrichment

Transfer Enrichment

Universal Enrichment

Feedback and Reporting

Merchant Search

Merchant Matching

Category Personalization

Enrich a card transaction with an unparsed de43

Authorizations

Body

Response