# UX Guide

## Introduction

This guide helps partners integrate UR's banking services in a way that accurately represents our product offering and creates the best experience for end users.

UR provides banking infrastructure with comprehensive banking features. The multi-currency card is a valuable spending tool that complements the account, **not the** primary product.

Following these guidelines ensures your users understand the full value of UR's banking services and helps set appropriate expectations from the start.

#### What UR Provides

UR offers a **bank account** that enables users to:

* Hold and manage fiat currency balances
* Deposit funds via bank transfer
* Send funds to external bank accounts
* Convert digital assets to fiat (off-ramp)
* Convert fiat to digital assets (on-ramp)
* Spend their balance using a multi-currency card

The account is the foundation. The card is a convenient way to access and spend the funds held in that account.

#### What UR Is Not

UR is not primarily a card product or payment card service. While the multi-currency card is a valuable feature, it should be positioned as one of several ways users can utilize their bank account, not as the main offering.

## Messaging Hierarchy

#### Primary Messaging

Your integration should emphasize:

1. Total bank balance
2. Individual currencies balances
3. Deposit, Send, Convert functionality

#### Secondary Messaging

After establishing the account value:

* Multi-currency spending capability
* Transaction history
* Virtual debit card
* Card management

#### What to Avoid

Do not position UR primarily as:

* A card product ("Get your Crypto card")
* A payment card service
* A crypto card offering
* Card-first value propositions

## Copy Guidelines

#### Recommended Terminology

#### Account Opening & Setup

✅ "Open your bank account"\
✅ "Start banking with UR"\
❌ "Apply for a card"\
❌ "Card application"

#### Feature Descriptions

✅ "Manage your cash balance"\
✅ "Deposit cash to your account"\
✅ "Send money to any bank account"\
✅ "Convert crypto directly into your bank account"\
✅ "Spend your balance with a debit card"\
❌ "Top up your card"\
❌ "Card balance"\
❌ "Load your card"

## Partner Positioning of UR

### Banner/Marketing Placement For Introduction & Acquisition

The partner should position UR as an **embedded financial capability** rather than an external service.

{% columns %}
{% column %}
**Key Positioning Principles:**

1. **Lead with the benefit to the user**, such as faster payouts, better rates, more control
2. **Mention "Licensed bank account"** early for credibility
3. **Avoid "Get the UR/Partner card"** messaging
4. **Position as integrated solution,** not external app
5. **Use your brand's voice,** not UR's
   {% endcolumn %}

{% column %}

<figure><img src="/files/puvnYvuN3pzQYxReqxdV" alt=""><figcaption><p>Banner example</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

### Fixed Entry Points for UR Bank Account Access

Beyond the initial banner/introduction, partners should provide persistent access to UR account features through a fixed entry point on the home screen. This ensures users can always access their UR account quickly to check balances and transactions without searching through menus.

#### Why Fixed Entry Points Matter:

**User Benefits:**

* Instant access to account balance
* Quick actions without navigation
* Reduces friction for frequent actions

**Partner Benefits:**

* Increased feature engagement
* Reduced support queries ("where's my account?")
* Better user retention
* Clear value proposition always visible

{% columns %}
{% column %}

<figure><img src="/files/IRngBjc3Snr8jAOvOrQ8" alt=""><figcaption><p>Example of a fixed entry point</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/pkI52i2flWPYvFptj4bv" alt=""><figcaption><p>Another example of a fixed entry point</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Fixed Entry Point**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=1-3\&t=HrYv0jeJvqeSoQlT-1)
{% endhint %}

## Visual Hierarchy

{% columns %}
{% column %}
Your integration should follow this visual hierarchy:

1. **Account Information (60% prominence)**

* Account balance (primary visual element)
* Currency balance
* Recent account activity

2. **Core Banking Actions (30% prominence)**

* Deposit funds
* Send funds
* Convert

3. **Card Features (10% prominence)**

* Card management
  {% endcolumn %}

{% column %}

<figure><img src="/files/NGwxUd7cVDpqJdE4AFg2" alt=""><figcaption><p>Bank Account page example</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Bank Account Dashboard**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=1-5\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}

## Account Creation

Partner users must establish their UR identity and link it to their partner account before accessing banking features. This process accomplishes two things:

1. **Account Creation:** Creates on-chain credential representing the UR account and KYC identity
2. **Account Linking:** Connects partner platform identity to user's UR account

### Two Authentication Paths

#### **Google OAuth (Recommended)**

* One-tap authentication
* No CAPTCHA or OTP required
* Fastest path
* Leverages Google's existing verification

<img src="/files/stmXvVBmfmhZJbF7qdCo" alt="" class="gitbook-drawing">

#### **Email Authentication**

* Universal accessibility (no Google account needed)
* Requires CAPTCHA (bot prevention)
* Requires OTP verification (email ownership proof)
* More steps, but more privacy control

<img src="/files/fI7fKeJEHcsfBI1pQD3w" alt="" class="gitbook-drawing">

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Account Creation**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=55-6395\&t=4YF7ojkFUmbkiA7z-1)
{% endhint %}

### URID

**URID (UR Identification)** is a unique identifier generated when a user creates a UR account. It serves as the primary account identifier for customer support and internal operations. Technically, the URID is the token ID of the user's Account NFT on-chain — it is the user's on-chain identity in the UR system.

#### Purpose:

* Unique account identification across all partners
* Customer support account lookup
* Internal operations and troubleshooting
* Cross-reference between partner systems and UR infrastructure
* On-chain account identity via NFT token ID

#### Technical Background

Each UR user is represented on-chain by an Account NFT. The URID corresponds directly to the token ID of this Account NFT, making it the canonical on-chain identity for the user. This means the URID is not merely a database key — it is a verifiable, immutable identifier rooted in the blockchain.

For more technical details on how Account NFTs are structured and managed, refer to the [Account section in Smart Contracts](https://github.com/mantle-xyz/ur-doc/blob/main/design/developer-resources/smart-contracts.md#account).

#### Recommended Placement

{% columns %}
{% column %}
URID is rarely needed by users in normal operations. However, it needs to be accessible for support scenarios.

Ensure it has low visual priority and doesn't compete with high-priority information or actions.
{% endcolumn %}

{% column valign="bottom" %}

<figure><img src="/files/CUXZVOhZMCTmfn15RtyJ" alt="" width="375"><figcaption><p>Example of low-priority but always accessible placement of URID</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

## KYC

The KYC (Know Your Customer) verification process enables users to activate their bank account and unlock full banking functionality. The flow consists of three sequential parts designed to verify user identity, collect required information, and ensure regulatory compliance.

{% content-ref url="/pages/IJXvBpvHvMsxMX9VNcyM" %}
[The User Lifecycle](/concepts/overview-the-user-lifecycle.md)
{% endcontent-ref %}

### Displaying the UR ID During KYC

UR ID is the user's support identifier. During custom partner KYC flows, users should always be able to read and share this value when they need support.

#### Where UR ID comes from

Retrieve the UR ID (`tokenId`) from the Account NFT contract by calling `tokenOfOwnerByIndex(userAddress, 0)`.

{% content-ref url="<https://github.com/mantle-xyz/ur-doc/blob/main/design/developer-resources/smart-contracts.md#account>" %}
<https://github.com/mantle-xyz/ur-doc/blob/main/design/developer-resources/smart-contracts.md#account>
{% endcontent-ref %}

#### When to display it

Show UR ID persistently:

* Across the full KYC onboarding flow (all steps)
* On every retry or failure screen
* Until KYC is completed or the user exits the flow

#### UX recommendations

* Keep it always visible in a fixed area (for example, top bar or sticky footer)
* Provide one-tap copy
* Keep visual priority low so it does not compete with primary KYC actions

{% hint style="warning" %}
Tech writer review required before publish.
{% endhint %}

### Three-Part KYC Structure (5-10mins)

{% stepper %}
{% step %}
**Questionnaire**

Tool: Sumsub\
Purpose: Collect user information and assess risk profile\
Duration: 2-3 minutes
{% endstep %}

{% step %}
**Biometric ID Verification**

Tool: ReadID App Clip (iOS) or ReadID App (Android)\
Purpose: Verify identity document authenticity via NFC chip scanning and liveness check\
Duration: 2-3 minutes
{% endstep %}

{% step %}
**Form A Signing**

Purpose: Regulatory compliance and consent documentation\
Duration: 1-2 minutes
{% endstep %}
{% endstepper %}

### Design Principles

#### Transparent Expectations

Users know what's required before they start: "3 steps: Answer questions → Scan ID → Sign form." Setting expectations reduces anxiety and abandonment.

#### Platform-Appropriate Tools

Different tools for iOS (App Clip) vs Android (full app) optimize for each platform's capabilities while maintaining functional parity.

#### Security Through Familiarity

Using established third-party tools (Sumsub, ReadID) leverages user trust in recognised verification providers.

#### Auto-save progress

If user exits mid-questionnaire, they can resume without restarting

### Pre-KYC Entry Point

#### Delegated Access

After successful UR account creation, users see the KYC prompt. If users dismiss the prompt or stop mid-way, they can proceed with KYC in a 'Bank Account dashboard' or equivalent on the partner's site.

{% columns %}
{% column %}

<figure><img src="/files/oyK03QQRsN0NwYgNbJX2" alt=""><figcaption><p>After successful account creation and connection, users see the KYC prompt.</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/xKUvbl60OmnnBKvWjXEI" alt=""><figcaption><p>Bank Account dashboard: Black card showing "Verify Your Identity" (Pre-KYC state)</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" icon="figma" %}
Figma Reference:\
[**KYC**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=61-7302\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}

## Virtual Debit Card Activation

The card activation flow serves as a critical bridge between account verification and spending capability. This document outlines the strategic design decisions, mandatory currency authorization and the security patterns that protect users while enabling frictionless card usage.

#### **Currency Authorization and Enablement**

Due to regulatory reasons, users have to authorize currencies for payment. To ensure payment does not fail at point of purchase, it is recommended to add currencies authorization at the card activation flow.

{% hint style="success" %} <mark style="color:green;">**We recommend enabling all currencies by default as it maximizes payment success. For wallet partners, this has to be enabled via EIP-7702 in order to batch transactions.**</mark>
{% endhint %}

### Integration Type: Delegated Access

<img src="/files/3b6YKI2EvdCyEm7hnkXW" alt="" class="gitbook-drawing">

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Delegated Access Card Activation**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=28-107\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}

**Authentication Requirement**

Every View Card action requires re-authentication and it applies to both activated and inactive card. Card details represent highly sensitive information comparable to physical card access. This security pattern:

1. Protects against unauthorised access: If someone gains temporary access to an unlocked phone, they can't view full card numbers and CVV
2. Follows industry standards: Banking apps universally gate card details behind authentication
3. Creates security ritual: Users associate card access with security verification, building trust in the platform's protective measures

While authentication adds friction, the trade-off is acceptable because users expect this security measure for financial data.<br>

### Integration Type: Wallet Access

<img src="/files/4l7w4LwGRk2DfI1HZUtV" alt="" class="gitbook-drawing">

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Wallet Access Card Activation**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=135-6297\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}

**Authentication Requirement**

Every "View Card" action requires wallet authentication and applies to both activated and inactive cards. Card details represent highly sensitive information comparable to physical card access. This security pattern:

1. Protects against unauthorised access: If someone gains temporary access to an unlocked phone, they can't view full card numbers and CVV
2. Follows industry standards: Banking apps universally gate card details behind authentication
3. Creates security ritual: Users associate card access with security verification, building trust in the platform's protective measures

While authentication adds friction, the trade-off is acceptable because users expect this security measure for financial data.<br>

**Wallet Authentication Pattern**

**For viewing card details:**

* For external wallet partners: Users must authenticate with their wallet (ie biometric, PIN)
  * Wallet signature proves ownership and intent
* For delegated access partners: Users must authenticate with their UR credentials (Google SSO or Email OTP)
* This applies every time users access "View Card"

**For card activation:**

* For external wallet partners: Users must authenticate with their wallet signature
  * Currency authorization is recommended to be included as part of the activation flow
* For delegated access partners: Users activate through standard partner authentication flow via UR's webview
  * Currency authorization is included within the activation flow

Viewing sensitive card data (full number, CVV) requires cryptographic proof of wallet ownership.

## Card Management

{% columns %}
{% column %}
The Card page serves as the central hub for card security and spending preferences.

**Users can:**

* View card details
* Manage currency authorization
* Monitor spending limits
* Control card security features
  {% endcolumn %}

{% column %}

<figure><img src="/files/OipuBsrUYL4YToZg6GxL" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Card Management**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=83-4148\&t=HrYv0jeJvqeSoQlT-1)
{% endhint %}

## Off-Ramp

UR's off-ramp service enables users to convert digital assets into fiat currency and deposit funds directly into their UR bank account. This seamless conversion bridge connects the digital asset ecosystem with traditional banking, allowing users to cash out digital assets at competitive rates with transparent fees.

#### **How It Works**

Users initiate off-ramp transactions from their partner platform, selecting:

* **Digital asset to convert**
* **Amount to cash out**
* **Destination currency**

The converted fiat appears in their UR bank account balance within minutes, ready to spend via Mastercard debit card.

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Off-ramp**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=29-4447\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}

## Bank Transfer

UR's bank transfer service allows users to receive funds from external bank accounts (that are under their own name) into their UR account. **User can accept incoming transfers in CHF, EUR, and USD from their personal bank accounts** at other financial institutions, providing flexible funding options beyond crypto off-ramping.

#### **How It Works**

For security, users are required to authenticate in order to access their IBAN details. They provide these details to their external bank to initiate a transfer. Funds arrive in their UR account within standard banking timeframes.

{% hint style="info" icon="figma" %}
Figma Reference:\
[**Bank Transfer**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=31-6328\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ur.app/design/ux-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.