# Delegated Mode

## 1. User Onboarding

In Delegated Mode, the Partner redirects the user to a secure UR Webview. Within this Webview, the user completes identity verification (KYC), creates their UR account and URID, and crucially, signs an approval to "Delegate" access to the Partner. Once complete, UR redirects the user back to the Partner App with an authorization code.

Key Difference: Unlike External Wallet Mode, the user does not sign every action with a personal wallet; they perform a one-time "Delegation" setup here.

**Authorization Flow Diagram**

```mermaid

sequenceDiagram
    participant User as User Browser
    participant Partner as Partner Server
    participant UR as UR Authorization Server
    participant MiniDapp as UR Mini Dapp

    Partner->>Partner: 1. Construct authorization URL
    Partner->>User: 2. Display authorization link
    User->>MiniDapp: 3. Click to visit authorization page
    Note over MiniDapp: 4. Parse URL parameters<br/>(client_id, redirect_uri, scope, state)
    User->>MiniDapp: 5. Complete KYC and authorization
    Note over UR: 6. Generate authorization code
    UR->>User: 7. Redirect to redirect_uri
    Note over User: redirect_uri?code=xxx&state=xxx
    User->>Partner: 8. Browser redirects to Partner
    Partner->>UR: 9. Call API to exchange code for user info<br/>(with signature verification)
    UR->>Partner: 10. Return user info and authorization details
    Partner->>User: 11. Complete business flow
```

**Flow Description:**

1. **Initialization**: The user initiates the process on the Partner App. The Partner [constructs a standard OAuth-style Authorization URL](/developer-resources/api-reference-delegated-contract-mode.md#authorization-url-construction) and redirects the user to UR.
2. **Onboarding** (UR Side): The user lands on the secure UR Webview and authenticates via social login (Google or Email OTP, managed by the UR account system). A UR account is automatically created along with a unique URID. The user completes the KYC process (Liveness/ID scan) directly within the UR Webview. The initial status of the URID is set to "Tourist".
3. **Delegation (Critical Step):** Upon submitting KYC data for review, UR prompts the user to grant permissions to the Delegated Contract that is dedicated to the Partner. This authorization enables the Partner to execute future actions (such as offramps) via API without requiring blockchain interaction for every transaction.
4. **Account creation**: UR redirects the user back to the Partner's `redirect_uri` with an Authorization Code. The Partner App [to retrieve the user's `URID`, `ETH Address`, and status](/developer-resources/api-reference-delegated-contract-mode.md#partner-to-fetch-user-onboarding-information), completing the binding process.
5. **Finalization**: Once KYC has been approved, the URID status will become live. Follow up functions will be then unlocked for the user.
6. **KYC retry**: This step is an **exception handling mechanism** and is not part of the standard workflow. Following the initial KYC submission, UR may occasionally flag specific verification steps for retry (e.g., due to document quality issues). This status is updated dynamically via the [profile](/developer-resources/api-reference-delegated-contract-mode.md#fetch-ur-account-information) API. <mark style="color:$primary;">Best Practice: We recommend performing a status check on this field before the user initiates any UR-related features. The user should be redirected to</mark> [<mark style="color:$primary;">get.ur.app</mark>](https://get.ur.app) <mark style="color:$primary;">to complete the retry process if and only if the</mark> <mark style="color:$primary;">`kycRetryVerificationLevel`</mark> <mark style="color:$primary;">field returns a non-zero value.</mark><br>

## 2. Card

Once the user completes onboarding and their URID status becomes **'Live'**, they are eligible for card issuance. Critical operations — such as card activation, revealing card details (PAN/CVV), and managing card settings — are performed by redirecting the user to the **UR Card Webview**. [`Refer to this document`](/developer-resources/api-reference-delegated-contract-mode.md#card) for details of integrating the Card webview integration.

## 3. Profile

Some users may need to view their IBAN information, so we provide an integration for the **Profile Webview**. Partners can integrate this webview into their app as either a webview or a dialog. For detailed integration instructions, please refer to [`this document`](/developer-resources/api-reference-delegated-contract-mode.md#profile).

## 4. Bank Transfer

For users who need to move funds between their UR account and external bank accounts, we provide an integration for the **Bank Transfer Webview**. Partners can integrate this webview into their app as either a webview or a dialog. For detailed integration instructions, please refer to [`this document`](/developer-resources/api-reference-delegated-contract-mode.md#bank-transfer).

## 5. Core Banking Functions

### Crypto-to-Fiat (Off-Ramp)

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant App as Partner App
    participant UR as UR Backend
    participant Delegator as UR Delegator Contract
    participant Chain as UR Chain

    rect rgb(240, 248, 255)
    note right of User: Phase 1: Quotation
    User->>App: Request USDC offramp in my UR account (e.g. 100 USDC)
    App->>UR: GET /quote/deposit (Amount, Chain)
    UR-->>App: Return Quote<br/>(Exchange Rate, Fees, Est. Fiat Output, Error code)
    App-->>User: Display Estimated Fiat Received
    end

    rect rgb(255, 250, 240)
    note right of User: Phase 2: Permit & Execution
    User->>App: Confirm Transaction
    App->> Chain: Transfer USDC to User's UR account
    Chain->> App: Event: Transfer confirmed 

    App->>UR: API: Create Offramp Request

    UR->>Delegator: request offramp for the user's UR account 
    UR->>App: API response: TX hash
    App-->>User: Show "Status: Processing"
    end

    rect rgb(240, 255, 240)
    note right of User: Phase 3: Settlement
    UR->>Delegator: Start Monitoring (Listening for Event)
    alt Event Offramp Done (Within 5 mins)
        Delegator->>Chain: Done the offramp and send fiat to user's UR account
        Delegator-->>UR: Event: DepositSuccess
        UR->>App: Webhook: Offramp final status
        App-->>User: Show "Status: Success"

    else Timeout (No Webhook report > 5 mins)
        Note right of App: Monitoring exceeded time limit
        
            App->>UR: API: Report Timeout
            UR->>Ops: 🚨 Alert: Deposit Stuck (TxHash)
            Ops->>UR: Fix status
            UR->>App: Fix status
    end
    end
```

**Core Mechanism**

1. **Quotation & Pricing**: The Partner requests a real-time exchange rate and fee structure via the [Offramp quote API](/developer-resources/api-reference-delegated-contract-mode.md#fetch-offramp-quote). This ensures the user sees the exact estimated fiat output before confirming.
2. **API-Driven Execution**: Once the user confirms the trade on the Partner's UI, the Partner triggers the transaction by calling the [Offramp API](/developer-resources/api-reference-delegated-contract-mode.md#create-offramp-request). Critically, this step does not require a user wallet signature. The [Partner signs the API request](/developer-resources/signature-and-verify.md) using their [own key](https://docs.ur.app/integration-methods/pages/l7f8Pyc9yXKXr2gDvZWF#id-1.-generate-key-pair).
3. **On-Chain Settlement**: UR's backend validates the request and triggers the Delegated Contract on the Mantle Network. The contract verifies the user's pre-authorized allowance, transfers the authorized crypto assets (e.g., USDC), and credits the user's UR account with the corresponding fiat balance (e.g., USD).
4. **Asynchronous Notification**: Upon successful on-chain settlement, UR notifies the Partner via a [webhook](/developer-resources/webhook.md#event-transaction), allowing the Partner to update the user's UI to reflect the completed transaction.

### Fiat-to-Crypto (On-Ramp)

Coming Soon

### Fiat-to-Fiat (FX)

Coming Soon

### Cash Pay-in

Coming Soon

### Cash Pay-out (Bank Transfer)

Coming Soon


---

# 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/integration-methods/delegated-mode.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.