Partner Onboarding UX Patterns

When a partner integration requires direct cardholder interaction — such as enrolling in a payment gateway or activating a feature — mCards launches the partner's web application inside the mCards mobile app. This page describes the UX patterns that govern how these embedded experiences are initiated, authenticated, and completed.

---

Embedded Web Application Pattern

All partner onboarding flows follow the same general pattern:

1. The cardholder initiates an action in the mCards mobile app (e.g., taps "Activate" on a feature or selects a payment gateway)
2. The mCards app opens an embedded webview pointing to the partner's onboarding URL
3. mCards passes a signed JWT token to the partner application via the Authorization header as a Bearer token
4. The partner validates the token, identifies the cardholder from its claims, and presents the onboarding experience
5. Upon completion, the partner signals success and the webview closes, returning the cardholder to the mCards app

This pattern ensures the cardholder never leaves the mCards app while interacting with partner services, and the partner receives verified cardholder context without requiring a separate login.

---

Feature Onboarding Flow

Feature onboarding allows cardholders to discover and activate partner-provided features on their cards through the Features Marketplace.

Discovery

The mCards mobile app displays available features to the cardholder. Each feature listing includes:

• Feature name and description
• Whether a subscription purchase is required
• Whether Terms & Conditions (T&C) acceptance is needed

Activation Steps

1. Subscription (if required): If the feature requires a subscription, the app retrieves pricing and facilitates the purchase before proceeding
2. T&C Acceptance (if required): If the feature requires Terms & Conditions, the cardholder is prompted to accept before activation continues
3. Webview Launch: If the feature has a custom_signup_webview_url, the mCards app opens a webview to that URL, passing a Feature SSO Token for authentication
4. Partner Onboarding: The feature provider's web application receives the token, validates it, and completes the activation flow (e.g., account linking, additional sign-up steps)
5. Completion: The cardholder returns to the mCards app with the feature activated

Token Details

The Feature SSO Token is passed as a Bearer token in the Authorization header. It contains:

• Cardholder identity (consumer_id, phone_number)
• Card context (cardholder_card_uuid, distributor_card_uuid)
• Optional claims (name, email, address, date of birth) based on the feature's configuration

See Feature SSO Token for the full claim structure and a sample payload.

---

Payment Gateway Onboarding Flow

Payment gateway onboarding allows cardholders to enroll with a payment gateway provider so that the gateway can participate in transaction authorization decisioning for their card.

Discovery

The mCards mobile app retrieves available payment gateways and displays them to the cardholder. Each gateway listing includes:

• Gateway name and brand
• Gateway category and status
• An onboarding_url provided by the gateway partner

Enrollment Steps

1. Gateway Selection: The cardholder selects a payment gateway from the available list
2. Token Generation: mCards generates a Payments User Token containing the cardholder's identity and card context
3. Webview Launch: The mCards app opens a webview to the gateway's onboarding_url, passing the Payments User Token as a Bearer token
4. Partner Onboarding: The payment gateway's web application validates the token, identifies the cardholder, and completes the enrollment (e.g., linking a funding source, setting up payment preferences)
5. Completion: The cardholder returns to the mCards app with the payment gateway linked to their card

Token Details

The Payments User Token follows the same structure as the Feature SSO Token. It contains:

• Cardholder identity (consumer_id, phone_number)
• Card context (cardholder_card_uuid, distributor_card_uuid)
• Optional claims (name, email, address, date of birth) based on the gateway's SSO configuration

See Payments User Token for the full claim structure and a sample payload.

---

Token Delivery

For both onboarding flows, the signed JWT is delivered to the partner's web application via the HTTP Authorization header:

Authorization: Bearer <signed_jwt>

Partners should:

1. Extract the token from the Authorization header
2. Validate the JWT signature using the mCards public key (available via the JWKS endpoint)
3. Verify the token has not expired (tokens are valid for 5 minutes)
4. Use the claims to identify the cardholder and card context

---

UX Considerations for Partners

When building an embedded onboarding experience, partners should consider:

---

Related Guides

• Platform Integration Concepts — Overview of embedded partner applications and user-context tokens
• Feature SSO Token — Token structure and sample payload for feature onboarding
• Payments User Token — Token structure and sample payload for payment gateway onboarding
• API Authentication and Credentials — HMAC request signing for API calls