Payments API Concepts

The Payments API enables payment gateway providers to integrate with the mCards platform and participate in card transaction processing. Through this integration, payment gateways create payment accounts for cardholders and actively participate in authorization decisioning using webhooks.

This guide describes the conceptual model for the Payments API and how payment gateways interact with the mCards platform during onboarding, authorization, and transaction processing.

What Is the Payments API?

The Payments API allows external payment gateway providers to integrate their payment platforms with mCards.

Using the Payments API, payment gateways can:

Create payment accounts for cardholders
Associate those accounts with issued mCards
Participate in transaction authorization decisioning
Receive transaction and account-related events via webhooks

Payment gateways are active participants in the authorization lifecycle.

Payment Accounts

A payment account represents a funding source managed by a payment gateway provider.

Key characteristics:

Payment accounts are created during payment gateway onboarding
Each payment account is associated with a cardholder
Payment accounts appear in the mCards app as available funding options
Payment accounts are evaluated by the Dynamic Processing Engine (DPE)

Payment accounts created through the Payments API differ from currency-based payment accounts, which are described separately.

Payment Gateway Onboarding

Before a payment gateway can participate in transaction processing, cardholders must be onboarded.

The onboarding flow includes:

A cardholder initiates the “add payment method” flow in the mCards mobile app
mCards launches the payment gateway’s embedded onboarding web application
mCards provides a Payments User Token
The payment gateway validates the token and onboards the cardholder
The payment gateway creates one or more payment accounts using the Payments API

Once onboarding is complete, payment accounts may be used during transaction authorization.

Role of the Dynamic Processing Engine (DPE)

The Dynamic Processing Engine (DPE) determines how transactions are evaluated and approved.

For each transaction:

The DPE evaluates payment accounts in rank order
Each payment account is considered independently
The DPE requests authorization decisions as required

If a payment account cannot support a transaction, the DPE moves on to the next available account.

Authorization Decisioning with Payment Gateways

Payment gateways participate in authorization decisioning through webhooks.

During authorization:

mCards receives an authorization request from the card network
The DPE identifies the next payment account to evaluate
mCards sends an authorization webhook to the payment gateway
The webhook requests an approve or decline decision
The payment gateway responds to the webhook
mCards uses the response to determine whether to approve the transaction or continue evaluation

In this model, payment gateways are responsible for real-time authorization decisions.

Payments API vs Currency API Decisioning

It is important to distinguish between payment gateway decisioning and currency-based decisioning.

Payments API Decisioning

Payment gateway is an active participant
Authorization decisions are made by the payment gateway
Decisions are communicated via webhooks
The DPE coordinates the evaluation sequence

Currency API Decisioning

Currency provider supplies balance information
mCards evaluates balance sufficiency directly
Currency providers do not participate in real-time authorization
Authorization decisions are made entirely by mCards

These two models coexist within the DPE and are evaluated consistently.

Payment Account Events

Payment gateways receive events related to payment accounts through webhooks.

Examples include:

Payment account creation
Payment account updates
Status changes

These events allow payment gateways to maintain synchronization with the mCards platform.

Relationship to Webhooks

Webhooks are a required component of Payments API integrations.

Payment gateways use webhooks to:

Receive authorization requests
Receive transaction completion events
Track payment account lifecycle events

Without webhooks, payment gateways cannot participate in authorization decisioning.

Relationship to API Authentication

Payment gateways authenticate API requests using standard mCards API credentials and HMAC-based authentication.

The Payments User Token is used only for onboarding and must not be used for API calls.

API authentication details are described in the API Authentication & Credentials guide.

Operations Accounts

Payment gateway providers are associated with operations accounts on the mCards platform.

Operations accounts are used to:

Support settlement and funds movement
Associate payment activity with the gateway provider
Maintain platform-level financial integrity

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

Environments and Testing

Payment gateway integrations must be developed and tested in the sandbox environment.

In sandbox:

No real transactions are processed
Transaction flows can be simulated
Webhook handling and authorization logic can be validated

Certification is required before promotion to production.

Related Guides

Platform Concepts
Transaction processing and the Dynamic Processing Engine.
Webhooks API Concepts
Event delivery and authorization webhooks.
API Authentication & Credentials
Authenticating Payments API requests.
Payments User Token
Token used during payment gateway onboarding.
Currency API Concepts
Balance-based payment accounts and alternative currencies.

Next step

Continue to Currency API Concepts to understand how alternative currencies and balance-based payment accounts are integrated with the mCards platform.