Guides

Distributors API Concepts

Understand the core concepts behind the Distributors API — distributors, locations, terminals, cardholders, campaigns, and analytics.

Distributors API Concepts

The Distributors API is the primary API for partners who distribute mCards-issued cards. It provides endpoints for managing distributors, locations, terminals, cardholders, campaigns, and viewing analytics dashboards.

This guide describes the domain model and key concepts you need to understand before working with the Distributors API.

Domain Model Overview

The Distributors API is organized around a hierarchy of entities:

Business
  └── Distributor (Marketer)
        ├── Distributor Cards (Card Programs)
        │     └── Cardholders
        │           └── Cards
        │                 └── Transactions
        ├── Locations
        │     └── Terminals
        └── Campaigns

Your API access is scoped to the businesses and distributors assigned to your partner account. See API Scoping and Permissions for details.

Core Entities

Businesses

A business is the top-level organizational entity. Businesses own distributors and are the administrative container for card programs.

Distributors (Marketers)

A distributor (also referred to as a "marketer" in some API responses) represents an entity that distributes cards to cardholders. Distributors belong to a business and manage one or more card programs.

Distributor Cards (Card Programs)

A distributor card represents a card program — the template from which individual cardholder cards are issued. Distributor cards define:

  • Card branding and styling (card art, splash screens, mCash icons)
  • Program configuration
  • Associated features and offers

Cardholders

A cardholder is an individual who holds one or more cards issued under a distributor's card program. The API allows you to:

  • List and search cardholders within your scope
  • View cardholder details
  • Access cards and transactions associated with a cardholder

Locations

A location represents a physical place where card transactions occur. Locations are associated with terminals and provide geographic context for transaction data.

Terminals

A terminal is a point-of-sale device at a location where card transactions are processed. Terminals are identified by their terminal ID and are linked to locations.

Campaigns

Campaigns are a key feature of the Distributors API. A campaign represents a card balance transfer campaign — a mechanism for distributing funds or value to cardholder cards.

The API provides endpoints to:

  • List campaigns associated with your distributors
  • View campaign details and status
  • Access campaign analytics

Dashboard and Analytics

The Distributors API provides comprehensive analytics endpoints for monitoring card program performance:

Dashboard Stats

  • Overview statistics — High-level metrics across your card programs
  • Transaction summaries — Aggregated transaction data by time period
  • Recent activity — Latest transactions and events
  • Top locations — Locations with the highest transaction volume
  • Distribution metrics — Card distribution and activation statistics

Distributor Card Stats

  • Cardholder growth — Growth trends for cardholders over time
  • Spend categories — Transaction breakdown by merchant category

Stats Overview

  • Library-wide statistics across all distributor cards in your scope

These endpoints power partner dashboards and reporting.

Feature Catalog

The Distributors API exposes a feature catalog that lists available features for distributor cards. Features represent add-on capabilities (e.g., loyalty programs, payment integrations) that can be enabled on a card program.

Merchant Categories

The API provides access to merchant category data, which classifies merchants into categories (e.g., restaurants, retail, travel). This data is used for transaction categorization and spend analytics.

Key Patterns

UUID-Based Identification

All entities in the Distributors API are identified by UUIDs (not numeric IDs). When referencing a distributor, cardholder, location, or other entity, use the uuid field from API responses.

Pagination

List endpoints support pagination through query parameters. Large result sets are paginated to ensure consistent performance.

Search and Filtering

Many list endpoints support search and filtering parameters to narrow results by specific criteria (e.g., filtering cardholders by name, filtering transactions by date range).

Related Guides

Updated 2 days ago