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 mCards 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 five API libraries, each serving a distinct purpose:

API	Purpose
Distributors API	Manage distributors, locations, terminals, cardholders, campaigns, and view dashboard analytics
Cards 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
Webhooks API	Subscribe to real-time event notifications for transactions, payments, offers, and locations

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	Distributors API, Webhooks API	Platform Concepts, Authentication, Distributors Concepts
Card-Level Data Access — View card details, transactions, and payment accounts for specific cards	Cards API	Platform Concepts, Authentication, Cards Concepts
Loyalty & Alternative Currencies — Create loyalty points, rewards, or other currencies that cardholders earn and spend	Currency API, Webhooks API	Currency Concepts, Platform Concepts, Authentication
Payment Gateway Integration — Integrate a payment platform for real-time transaction authorization	Payment API, Webhooks API	Payments Concepts, Webhooks Concepts, Payments User Token, Authentication
Real-Time Event Handling — Receive notifications for transactions, payments, offers, and location events	Webhooks API	Webhooks 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 mCards 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

For a GET request, sign the JSON-serialized null payload:

PAYLOAD="null"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$MCARDS_API_SECRET" | awk '{print $NF}')

Step 3: Make the Request

Call the Distributors API to list your distributors:

curl -X GET "${MCARDS_BASE_URL}/api/distributors/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
Webhooks API Concepts — Set up real-time event handling