Guides
Start typing to search…

Platform Integration Concepts

The mCards platform provides a set of 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 the Webhooks, Payments, and Currency APIs.

Actors in the Transaction Lifecycle

A card transaction involves multiple actors, each with a defined role in the lifecycle of a transaction.

The primary actors are:

  • Cardholder
    The consumer initiating a transaction using an mCards-issued card.

  • Merchant
    The business where the transaction occurs.

  • Acquirer / Processor
    The financial institution or processor that routes transactions from the merchant to the card network.

  • Card Network
    The card network (for example, Mastercard or Visa) that delivers transaction messages between the acquirer and the issuer.

  • mCards Platform
    Acts as the issuer processor and is responsible for authorization decisioning and transaction processing.

  • Payment Gateway Provider
    An external partner that may participate in authorization decisioning for payment accounts created using the Payments API.

  • Currency Provider
    An external partner that manages balances for alternative currencies created using the Currency API.

Understanding how these actors interact provides the foundation for all API integrations.

Transaction Processing on the mCards Platform

All card transactions require an approval decision from the mCards platform in order to be successfully processed.

When a transaction occurs:

  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 it should be approved or declined
  5. An approval or decline response is returned through the card network

mCards is responsible for applying platform rules and partner integrations during this evaluation.

Single-Message vs Dual-Message Transactions

mCards supports both single-message and dual-message transaction models.

Dual-Message Transactions

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.

Dual-message transactions are common for use cases where the final transaction amount may change.

Single-Message Transactions

Single-message transactions combine authorization and completion into a single message.

  • Approval and completion occur at the same time
  • No separate completion message is sent

Single-message transactions are common for low-risk or fixed-amount purchases.

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

Dynamic Processing Engine (DPE)

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

For each transaction, the DPE:

  • Evaluates available payment accounts for the cardholder
  • Processes payment accounts in rank order
  • Applies decisioning logic for each account
  • Determines whether the transaction can be approved

If a payment account cannot support the transaction, the DPE moves to the next account in the ranking.

Platform Financial Constructs

mCards exposes several financial constructs through its APIs. These constructs determine how transactions are funded and approved.

Payment Gateways

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

Key characteristics:

  • 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 a payment gateway declines a transaction, the DPE evaluates the next available payment account.

Currency Providers

A currency provider represents an external partner managing an alternative currency using the Currency API.

Key characteristics:

  • Currency providers create balances associated with cardholders
  • Currency balances may be payment or non-payment types
  • For payment-type currencies:
    • mCards evaluates the available balance directly
    • The currency provider does not participate in real-time authorization
  • Approval is based on balance sufficiency

Currency providers supply balance data, but mCards is responsible for authorization decisions.

Operations Accounts

Payment gateways and currency providers are associated with operations accounts on the mCards platform.

Operations accounts are used to:

  • Support settlement and funds movement
  • Maintain platform-level financial integrity
  • Associate API activity with a partner entity

Operations accounts are managed by mCards and exposed through API endpoints for visibility.

Embedded Partner Web Applications

Some integrations require direct cardholder interaction.

In these cases, mCards launches partner-hosted onboarding web applications from within the mCards mobile app.

This pattern is used for:

  • Feature onboarding
  • Payment gateway onboarding

Embedded partner web applications are described in detail in the Partner Integration Concepts section.

User-Context Tokens

When launching embedded partner onboarding applications, mCards provides user-context tokens that allow partners to identify the cardholder and trust the request.

Two token types exist:

  • Feature SSO Token
  • Payments User Token

These tokens are used only for onboarding and are not API authentication credentials.

Environments: Sandbox (UAT) and Production

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 the sandbox environment before moving to production.

Simulating Transactions

In the sandbox environment, mCards provides transaction simulation capabilities.

Simulation allows partners to:

  • Trigger single-message transactions
  • Trigger dual-message transactions
  • Validate webhook handling
  • Test authorization decisioning logic

Simulation is required to verify integrations before certification.

Certification and Promotion to Production

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

The certification process includes:

  • Functional validation
  • Security review
  • Verification of webhook handling
  • Confirmation of correct authorization behavior

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

Related Guides

  • Webhooks API Concepts
    Event delivery and webhook security.

  • Payments API Concepts
    Payment gateway integration and authorization participation.

  • Currency API Concepts
    Alternative currencies and balance-based decisioning.

Next step

Continue to Common API Concepts to understand authentication, credentials, and reliability patterns shared across all mCards APIs.

Updated about 2 months ago