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.

Purpose

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:

Securely identifying the cardholder to the payment gateway
Establishing trust between the mCards platform and the payment gateway
Launching a payment gateway-hosted onboarding web application

When the Token Is Issued

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

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 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

What the Token Represents

The Payments User Token represents:

Represents	Does NOT Represent
A specific cardholder	API authentication credentials
A specific payment gateway onboarding session	Authorization to process transactions
A trusted request from the mCards platform	Permission to approve or decline transactions

Transaction authorization occurs later through webhooks and the Payments API, not through this token.

Token Structure

The Payments User Token is a signed JWT with claims describing the onboarding context:

Claim	Description
`iss`	Identifies mCards as the issuing platform
`aud`	Identifies the payment gateway provider (configured per gateway, or defaults to the payments API base URL)
`iat`	Token issue time (Unix timestamp)
`exp`	Token expiration — 5 minutes after issue
`consumer_id`	The cardholder's UUID
`phone_number`	The cardholder's phone number
`cardholder_card.cardholder_card_uuid`	UUID of the cardholder's card
`distributor_card.distributor_card_uuid`	UUID of the card program

Depending on the payment gateway configuration, additional optional claims may be included:

Optional Claim	Included When
`full_name`, `first_name`, `last_name`	Gateway is configured to include cardholder name
`email`	Gateway is configured to include cardholder email
`date_of_birth`	Gateway is configured to include date of birth
`address`	Gateway is configured to include cardholder address
`location`	Gateway is configured to include location data

Sample Payload

{
  "consumer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phone_number": "+15551234567",
  "cardholder_card": {
    "cardholder_card_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  },
  "distributor_card": {
    "distributor_card_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  },
  "full_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "exp": 1716000600,
  "iss": "mcards",
  "iat": 1716000300,
  "aud": "your-payment-gateway-identifier"
}

Note: Optional claims (full_name, email, etc.) appear only when the payment gateway is configured to include them. Your token may contain a subset of these fields.

Token Validation

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

Verify the token signature using public keys from the mCards JWKS endpoint
Confirm the issuer matches mCards
Check expiration to ensure the token has not expired
Verify the audience matches the payment gateway provider

Relationship to the Payments API

The Payments User Token is used only for onboarding. After onboarding:

The payment gateway uses the Payments API to manage payment accounts
The payment gateway receives webhook events during transaction authorization
API calls use HMAC authentication, not the Payments User Token

The token and the API serve different purposes in the payment gateway lifecycle:

Phase	Mechanism
Onboarding	Payments User Token (embedded web app)
Account management	Payments API with HMAC authentication
Authorization decisioning	Webhook events from mCards

Trust Boundaries

mCards Responsibilities

Issue Payments User Tokens at the correct point in the onboarding flow
Sign tokens using platform-controlled private keys
Publish public keys for token verification

Payment Gateway Provider Responsibilities

Validate the Payments User Token before using it
Reject requests with invalid, expired, or improperly scoped tokens
Protect cardholder data obtained during onboarding
Use the token only within the onboarding session

Common Mistakes to Avoid

Treating the Payments User Token as an API credential
Reusing the token outside the onboarding session
Skipping token signature validation
Ignoring token expiration
Using the token to authorize transactions (use webhooks instead)

Related Guides

Embedded Partner Web Applications — The onboarding pattern this token supports
Feature SSO Token — The token used for feature onboarding
Payments API Concepts — Payment gateway integration and authorization
Webhooks API Concepts — Event delivery during authorization