LogoLogo
StatusChangelogDashboardCreate a Ticket
  • Getting Started
  • Intro to APIs
  • How to Contact us
  • How to Go-Live
  • Intro to Risk
  • Intro to Spec Sheets
  • Product Guides
    • Deposit Hub
      • 🌎Global Cash
    • Credit Hub
    • Payment Accounts
    • ID Score
  • API References
    • OAuth
      • OAuth Object Details
      • Create OAuth Key
      • Generate Refresh Token
    • Users
      • User Object Details
      • Testing on UAT
      • View All Users
      • View User
      • Create User
      • Update User
      • Generate UBO Doc
      • Manage Duplicates
      • Allowed Document Types
      • Allowed Entity Scopes
      • Allowed Entity Types
    • Nodes
      • Node Object Details
      • Testing on UAT
      • View all User Nodes
      • View Node
      • Create Node
      • Update Node
      • Generate eCash Barcode
      • Allowed Node Types
      • View ATMs
    • Subnets
      • Subnet Object Details
      • Testing on UAT
      • View all Node Subnets
      • View Subnet
      • Create Subnet
      • Update Subnet
      • Push to Wallet
    • Shipments
      • Shipment Object Details
      • View all Subnet Shipments
      • View Shipment
      • Create Shipment
      • Cancel Shipment
    • Statements
      • Statement Object Details
      • View all User Statements
      • View all Node Statements
    • Transactions
      • Transaction Object Details
      • Testing on UAT
      • View all User Transactions
      • View all Node Transactions
      • View Transaction
      • Create Transaction
      • Create Batch Transactions
      • Cancel Transaction
      • Retry ACH Transaction
      • Dispute Chargebacks
      • Dispute Transaction
    • Subscriptions
      • Subscription Object Details
      • Webhook Object Details
      • Testing on UAT
      • View all Subscriptions
      • View Subscription
      • Create Subscription
      • Update Subscription
      • View Webhook Logs
    • Miscellaneous
      • Dummy Transactions
      • Verify Address
      • Verify Routing Number
      • International WIRE-INT Required Data by Country
      • View Billers
      • View Enriched Data
      • Loan Limits
      • Transaction Decisioning
      • 3D Secure
      • Virtual Terminal
      • Pre-Authorization
      • Card Disputes Guide
      • Mobile Wallets
      • Interchange Revenue
      • Enrichment Guide
  • Developer Guides
    • User Onboarding
      • Create User Flow
      • Authenticate as the User
      • Create Node Flow
        • Cash Advance
        • Credit Builder Loan
        • One Time Loans
        • Secured Open Loans
        • Secured Revolving Loans
        • Unsecured Revolving Loans
      • Create Subnets Flow
        • Creating Cards
        • Creating AC/RT
      • Linking External Accounts
        • Linking Cards
        • Linking External Bank Account
      • Add Additional Documents
    • Account Details
      • Displaying Balances
      • Transaction History
      • Transaction Details
      • Account Agreements
      • Node Statements
      • Card Details
    • Managing Cards
      • Card Preferences
      • Setting PIN
      • Mobile Wallet Flow
        • Integrate with Apple Pay
        • Integrate with Google Pay
        • Integrate with Samsung Pay
      • Shipping Cards
    • Originating Transactions
      • Sending Fed Wires
      • Sending ACH Transfers
      • Sending International Wires
      • Deposit a Check
      • Issuing Checks
      • Recurring Transactions
      • 3rd Party Payment Accounts
      • Cancelling Transactions
      • Exceeding Origination Limits
    • Receiving Transactions
      • Transaction Decisioning
      • Receiving ACH / Wires
      • Card Transactions
      • Exceeding Inbound Limits
    • Managing Disputes
      • ACH Disputes
      • Card Disputes
    • 3rd Party Integrations
      • Payment Integrations
      • Account Aggregators
      • 3rd Parties & Compliance
  • Recipes
    • Overdraft Protection
    • Social Banking
    • Monetizing Transactions
Powered by GitBook
On this page
  • The Enriched Info Object
  • Enriched Info Object Examples
  • Structure of the Enriched Info Object
  • Merchant Profiles
  • Merchant Profile Basic Details
  • Merchant Profile Examples
  • Transaction Categories
  • Implementing the Enrichment Service
  • Early-Stage
  • Growth
  • Enterprise

Was this helpful?

Export as PDF
  1. API References
  2. Miscellaneous

Enrichment Guide

PreviousInterchange RevenueNextUser Onboarding

Last updated 2 years ago

Was this helpful?

Enrichment service is our data repository and intelligence engine that classifies, categorizes, and analyzes user transactions. Examples of data provided include the relevant business entity, location, and the category of the expense. (See: ).

This information is stored in our ever-expanding Knowledge Repository and returned with transactions in Enriched Info (enriched_info) for Card Transactions.

The Enriched Info Object

When a card transaction is received by us, we run it through our Knowledge Repository to appropriately assign:

  • the Merchant Profile(s) that describe the type of business, physical retail location, or facilitator who provided Synapse with the transaction.

  • the Transaction Category (enriched_info.category) for the transaction to place it into easily recognizable "buckets" from which potentially the end user, platform, or Synapse could then take further actions.

Enriched Info Object Examples

// PAYPAL *NETFLIX.COM 4029357733   CA 950327620
{
    "category": "entertainment",
    "entity_id": "5bde7b198ddd931c7ee7d0df", // Netflix
    "facilitator_id": "5bde7b198ddd931c7ee7d0e0", // Paypal
    "location_id": null,
    "status": "SETTLED"
}
// PAYPAL *PENGZHONGFA 4029357733 CA 95131
{
    "category": "shopping",
    "entity_id": null,
    "facilitator_id": "5bde7b198ddd931c7ee7d0e0", // Paypal
    "location_id": null,
    "status": "SETTLED"
}
// SQ *SUNSHINE MARKET LONG BEACH CA 90802
{
    "category": "food&drink",
    "entity_id": null,
    "facilitator_id": "5bde7b198ddd931c7ee7d0e2", // Square
    "location_id": "5cbb6df99000ab190894c4f1", // Sunshine Convenience Market
    "status": "SETTLED"
}
# MCDONALD S F1063 LOS ANGELES CA 90016
{
    "category": "food&drink",
    "entity_id": "5bde7b198ddd931c7ee7d0de", // McDonald's (chain)
    "facilitator_id": null,
    "location_id": "5d8010fb33c4bef4facee888", // McDonald's (local)
    "status": "SETTLED"
}
// JT BEAUTY KANSAS CITY MO 641343315
{
    "category": "shopping",
    "entity_id": null,
    "facilitator_id": null,
    "location_id": "5d73d3d0a8120df48e6cd1be", // JT Beauty Supply
    "status": "SETTLED"
}

Structure of the Enriched Info Object

Key

Type

Description

category

string

General category of the expense (e.g. "cash", "entertainment", "food&drink", "health", "services", "shopping", "transfer", "transportation", "travel"). Simplified / aggregated based on internal logic (similar to Merchant Category Codes / MCCs used by card processors). Please note that category is assigned according to the transaction rather than Merchant Profile (i.e. multiple transactions with different categories can be matched to the same Merchant Profile).

entity_id

string

Entity ID (i.e. the unique identifier that maps to the business entity / Corporate Entity Profile associated with the transaction).

facilitator_id

string

Facilitator ID (i.e. the unique identifier that maps to the facilitator / Facilitator Profile associated with transaction).

location_id

string

Location ID (i.e. the unique identifier that maps to the specific retail location / Location Profile associated with the transaction)

status

string

The status for the merchant information in the Knowledge Repository. The value can either be SETTLED or PENDING.

One-off locations (e.g. a "mom-and-pop" location that is not part of a chain or other larger corporate entity) may only have a location_id (i.e. you will find both entity_id: "null" and facilitator_id: "null").

Please also note that you may also find location_id: "null" (e.g. for an online-only transaction for Netflix facilitated by PayPal)

If the business is not currently confirmed in our Knowledge Repository, then all values associated with the enriched_info attached to the transaction may be "null". Additionally, if a transaction was not matched to a Merchant Profile in the repository, status will be "PENDING" (it may take up to 48 hours to review and update information in the repository).

Lastly, if you suspect the merchant information is incorrect. Please follow these steps to report these issue to us:

  • If the enriched_info.status: "SETTLED" and the name, logo, or official_page is incorrect

  • OR

  • If the enriched_info.status: "PENDING" and the name, logo, or official_page is incorrect for greater than 48 hours

Merchant Profiles

The Knowledge Repository consists of Merchant Profiles that represent the businesses we provide enriched financial data about. A Merchant Profile can represent:

  • a larger business or corporate entity,

  • a specific retail location, or

  • a facilitator.

Please refer to basic details and examples below.

Merchant Profile Basic Details

Merchant β€Œβ€ŒProfile

Details

Examples β€Œβ€Œ

Corporate Entity Profile

Profile for a business or corporate entity (e.g. a restaurant or store chain).

McDonald's Walmart 7-Eleven

Location Profile

Profile for a specific retail location (e.g. a singular business location or a franchise location).

Singular Business Location Example "Sunshine Convenience Market" β€Œβ€Œ Franchise Location Example "MCDONALD S F1063 LOS ANGELES CA 90016"

Facilitator Profile

Profile for a payment facilitator, hotel/discount travel facilitator, or other type of facilitator for the transaction. Please note that payment facilitators are in control of transaction formatting and use their own formats that may restrict our Enrichment service's ability to identify a final merchant for a transaction (e.g. by prepending an abbreviated code, followed by an asterisk, followed by a short transaction description that may be truncated such that we are unable to parse a merchant name). We provide facilitator information as part of our effort to transparently provide as much information as possible for each transaction.

Payment Facilitator Examples PayPal Apple Pay Google Pay Venmo Square Cash App β€Œβ€Œ Hotel / Discount Travel Facilitator HotelTonight Expedia β€Œβ€Œ Other Facilitators Kickstarter Indiegogo ActBlue WinRed

Please note that a retail location that is part of a larger business or corporate entity will have its own Location Profile and will reference the Corporate Entity Profile of its parent company. A singular business location (e.g. a "mom and pop" operation with only one location) will have a Location Profile but will not reference a parent company (i.e. will not reference a Corporate Entity Profile).

Merchant Profile Examples

{
    "_id": "5bde7b198ddd931c7ee7d0de",
    "address": {
        "city": "Oak Brook",
        "country_code": "US",
        "loc": [
            41.84754,
            -87.97179
        ],
        "postal_code": "60523",
        "street1": "2111 Midwest Rd",
        "street2": null,
        "subdivision": "IL"
    },
    "analytics": {},
    "logo": "https://cdn4.synapsefi.com/uploads/2020/01/03/1lcwyJFj8OMG0fb0vqiUTVCQHtamLKDRp6WAnESY5Ixe73uNP4.png",
    "name": "McDonald's",
    "official_page": "https://www.mcdonalds.com/",
    "phone_number": {
        "country_code": "1",
        "national_number": "8884244622"
    },
    "scope": "entity"
}
{
    "_id": "5d8010fb33c4bef4facee888",
    "address": {
        "city": "Los Angeles",
        "country_code": "US",
        "loc": [
            34.03021,
            -118.33469
        ],
        "postal_code": "90016",
        "street1": "2838 Crenshaw Blvd",
        "street2": null,
        "subdivision": "CA"
    },
    "analytics": {},
    "name": "McDonald's",
    "phone_number": {
        "country_code": "1",
        "national_number": "3237310046"
    },
    "scope": "location"
}
{
    "_id": "5bde7b198ddd931c7ee7d0e0",
    "address": {
        "city": "San Jose",
        "country_code": "US",
        "loc": [
            37.37696,
            -121.92266
        ],
        "postal_code": "95131",
        "street1": "2211 N 1st St",
        "street2": null,
        "subdivision": "CA"
    },
    "analytics": {},
    "logo": "https://cdn4.synapsefi.com/uploads/2020/03/06/d2BYQAtzO39x0VZu05qL4UcMajsFWE7rgDlRIbe8fTvkhi1Swo.jpeg",
    "name": "PayPal",
    "official_page": "https://www.paypal.com/",
    "phone_number": {
        "country_code": "1",
        "national_number": "8882211161"
    },
    "scope": "entity"
}

Transaction Categories

We similarly classify transactions from businesses by functionally combining their transactions into the following general categories:

Category

Examples

cash

cash disbursements (e.g. manual and ATMs)

entertainment

movies, amusements parks, shows, exhibits, digital subscriptions

food&drink

restaurants, fast food, grocery, alcohol & bars, delivery service facilitators (e.g. DoorDash, UberEats, GrubHub, etc.)

health

medical care, pharmacies, doctors, health practitioners

services

other services not classified as "entertainment," "health," or "transportation" (e.g. utilities, insurance, education, laundry, beauty shops, repair shops, etc.)

shopping

clothing retailers, electronics retailers, online merchants

transfer

person-to-person (P2P) money transfers (Cash App, Venmo, Paypal, Apple Pay, etc.)

transportation

public transportation, ridesharing (e.g. Uber/Lyft), taxi, parking, service stations, auto supplies, fuel

travel

car rentals, airlines, hotels, travel agencies, cruises, hotel/discount travel facilitators (e.g. HotelTonight, Expedia, etc.)

Implementing the Enrichment Service

How your platform chooses to pull data from our Knowledge Repository will vary based on the maturity of your platform and the size of your user base. An early-stage startup and a large enterprise operation will have different priorities in terms of optimizing for speed of development vs maximizing efficiencies at scale. Here are three suggestions:

  • Early-Stage Approach (suitable for early-stage startups or for initial rapid prototyping)

  • Growth Approach (suitable for growth-stage companies beginning to scale up operations)

  • Enterprise Approach (suitable for enterprises performing operations at scale)

Early-Stage

This approach is by far the easiest to implement, but is an inefficient solution at scale.

This approach means that you will be performing (and therefore repeating) distinct API calls to retrieve Merchant Profiles from the Knowledge Repository each time you process a new transaction.

Growth

This approach attempts to strike a balance between development time, ease of implementation, and scalability, but it is a less efficient approach than the Enterprise approach below.

At the user device level, cache knowledge objects (i.e. aggregate unique IDs) and associated Merchant Profiles locally for quick retrieval.

This approach will require you to refresh Knowledge data on user devices regularly (e.g. every 72 hours), and also means that you will be storing more data on user devices than is technically relevant to them and may have periods where locally cached data is temporarily out of sync with the "true" data in the Knowledge Repository.

Enterprise

This approach is the ideal/recommended way to use data gathered from the Knowledge Repository at scale as it is the most efficient for your operations.

At the server level, collect and cache all unique Merchant Profiles (as well as periodically check for new Merchant Profiles) to be able to retrieve up-to-date information from the Knowledge Repository without having to perform additional calls to our API.

Please open a support ticket to and we will do our best to update it with the correct information as quickly as possible.

Each time you receive the transaction stream (see: and ), you extract the relevant Entity ID, Facilitator ID, and/or Location ID to then perform the subsequent API call(s) necessary to retrieve the relevant Merchant Profiles associated with the ID(s) (See: ).

View Enriched Data
help@synapsefi.com
View Transaction
Subscriptions
View Enriched Data