Payments User Token

The Payments User Token is used by payment gateway providers to onboard cardholders when a payment method is added from within the mCards mobile app. It allows the mCards platform to securely pass cardholder context to a payment gateway’s embedded onboarding web application.

This guide is the authoritative reference for the Payments User Token and describes when it is issued, how it is delivered, what it represents, and how payment gateway providers are expected to validate and use it.

Purpose of the Payments User Token

When a cardholder adds a payment method, mCards must allow a payment gateway provider to onboard the cardholder and create one or more payment accounts that can participate in transaction processing.

The Payments User Token enables this by allowing mCards to:

Securely identify the cardholder to the payment gateway
Establish trust between the mCards platform and the payment gateway
Launch a payment gateway–hosted onboarding web application

The token is used only for payment gateway onboarding and does not grant API access.

When the Payments User Token Is Issued

The Payments User Token is issued during payment gateway onboarding flows.

At a high level:

A cardholder initiates the “add payment method” flow in the mCards mobile app
The mobile app launches the payment gateway’s onboarding web application
mCards includes the Payments User Token with the onboarding request
The payment gateway validates the token
The payment gateway onboards the cardholder and creates payment accounts

Once onboarding is complete, payment accounts created by the gateway may be used during transaction authorization and processing.

How the Token Is Delivered

The Payments User Token is delivered to the payment gateway’s onboarding web application as part of the initial request.

The token is included in the Authorization header as a Bearer token
The token is a JSON Web Token (JWT)
The token is intended for immediate validation and use

The token is used only within the context of the embedded onboarding session.

What the Payments User Token Represents

Conceptually, the Payments User Token represents:

A specific cardholder
A specific payment gateway onboarding session
A trusted request initiated by the mCards platform

The token does not represent:

API authentication credentials
Authorization to process transactions
Permission to approve or decline transactions

Transaction authorization occurs later through webhooks and the Payments API.

Token Structure (Conceptual)

The Payments User Token is a signed JWT that includes claims describing the onboarding context.

At a conceptual level, the token includes:

Issuer
Identifies mCards as the issuing platform
Audience
Identifies the payment gateway provider
Expiration
Enforces short token lifetime
Cardholder context
Identifiers required to associate onboarding with a cardholder

Payment gateways should treat the token as opaque beyond the claims required to complete onboarding.

Token Validation

Payment gateway providers must validate the Payments User Token before using it.

At a minimum, validation includes:

Verifying the token signature
Confirming the token was issued by mCards
Ensuring the token has not expired
Ensuring the token audience matches the payment gateway

Signature Verification

Tokens are digitally signed by mCards
Payment gateways validate the signature using public keys published by mCards
Public keys are retrieved from the mCards JSON Web Key Set (JWKS) endpoint

Successful validation establishes trust between the payment gateway onboarding application and the mCards platform.

Relationship to Embedded Partner Web Applications

The Payments User Token is an implementation of the Embedded Partner Web Application pattern.

The embedded web application provides the onboarding experience
The Payments User Token provides secure cardholder context

This pattern is shared with feature onboarding but uses a different token scoped specifically to payment gateway onboarding.

Relationship to the Payments API

The Payments User Token is used only during onboarding.

After onboarding:

Payment gateways interact with mCards using the Payments API
API authentication uses standard mCards API credentials
The Payments User Token is no longer used

The token does not replace API authentication and must not be used in backend API requests.

Relationship to Webhooks and Authorization

Payment accounts created during onboarding may participate in transaction authorization.

During transaction processing:

mCards sends payment account webhooks to the payment gateway
The payment gateway participates in authorization decisioning
Authorization decisions are communicated via webhook responses

The Payments User Token plays no role in authorization or transaction processing beyond onboarding.

Trust Boundaries and Responsibilities

mCards Responsibilities

Issue Payments User Tokens during payment gateway onboarding
Sign tokens using platform-controlled private keys
Publish public keys for token verification

Payment Gateway Responsibilities

Validate the Payments User Token before onboarding
Reject invalid or expired tokens
Secure the onboarding web application
Create and manage payment accounts using the Payments API

mCards does not manage payment gateway onboarding logic, and payment gateways do not have access to mCards mobile app internals.

Common Implementation Mistakes

Payment gateway providers should avoid the following mistakes:

Treating the Payments User Token as an API credential
Attempting to reuse the token after onboarding
Skipping signature validation
Assuming the token authorizes transactions
Using the token across environments

Related Guides

Embedded Partner Web Applications
Overview of the embedded onboarding pattern.
Tokens for Embedded Web Applications
Shared properties of user-context tokens.
Feature SSO Token
Token used for feature onboarding.
Payments API Concepts
Describes payment account creation, authorization, and processing.

Next step

With Partner Integration Concepts complete, continue to Platform Concepts under API Integration Concepts to understand transaction processing and authorization on the mCards platform.