> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session management

> Create and manage authenticated sessions that launch Meridian's hosted Virtual Accounts UI inside your application's WebView.

## Create a new UI Session

Each session represents a single, self-contained interaction. Your customer completes onboarding or account management actions within the embedded experience and exits when finished. Because the experience runs in a WebView, your application must provide a way for your customer to leave the flow. This is typically a **custom navigation bar or close control** in the host application.

Each time your customer re-enters the Virtual Accounts experience, you must create a **new authentication session** and launch a new embedded experience. This ensures that access is explicit, time-bound, and scoped to a single interaction.

Your application must follow the sequence below each time a customer enters the Virtual Accounts experience:

<Steps>
  <Step title="Create a UI Session">
    Your backend calls the Virtual Accounts API to [create a new session](/products/retail-va/api-reference/sessions/create-session) and provide user details in the `customer` object with a unique `customerId`.
  </Step>

  <Step title="Build the Session URL">
    The Virtual Accounts API returns a `sessionKey` that you use to generate a fully formed `sessionURL`. Pass this URL to the client without modification.

    <CodeGroup>
      ```jsx Sandbox theme={null}
      sessionURL = `https://sandbox.va.meridianpay.com?sessionKey=${sessionKey}`
      ```

      ```jsx Production theme={null}
      sessionURL = `https://va.meridianpay.com?sessionKey=${sessionKey}`
      ```
    </CodeGroup>
  </Step>

  <Step title="Load a WebView">
    The client loads the `sessionURL` directly inside a [WebView](/products/retail-va/web-view) that meets the required configuration and permission requirements.
  </Step>

  <Step title="User completes the flow and exits">
    Your customer completes onboarding or account actions and exits the experience using the host application's navigation controls.

    ```mermaid theme={null}
    sequenceDiagram
    actor Customer
    participant App as Partner Mobile App
    participant Backend as Partner Backend
    participant API as Meridian Backend
    participant UI as Meridian UI Session

    Customer->>App: Taps "Open Virtual Account (VA)"

    App->>Backend: Create a new VA UI Session

    Backend->>API: POST /v1/virtual-accounts/sessions

    API-->>Backend: 201 Created

    Backend-->>App: Return the sessionKey

    Note over App,UI: Session is single-use · expires in 30 min · must not be cached or reused

    App->>UI: Generate and Load the sessionURL in a WebView<br/>(camera · cookies · localStorage · JS enabled)
    ```
  </Step>
</Steps>

## UI Session lifecycle

Virtual Accounts sessions follow these rules:

* Sessions are **single-use** and must not be reused.
* Sessions are **short-lived** and expire after **30 minutes**.
* Sessions are **payload-bound** to the customer identifier and any onboarding or receiver details submitted at creation time.
* Any change to customer identifiers, KYC information, or receiver details requires creating a **new session**.
* Session URLs must **not** be cached or stored for later use.

These constraints ensure data freshness, deterministic behavior, and secure access to the hosted experience.