Welcome to mCards

The mCards platform provides APIs and services for card issuance, transaction processing, authorization decisioning, and offer management. As a development partner, you integrate with one or more mCard APIs to build solutions for card distribution, payments, loyalty currencies, and real-time event handling.

This guide helps you understand what is available, identify which APIs you need, and get started with your integration.

Platform Overview

The mCards platform centers around issued cards and the cardholders who use them. Partners interact with the platform through eight API libraries, each serving a distinct purpose:

API	Purpose
Distributor API	Manage distributors, locations, terminals, cardholders, campaigns, charges, round-ups, and view dashboard analytics
Card API	Access card-level data including cardholder cards, transactions, and payment accounts
Currency API	Create and manage alternative currencies (loyalty points, rewards) with balance tracking
Payment API	Integrate payment gateways that participate in real-time transaction authorization
Webhook API	Subscribe to real-time event notifications for transactions, card lifecycle changes, payments, offers, and locations
Marketer API	Manage how features are distributed and syndicated to distributors
Sandbox API	Simulate card transactions and location events in non-production environments
Accounting API	Read and manage accounts (ledger positions), balances, and transactions

All APIs share a common authentication model (HMAC-based request signing) and are available in both sandbox and production environments.

What Do You Want to Build?

Use this matrix to identify which APIs and concepts are relevant to your integration.

Integration Type	APIs You Need	Key Concepts
Card Distribution & Management — Distribute cards, manage cardholders, track campaigns, view analytics	Distributor API, Webhook API	Platform Concepts, Authentication, Distributors Concepts
Card-Level Data Access — View card details, transactions, and payment accounts for specific cards	Card API	Platform Concepts, Authentication, Cards Concepts
Loyalty & Alternative Currencies — Create loyalty points, rewards, or other currencies that cardholders earn and spend	Currency API, Webhook API	Currency Concepts, Platform Concepts, Authentication
Payment Gateway Integration — Integrate a payment platform for real-time transaction authorization	Payment API, Webhook API	Payments Concepts, Webhooks Concepts, Payments User Token, Authentication
Real-Time Event Handling — Receive notifications for transactions, card lifecycle changes, payments, offers, and location events	Webhook API	Webhooks Concepts, Authentication
Feature Distribution & Syndication — Distribute features to distributors and assign them to cards	Marketer API, Distributor API	Feature Syndication, Marketer Concepts, Distributor Concepts
Testing & Simulation — Simulate authorizations, completions, and location events, and exercise webhooks	Sandbox API, Webhook API	Sandbox Concepts, Webhooks Concepts
Accounts & Ledger — Create and read accounts, balances, and transactions	Accounting API	Accounting Concepts, Authentication

Quick Start Checklist

Follow these steps to go from zero to your first API call.

1. Get Your Credentials

Contact your mCards partner manager to receive:

API key — Identifies your partner account
API secret — Used to sign API requests via HMAC
Sandbox environment access — All development starts in sandbox

You will receive separate credentials for sandbox (UAT) and production.

2. Understand Authentication

All mCard APIs use HMAC-SHA256 request signing. Before making any API call, read API Authentication and Credentials to understand:

How to construct the HMAC signature
Which headers to include
How authentication differs from webhook security

3. Read the Relevant Concepts

Based on the integration you are building (see the matrix above), read the corresponding concept guides. These explain the platform model, transaction lifecycle, and how your integration fits into the overall system.

4. Explore the API Reference

Each API has a full reference with endpoint details, request/response schemas, and parameter descriptions:

5. Build and Test in Sandbox

The sandbox environment allows you to:

Make API calls without processing real transactions
Simulate card transactions to test your integration
Validate webhook handling and authorization logic

6. Certify and Go Live

Once your integration is working in sandbox:

Complete the mCards certification process (functional validation, security review, webhook verification)
Receive production credentials from your partner manager
Promote your integration to production

Your First API Call

Once you have your sandbox credentials, follow this walkthrough to make your first authenticated request.

Step 1: Prepare Your Credentials

Set your sandbox API key and secret as environment variables:

export MCARDS_API_KEY="your_sandbox_api_key"
export MCARDS_API_SECRET="your_sandbox_api_secret"

Step 2: Compute the HMAC Signature

A GET request has no body, so the signature is computed over the empty string:

PAYLOAD=""
SIGNATURE=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$MCARDS_API_SECRET" | awk '{print $NF}')

Requests with a body sign the exact raw JSON string being sent instead.

Step 3: Make the Request

Call the Distributor API to list your distributors:

curl -X GET "${MCARDS_BASE_URL}/api/distributor/v1/distributors" \
  -H "Authorization: HMAC_256 ${MCARDS_API_KEY};${SIGNATURE}" \
  -H "Content-Type: application/json"

Step 4: Review the Response

A successful response returns your scoped distributors with pagination:

{
  "distributors": [
    {
      "uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "name": "Example Distributor",
      "status": "active"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 1
  }
}

If you receive a 401 Unauthorized error, check your API key and signature — see the Authentication Troubleshooting section.

Next Steps

API Authentication and Credentials — Learn how to sign API requests
Pagination and Rate Limits — Understand pagination and rate limiting
Platform Integration Concepts — Understand the transaction lifecycle
Webhook API Concepts — Set up real-time event handling