Platform Integration Concepts

The mCards platform provides APIs that enable partners to participate in card transaction processing, authorization decisioning, and balance management. Understanding how the platform processes transactions and how partners fit into that flow is essential before integrating with any mCards API.

This guide describes the core platform concepts that apply across all five API libraries.

Actors in the Transaction Lifecycle

A card transaction involves multiple actors, each with a defined role:

Transaction Processing

All card transactions require an approval decision from the mCards platform.

Transaction Flow

1. The merchant submits the transaction to the acquirer
2. The transaction is routed through the card network
3. The card network delivers the transaction message to mCards
4. mCards evaluates the transaction and determines whether to approve or decline
5. The approval or decline response is returned through the card network

Authorization Sequence (Dual-Message with Payment Gateway)

The following diagram shows the full authorization flow for a dual-message transaction involving a payment gateway partner:

Cardholder       Merchant       Card Network       mCards (DPE)       Payment Gateway
    │                │                │                  │                    │
    │── Tap card ───>│                │                  │                    │
    │                │── Auth req ───>│                  │                    │
    │                │                │── Auth msg ──────>│                    │
    │                │                │                  │                    │
    │                │                │                  │── payment.hold ───>│
    │                │                │                  │                    │
    │                │                │                  │<── approve/decline ─│
    │                │                │                  │                    │
    │                │                │<── Approve/Decline│                    │
    │                │<── Response ───│                  │                    │
    │<── Receipt ────│                │                  │                    │
    │                │                │                  │                    │
    │                │                │                  │── transaction       │
    │                │                │                  │   webhook ─────────>│
    │                │                │                  │   (to subscribers)  │

Key points:

• The payment gateway receives a payment.hold webhook and must respond synchronously with an approve or decline decision
• After the authorization decision, mCards delivers a transaction webhook to all subscribed partners (asynchronously)
• For payment currency accounts, the DPE checks balances directly — no webhook is sent to the currency provider during authorization

Single-Message vs Dual-Message Transactions

mCards supports both transaction models:

Dual-message transactions consist of two distinct messages:

• Authorization — Determines whether the transaction is approved and places a hold on funds
• Completion — Finalizes the transaction and moves funds

Single-message transactions combine authorization and completion into a single message. Approval and fund movement occur simultaneously.

In both models, mCards must approve the transaction for it to succeed.

Dynamic Processing Engine (DPE)

The Dynamic Processing Engine (DPE) is the component responsible for authorization decisioning.

For each transaction, the DPE:

1. Evaluates available payment accounts for the cardholder
2. Processes payment accounts in rank order (lowest rank number = highest priority)
3. Applies decisioning logic for each account type
4. Determines whether the transaction can be approved

If a payment account cannot support the transaction (e.g., insufficient balance, gateway decline), the DPE moves to the next account in the ranking.

Rank Order Evaluation

Each cardholder card may have multiple payment accounts — from different payment gateways and/or currency providers. The DPE evaluates these in a configured rank order:

Rank 1: Partner A Payment Gateway  →  Approved?  →  Done
                                       ↓ Declined
Rank 2: Loyalty Points (Currency)  →  Sufficient balance?  →  Done
                                       ↓ Insufficient
Rank 3: Partner B Payment Gateway  →  Approved?  →  Done
                                       ↓ Declined
        → Transaction Declined

• Payment gateway accounts — The DPE sends a real-time webhook to the partner; the partner responds with approve or decline
• Payment currency accounts — The DPE checks the available balance directly; no webhook is sent to the currency provider

The rank order is configured per distributor card (card program) and determines the priority in which payment sources are attempted.

Syndication

Payment gateways and currencies are linked to distributor cards (card programs) through syndication. Syndication determines:

• Which card programs can use a given payment gateway or currency
• Which cardholders have access to each payment source (based on their card program)
• The rank order of payment accounts within each card program

A payment gateway may be syndicated to multiple distributor cards, meaning cardholders across different card programs can all use that gateway. Conversely, a single card program may have multiple syndicated payment sources evaluated in rank order.

Platform Financial Constructs

Payment Gateways

A payment gateway represents an external payment platform integrated via the Payments API.

• Payment gateways create payment accounts for cardholders
• Payment gateways actively participate in authorization decisioning
• During authorization, mCards sends webhook events to the payment gateway
• The payment gateway responds with approval or decline decisions
• If declined, the DPE evaluates the next available payment account

Currencies

A currency represents an alternative balance (loyalty points, rewards) managed via the Currency API.

• Currency providers create balances associated with cardholders
• Currencies may be payment or non-payment types:
  • Payment currencies — mCards evaluates the balance during authorization; the provider does not participate in real-time decisioning
  • Non-payment currencies — Balances exist for tracking but do not affect transaction authorization
• For payment currencies, approval is based on balance sufficiency

Operations Accounts

Payment gateways and currency providers are associated with operations accounts on the mCards platform. These accounts support settlement, funds movement, and platform-level financial integrity.

Embedded Partner Web Applications

Some integrations require direct cardholder interaction — such as enrolling in a payment gateway or activating a feature. In these cases, mCards launches partner-hosted onboarding web applications from within the mCards mobile app, passing a signed JWT token to securely identify the cardholder.

For the full onboarding flow, token delivery mechanism, and UX guidance, see Partner Onboarding UX Patterns. For token structure and sample payloads, see Feature SSO Token and Payments User Token.

Environments

mCards provides two environments for API integrations:

Sandbox (UAT)

• Used for development and testing
• Does not process real-world transactions
• Provides tools for simulating transaction flows
• Required starting point for all partners

Production

• Processes real transactions
• Requires certification approval
• Uses production credentials issued by mCards

Partners must complete development and testing in sandbox before moving to production.

Simulating Transactions

In the sandbox environment, mCards provides a transaction simulation API that allows partners to trigger test transactions against cardholder cards. This is essential for validating your integration end-to-end without processing real-world transactions.

Simulation Endpoint

POST /api/free_money/transactions/simulate

Required Parameters

Optional Parameters

Example Request

PAYLOAD='{"card_uuid":"a1b2c3d4-...","amount":"25.00","merchant_id":"MERCHANT001","merchant_trade_name":"Test Coffee Shop","mcc":"5814"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$MCARDS_API_SECRET" | awk '{print $NF}')

curl -X POST "${MCARDS_BASE_URL}/api/free_money/transactions/simulate" \
  -H "Authorization: HMAC_256 ${MCARDS_API_KEY};${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

What Happens During Simulation

When you simulate a transaction, the platform processes it through the full authorization flow:

1. The DPE evaluates payment accounts in rank order
2. Payment gateway partners receive payment.hold webhooks (if applicable)
3. Currency balances are evaluated (if applicable)
4. Transaction webhooks are delivered to subscribed partners
5. The transaction appears in card transaction history

This allows you to validate:

• Webhook handling — Verify your server correctly receives and processes webhook events
• Authorization logic — Test your payment gateway's approve/decline responses
• Balance management — Confirm currency balances update correctly
• End-to-end flow — Verify the complete integration from transaction to webhook to response

Simulation is required to complete the mCards certification process before accessing production credentials.

Certification and Promotion to Production

Before accessing production credentials, partners must complete the mCards certification process:

1. Functional validation — Verify that the integration handles all expected transaction scenarios
2. Security review — Confirm secure handling of credentials, tokens, and webhook payloads
3. Webhook verification — Validate correct handling of all subscribed event types
4. Authorization behavior — Confirm correct approval/decline logic (for payment gateway integrations)

Once certification is complete, mCards provides production credentials and the partner promotes their integration to production.

Related Guides

• API Authentication and Credentials — HMAC request signing
• API Scoping and Permissions — Data scoping for your partner account
• Webhooks API Concepts — Event delivery and webhook security
• Payments API Concepts — Payment gateway integration
• Currency API Concepts — Alternative currencies and balance management