Distributor API Concepts

The Distributor 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 Distributor API.

Domain Model Overview

The Distributor API is organized around a hierarchy of entities:

Business
  └── Distributor
        ├── 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

A distributor represents an entity that distributes cards to cardholders. Distributors belong to a business and manage one or more card programs.

A distributor is not the same as a marketer. A marketer is a separate, upstream entity in the feature‑syndication model: features are syndicated to a marketer, the marketer distributes them to its distributors, and the distributor then assigns those features to its cards. See Feature Syndication for the full model and the Marketer API Concepts for the marketer's own API.

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
Enable or disable a cardholder's card (card status)

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 Distributor 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

Issuing and Sending Cards

The Distributor API offers two ways to get a card into a cardholder's hands, and the difference is who provides the cardholder's information and when identity verification happens.

Issue a Card

Issuing a card accepts the full cardholder PII (name, phone, date of birth, address, email) and runs identity verification (OFAC/PEP, Registered Address, Prove) followed by card issuance. It bypasses the SMS campaign and mobile‑app onboarding flow. Use this when you already hold the cardholder's verified details and want the card created immediately.

The call is half synchronous, half asynchronous. Identity verification runs inline and its per‑check results are in the response, but issuer provisioning takes longer: the endpoint returns 201 as soon as the checks are done and a card record exists in the pending state. A 201 is not a guarantee that the card was provisioned or is usable. The rest of the progress — active, issued, issuer_error or link_failed — arrives as card_status webhook deliveries, so subscribe to that event before you start issuing.

Send a Card

Sending a card is a shortcut that creates a default campaign and sends a card to a single recipient. The recipient then self‑onboards — completing their own details through the campaign/app flow. Use this when you only have minimal contact information and want the cardholder to finish onboarding themselves.

	Issue a Card	Send a Card
Cardholder PII	Supplied by you, up front	Provided by the recipient during onboarding
Identity verification	Runs immediately, before issuance	Runs as part of the recipient's onboarding
Onboarding flow	Bypassed	SMS smart link and/or emailed claim link + mobile app
Issuance outcome	`201` plus `card_status` webhook deliveries	Follows the recipient's onboarding
Use when	You already have verified cardholder data	The recipient should self‑onboard

Reaching the recipient by phone, email or both

send_card needs at least one of phone and email; delivery_method is optional and is inferred from whichever you supply.

You send	What happens	`campaign_item.status`
`phone` only	The existing SMS smart link is sent	`pending` until the recipient onboards
`phone` and `email`	SMS smart link plus an email copy of the same link	`pending`
`email` only	A claim‑first invite: the recipient is emailed a hosted claim link, enters their phone there, and only then joins the normal SMS/onboarding flow. No funds move until the claim	`awaiting_claim`, then `pending`; `expired` if never claimed

The 201 response also carries a channels object — sms and email are each queued or skipped, with an optional reason. queued means the message was handed to the delivery pipeline, not that it was delivered.

Email delivery is a per‑card capability that mCards enables on request. When it is off, an email‑only request is rejected with 422 on the email field, and a phone‑and‑email request still goes out by SMS with channels.email = skipped and reason = email_invites_disabled.

Email‑only invites have a lifecycle of their own:

Repeating a send_card for the same email while an invite is still awaiting claim resends the invite with a fresh link rather than creating a duplicate; resends within 24 hours are skipped (reason = resend_throttled).
The claim link expires after the card's claim window (30 days by default). status becomes expired immediately; claim_status follows on the next hourly lifecycle sweep, so the pair expired / awaiting_claim can appear briefly.
An unclaimed invite can be voided with DELETE .../send_card/{campaign_item_uuid}, which stops the claim link working. Voiding is idempotent; a claimed or funded item answers 409.
claim_status, claim_expires_at and claimed_at on the campaign item track this; they are null for phone sends.

An optional originator_identifier on the request is stored with the campaign item and echoed on card_status webhook events for the resulting card, so you can correlate issuance outcomes with your own records.

Charges, Recurring Charges, and Round-Ups

The Distributor API includes endpoints for moving value on cardholder cards:

Charges — one‑time charges against a cardholder card.
Recurring Charges — scheduled charges that repeat, with full lifecycle management (create, read, update, delete).
Round‑Ups — configure round‑up behavior on a cardholder card (per‑card configurations and settings) and read the resulting round‑up events.

Feature Syndication

Distributors receive features that a marketer has syndicated to them, and then assign those features to their distributor cards (optionally bundling a feature with a specific card). The Distributor API exposes the distributor side of this flow — reading the feature distribution and managing card‑level assignment. For the complete model across marketer and distributor, see Feature Syndication.

QR Code Landing Page

The Distributor API lets you manage a QR code landing page for a card program — reading and updating the landing page and retrieving its QR code image — so cardholders can be directed to a program‑specific destination.

Dashboard and Analytics

The Distributor 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 Distributor 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. How those features arrive at a distributor is described in Feature Syndication.

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 Distributor 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

API Authentication and Credentials — How to authenticate API requests
API Scoping and Permissions — How data is scoped to your partner account
Feature Syndication — How features flow from a marketer to a distributor's cards
Webhook API Concepts — The card_status event that reports card lifecycle progress
Distributor API Reference — Full endpoint documentation