API Authentication and Credentials

All mCards APIs use a shared authentication model and consistent credential management approach. Before calling any mCards API, partners must understand how credentials are issued, how requests are authenticated, and how authentication differs from webhook security.

This guide describes the common credential and authentication concepts that apply across all mCards APIs.

API Credentials

mCards issues API credentials to identify and authenticate development partners.

Each partner is provided with:

An API key
An API secret

These credentials are used to authenticate API requests and associate activity with the correct partner entity.

API credentials are:

Issued per environment (sandbox and production)
Managed by mCards
Required for all API requests

Partners must protect API secrets and treat them as confidential.

Environments and Credentials

mCards provides separate credentials for each environment.

Sandbox (UAT) Credentials

Used for development and testing
Valid only in the sandbox environment
Required for transaction simulation and certification

Production Credentials

Used for live transaction processing
Issued only after certification approval
Valid only in the production environment

Sandbox and production credentials are not interchangeable. Requests authenticated with sandbox credentials will not be accepted in production, and vice versa.

API Authentication Model

All mCards APIs use HMAC-based request authentication.

HMAC authentication allows mCards to:

Verify the identity of the calling partner
Ensure request integrity
Prevent request tampering

Each API request must include authentication information that allows mCards to validate the request signature.

High-Level HMAC Flow

At a conceptual level, API authentication works as follows:

The partner constructs an API request
The request payload is signed using the partner’s API secret
Authentication information is included in the request headers
mCards validates the signature using the partner’s credentials
If validation succeeds, the request is processed

If authentication fails, the request is rejected.

What Is Signed

The HMAC signature is generated from components of the API request, such as:

Request payload
Request metadata (for example, timestamp or identifier)

The exact signing algorithm and header format are defined in the API reference documentation.

Partners must follow the signing rules precisely to ensure successful authentication.

Authentication Headers

Authenticated API requests include specific HTTP headers that convey authentication information.

These headers typically include:

The API key identifying the partner
The HMAC signature
Additional metadata required for verification

The exact header names and formats are consistent across APIs and are documented in the API reference.

Authentication Failures

Authentication failures may occur for reasons such as:

Invalid API key
Incorrect signature generation
Mismatched request payload
Expired or malformed authentication metadata

When authentication fails, mCards rejects the request and returns an error response.

Partners should ensure:

Signatures are generated using the correct secret
Requests are not modified after signing
Credentials correspond to the correct environment

API Authentication vs Webhook Security

API authentication and webhook security serve different purposes and use different mechanisms.

API Authentication

Used for partner-to-mCards API calls
Uses HMAC signatures generated with API credentials
Authenticates and authorizes API requests

Webhook Security

Used for mCards-to-partner event notifications
Uses webhook-specific secrets
Ensures webhook authenticity and integrity

Webhook security is described separately in the Webhooks API Concepts guide.

Partners should not reuse API credentials for webhook verification or vice versa.

Credential Management Responsibilities

Partner Responsibilities

Partners are responsible for:

Safely storing API secrets
Preventing unauthorized access to credentials
Rotating credentials if compromise is suspected
Using the correct credentials per environment

mCards Responsibilities

mCards is responsible for:

Issuing and managing API credentials
Validating authenticated requests
Associating API activity with the correct partner

Related Guides

Platform Concepts
Overview of transaction processing and authorization.
Webhooks API Concepts
Webhook delivery, event types, and webhook-specific security.
Payments API Concepts
Payment gateway integration and authorization participation.
Currency API Concepts
Alternative currencies and balance management.

Next step

Continue to Webhooks API Concepts to understand how mCards delivers events to partners and how webhook notifications are secured.