# Mesa

> Developer documentation for Mesa's embedded financial features.

## Embedded UI — Overview

Mesa Embedded UI lets you drop Mesa's financial features directly into your web application. The integration renders in an `<iframe>` controlled by a lightweight JavaScript SDK, keeping Mesa's internals fully isolated from your application code.

### When to Use

* You want Mesa financial features embedded directly in your UI without a redirect.
* You need white-label theming — including custom colors, copy, and button text — so the Mesa UI matches your brand.
* You require secure, origin-validated communication between your app and Mesa.

### Getting Started

Follow the [Quickstart](/embedded-ui/quickstart) to go from zero to a working integration.

* [Auth Flow](/embedded-ui/auth-flow) — JWT-based trust model and token payload reference
* [User Flows](/embedded-ui/user-flows) — navigate between CTA, auth, onboarding, and dashboard
* [SDK Reference](/embedded-ui/sdk-reference) — full `MesaClient` API
* [Theming](/embedded-ui/theming) — match your brand
* [ThemeConfig](/embedded-ui/theme-config) — full theme and copy property reference


## Partner API - Overview

### Getting Started

* [Endpoints](/partner-api/endpoints) — all endpoints for the partner API


## Set Up - Overview

Log in at [partners.joinmesa.com](https://partners.joinmesa.com) using the credentials supplied by your Mesa contact.

### Getting Started

* [API Keys](/set-up/api-keys) — create and manage API Keys
* [Authorized Users](/set-up/authorized-users) — add and managed authorized users


## Set Up - API Keys

An API Key consists of a clientId and clientSecret...


## Set Up - Authorized Users


## Partner API - Endpoints

### Version 1.0

***

### Authentication

Authenticate for a given user, using your API Keys.

#### POST partners/\:partnerId:/auth

##### Parameters

`partnerId` - Your assigned partner id

##### Body

```json
{
  "clientId": "...",  // string - Your API Key clientId
  "clientSecret": "...",  // string - Your API Key clientSecret
  "vendorId": "...", // string - The vendor id to which this user is associated
  "userId": "...", // string - The user id
}
```

##### Responses

`200`:

```json
{
  "token": "...", // string - The Bearer token to be used for subsequent API calls
  "config": {  // 
    "theme": { /* ... */ } // object - Theme object
  }
}
```

***

### Invoices

#### GET partners/\:partnerId:/invoices

##### Headers

`Authorization` - Bearer Token

##### Parameters

`sortField`

`sortDirection`

`page`

`limit`

##### Responses

`200`:

```json
{
  "data": { /* ... */ },
  "page": 1,
  "limit": 25,
  "total": 10
}
```


## Auth Flow

Mesa Embedded UI uses a JWT-based trust model to establish a secure channel between your page and the Mesa iframe.

### Step 1 — Request a token from your server

Your server authenticates with Mesa's token API using your `clientId` and `clientSecret` and returns a short-lived JWT to your frontend. **Never expose `clientId` or `clientSecret` to the browser.**

:::code-group
```ts [Express.js]
app.post('/api/mesa-token', async (req, res) => {
  const response = await fetch('https://api.joinmesa.com/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: process.env.MESA_CLIENT_ID,
      clientSecret: process.env.MESA_CLIENT_SECRET,
      vendorId: req.user.orgId,  // your authenticated user's Org ID
      userId: req.user.id,       // your authenticated user's User ID
    }),
  });

  const { token } = await response.json();
  res.json({ token });
});
```

```python [Python]
# Flask
@app.route('/api/mesa-token', methods=['POST'])
@login_required
def mesa_token():
    response = requests.post('https://api.joinmesa.com/v1/token', json={
        'clientId': os.environ['MESA_CLIENT_ID'],
        'clientSecret': os.environ['MESA_CLIENT_SECRET'],
        'vendorId': current_user.org_id,  # your authenticated user's Org ID
        'userId': current_user.id,        # your authenticated user's User ID
    })
    return jsonify(token=response.json()['token'])
```

```java [Java]
// Spring Boot
@RestController
public class MesaController {

    @PostMapping("/api/mesa-token")
    public Map<String, String> getMesaToken(@AuthenticationPrincipal UserDetails user)
            throws IOException, InterruptedException {
        var payload = Map.of(
            "clientId", System.getenv("MESA_CLIENT_ID"),
            "clientSecret", System.getenv("MESA_CLIENT_SECRET"),
            "vendorId", getOrgId(user),   // your authenticated user's Org ID
            "userId", user.getUsername()  // your authenticated user's User ID
        );

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.joinmesa.com/v1/token"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(
                new ObjectMapper().writeValueAsString(payload)))
            .build();

        var response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        var token = new ObjectMapper().readTree(response.body())
            .get("token").asText();

        return Map.of("token", token);
    }
}
```

```csharp [C# (.NET)]
// ASP.NET Core
app.MapPost("/api/mesa-token", async (HttpContext ctx) =>
{
    var body = JsonSerializer.Serialize(new
    {
        clientId = Environment.GetEnvironmentVariable("MESA_CLIENT_ID"),
        clientSecret = Environment.GetEnvironmentVariable("MESA_CLIENT_SECRET"),
        vendorId = ctx.User.FindFirstValue("org_id"),                    // your authenticated user's Org ID
        userId = ctx.User.FindFirstValue(ClaimTypes.NameIdentifier),     // your authenticated user's User ID
    });

    using var http = new HttpClient();
    var response = await http.PostAsync(
        "https://api.joinmesa.com/v1/token",
        new StringContent(body, Encoding.UTF8, "application/json")
    );

    var json = await response.Content.ReadFromJsonAsync<JsonElement>();
    return Results.Json(new { token = json.GetProperty("token").GetString() });
});
```
:::

### Step 2 — Pass the token to `MesaClient.init()`

Your frontend fetches the token from your server and passes it to the SDK. The SDK decodes the JWT to locate the Mesa iframe, inserts it into the page, then forwards the raw token to the embed as part of the auth handshake. The embed decodes the token to establish session context (partner identity, program config, etc.) and pins its trusted origin to the page that sent the message.

```ts
const { token } = await fetch('/api/mesa-token', { method: 'POST' }).then(r => r.json());

await client.init({
  containerId: 'mesa-container',
  jwtToken: token,
});

// client.initialized === true
```

Once `init()` resolves, the embed is authenticated and ready.

***

### JWT Payload Reference

The token request body controls how Mesa behaves for the current session. These fields are encoded in the signed JWT returned by the token API.

| Field         | Type     | Description                                            |
| ------------- | -------- | ------------------------------------------------------ |
| `origin`      | `string` | Allowed iframe origin; scopes the token to your domain |
| `partnerId`   | `number` | Mesa-assigned partner identifier                       |
| `programCode` | `string` | Controls which payment programs appear in onboarding   |

***

### Security

* **Credentials stay server-side** — `clientId` and `clientSecret` never touch the browser
* **Origin-pinned** — the embed locks trust to the origin of the first valid `auth` message it receives; all subsequent postMessages from any other origin are rejected
* **Short-lived tokens** — JWTs are scoped to a single user session and should not be cached or reused


## Quickstart

Integrate Mesa Embedded UI into your web app in three steps.

### Prerequisites

* A Mesa account with `clientId` and `clientSecret`
* A server that can make server-side HTTP requests
* A frontend web app (any framework)

***

### Step 1 — Create a token endpoint on your server

Your server fetches a signed JWT from Mesa's token API and returns it to your frontend. **Never expose `clientId` or `clientSecret` to the browser.**

:::code-group
```ts [Express.js]
app.post('/api/mesa-token', async (req, res) => {
  const response = await fetch('https://api.joinmesa.com/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: process.env.MESA_CLIENT_ID,
      clientSecret: process.env.MESA_CLIENT_SECRET,
      userId: req.user.id,      // your authenticated user's ID
      vendorId: 'early-pay',    // Mesa product identifier
    }),
  });

  const { token } = await response.json();
  res.json({ token });
});
```

```python [Python]
# Flask
@app.route('/api/mesa-token', methods=['POST'])
@login_required
def mesa_token():
    response = requests.post('https://api.joinmesa.com/v1/token', json={
        'clientId': os.environ['MESA_CLIENT_ID'],
        'clientSecret': os.environ['MESA_CLIENT_SECRET'],
        'userId': current_user.id,      # your authenticated user's ID
        'vendorId': 'early-pay',        # Mesa product identifier
    })
    return jsonify(token=response.json()['token'])
```

```java [Java]
// Spring Boot
@RestController
public class MesaController {

    @PostMapping("/api/mesa-token")
    public Map<String, String> getMesaToken(@AuthenticationPrincipal UserDetails user)
            throws IOException, InterruptedException {
        var payload = Map.of(
            "clientId", System.getenv("MESA_CLIENT_ID"),
            "clientSecret", System.getenv("MESA_CLIENT_SECRET"),
            "userId", user.getUsername(),    // your authenticated user's ID
            "vendorId", "early-pay"         // Mesa product identifier
        );

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.joinmesa.com/v1/token"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(
                new ObjectMapper().writeValueAsString(payload)))
            .build();

        var response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        var token = new ObjectMapper().readTree(response.body())
            .get("token").asText();

        return Map.of("token", token);
    }
}
```

```csharp [C# (.NET)]
// ASP.NET Core
app.MapPost("/api/mesa-token", async (HttpContext ctx) =>
{
    var body = JsonSerializer.Serialize(new
    {
        clientId = Environment.GetEnvironmentVariable("MESA_CLIENT_ID"),
        clientSecret = Environment.GetEnvironmentVariable("MESA_CLIENT_SECRET"),
        userId = ctx.User.FindFirstValue(ClaimTypes.NameIdentifier),  // your authenticated user's ID
        vendorId = "early-pay",  // Mesa product identifier
    });

    using var http = new HttpClient();
    var response = await http.PostAsync(
        "https://api.joinmesa.com/v1/token",
        new StringContent(body, Encoding.UTF8, "application/json")
    );

    var json = await response.Content.ReadFromJsonAsync<JsonElement>();
    return Results.Json(new { token = json.GetProperty("token").GetString() });
});
```
:::

***

### Step 2 — Load the SDK

Add the Mesa SDK to your page via a script tag or npm import.

**Script tag:**

```html
<script src="https://cdn.joinmesa.com/sdk/mesa-client.js"></script>
```

**npm:**

```bash
npm install @mesa/sdk
```

***

### Step 3 — Initialize the client

Add a container element and call `MesaClient.init()` with the JWT from your server.

```html
<div id="mesa-container" style="width: 100%; height: 600px;"></div>
```

```ts
import MesaClient from '@mesa/sdk'; // or use window.MesaClient from script tag

async function mountMesa() {
  // 1. Fetch token from your server
  const { token } = await fetch('/api/mesa-token', { method: 'POST' }).then(r => r.json());

  // 2. Initialize the client
  const client = new MesaClient();
  await client.init({
    containerId: 'mesa-container', // ID of the DOM element to mount into
    jwtToken: token,
    entrypoint: 'intro',           // default — shows the pre-auth landing card
    // email: 'user@example.com',  // optional — pre-fills sign-up email
  });

  console.log('Mesa is ready:', client.initialized); // true
}

mountMesa();
```

***

### Next Steps

* [Auth Flow](/embedded-ui/auth-flow) — understand what happens under the hood
* [User Flows](/embedded-ui/user-flows) — navigate between CTA, auth, onboarding, and dashboard
* [Theming](/embedded-ui/theming) — customize colors, radius, and scaling
* [ThemeConfig](/embedded-ui/theme-config) — full theme property reference
* [SDK Reference](/embedded-ui/sdk-reference) — full API documentation


## SDK Reference

### `MesaClient`

The main class for embedding Mesa into a partner web app. Available as an ES module export and as `window.MesaClient` for script-tag usage.

```ts
import MesaClient from '@mesa/sdk';

const client = new MesaClient();
```

***

#### `init(opts: InitOptions): Promise<void>`

Inserts the Mesa `<iframe>` into the specified container, performs the auth handshake, and marks the client as ready.

```ts
await client.init({
  containerId: 'mesa-container',
  jwtToken: token,
  entrypoint: 'intro',            // 'intro' | 'auth' | 'onboarding' | 'dashboard'
  email: 'user@example.com',      // optional — pre-fills sign-up email
});
```

Throws if:

* The container element is not found after 10 retries (100ms each)
* The iframe does not respond with `{ auth_ok: true }` within 5 seconds

Sets `client.initialized = true` on success.

***

#### `destroy(): Promise<void>`

Removes the iframe from the DOM, clears all pending message handlers, and resets internal state.

```ts
await client.destroy();
// client.initialized === false
```

Call this when unmounting the component that hosts the Mesa embed (e.g., in a React `useEffect` cleanup).

***

#### `startIntroScreen(opts?: { email?: string }): Promise<void>`

Navigates the embed to the intro screen (pre-auth landing card).

```ts
await client.startIntroScreen({ email: 'user@example.com' });
```

Pass `email` to pre-fill the sign-up field on the intro screen.

***

#### `startAuth(opts?: { email?: string; screen?: 'signIn' | 'signUp' }): Promise<void>`

Navigates the embed directly to the auth screen, bypassing the intro card.

```ts
await client.startAuth();

// Go directly to sign-in instead of sign-up:
await client.startAuth({ screen: 'signIn' });
```

Pass `screen` to control which auth view opens. Defaults to `'signUp'`.

***

#### `startOnboarding(opts?: { email?: string }): Promise<void>`

Navigates the embed to the onboarding flow. The user must be authenticated.

```ts
await client.startOnboarding({ email: 'user@example.com' });
```

Pass `email` to pre-fill the sign-up field if the user needs to authenticate first.

***

#### `startDashboard(opts?: { email?: string }): Promise<void>`

Navigates the embed to the dashboard. The user must be authenticated and fully onboarded.

```ts
await client.startDashboard({ email: 'user@example.com' });
```

Pass `email` to pre-fill the sign-up field if the user needs to authenticate first.

***

#### `updateTheme(theme: ThemeConfig): void`

Live-updates theme and copy overrides without reinitializing the embed.

```ts
client.updateTheme({ accentColor: 'violet', radius: 'large', introScreenButtonText: 'Get Paid Now' });
```

See [ThemeConfig](/embedded-ui/theme-config) for all available properties.

***

#### `startInstantPayoutButton(configs: InstantPayoutButtonConfig | InstantPayoutButtonConfig[]): void`

Injects a styled "Get Paid Now" button into the page next to one or more DOM elements. Buttons are rendered in a shadow DOM to avoid style conflicts.

```ts
client.startInstantPayoutButton({
  selector: '#pay-button-container',
  invoiceId: 'inv_123',
  position: 'afterend', // optional — 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend', defaults to 'afterend'
});

// Or inject multiple buttons at once:
client.startInstantPayoutButton([
  { selector: '#row-1 .actions', invoiceId: 'inv_123' },
  { selector: '#row-2 .actions', invoiceId: 'inv_456' },
]);
```

When clicked, each button opens the instant payout modal for the specified invoice and temporarily expands the iframe to fullscreen overlay. The iframe restores to its original dimensions when the modal is dismissed.

Button text and colors can be customized via [`updateTheme`](#updatethemetheme-themeconfig-void) using `getPaidNowText`, `getPaidNowButtonColor`, and `getPaidNowButtonHoverColor`.

Requires `init()` to have completed.

***

#### `removeInstantPayoutButtons(): void`

Removes all buttons previously injected by `startInstantPayoutButton()`.

```ts
client.removeInstantPayoutButtons();
```

Also called automatically by `destroy()`.

***

#### `initialized: boolean`

`true` after `init()` completes successfully. `false` before init or after `destroy()`.

***

### `InitOptions`

```ts
type InitOptions = {
  containerId: string;                                              // ID of the DOM element to mount the iframe into
  jwtToken: string;                                                 // JWT issued by Mesa's token API
  entrypoint?: 'intro' | 'auth' | 'onboarding' | 'dashboard';     // controls which screen loads first (default: 'intro')
  email?: string;                                                   // optional — pre-fills sign-up email
  theme?: ThemeConfig;                                              // optional — theme / copy overrides applied at init
};
```

| Property      | Type                                               | Description                                                                                                                       |
| ------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `containerId` | `string`                                           | ID of the DOM element that will contain the iframe. The element must exist (or appear within 1 second) before `init()` is called. |
| `jwtToken`    | `string`                                           | Signed JWT obtained from your server's Mesa token endpoint.                                                                       |
| `entrypoint`  | `'intro' \| 'auth' \| 'onboarding' \| 'dashboard'` | Controls which screen the embed opens on. Defaults to `'intro'`. See [User Flows](/embedded-ui/user-flows).                       |
| `email`       | `string`                                           | Pre-fills the sign-up email field. Effective when `entrypoint` is `'intro'` or `'auth'`.                                          |
| `theme`       | `ThemeConfig`                                      | Theme and copy overrides applied during the auth handshake. See [ThemeConfig](/embedded-ui/theme-config).                         |

***

### `InstantPayoutButtonConfig`

```ts
type InstantPayoutButtonConfig = {
  selector: string;                                                         // CSS selector for the element to insert the button relative to
  invoiceId: string;                                                        // Mesa invoice ID to open when the button is clicked
  position?: 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend';     // insertion position (default: 'afterend')
};
```

| Property    | Type                             | Description                                                                           |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------------- |
| `selector`  | `string`                         | CSS selector identifying the target element. Logs a warning and skips if not found.   |
| `invoiceId` | `string`                         | The Mesa invoice ID to open in the instant payout modal.                              |
| `position`  | `InsertAdjacentElement` position | Where to insert the button relative to the matched element. Defaults to `'afterend'`. |

***

For brand and copy customization, see [ThemeConfig](/embedded-ui/theme-config).

***

### Global Script Tag Usage

When loaded via `<script>`, `MesaClient` is exposed as `window.MesaClient`:

```html
<script src="https://cdn.joinmesa.com/sdk/mesa-client.js"></script>
<script>
  const client = new window.MesaClient();
  await client.init({ containerId: 'mesa-container', jwtToken: token });
</script>
```


## ThemeConfig

`ThemeConfig` controls the visual appearance and copy of the Mesa embed. You can provide it in two ways:

* **At init** — pass `theme: { ... }` in `InitOptions` when calling `client.init()` (see [Theming](/embedded-ui/theming#init-time-theme))
* **Runtime** — call `client.updateTheme(themeConfig)` at any point after `init()` (see [SDK Reference](/embedded-ui/sdk-reference#updatethemetheme-themeconfig-void))

***

### Color

| Property                    | Type        | Default   | Description                                                                                                                                                 |
| --------------------------- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accentColor`               | named color | `'blue'`  | Primary brand color for buttons, links, and interactive elements.                                                                                           |
| `grayColor`                 | named gray  | `'slate'` | Gray scale for borders, backgrounds, and muted text.                                                                                                        |
| `customAccentColor`         | hex string  | —         | Arbitrary hex value for pixel-exact brand colors. Mesa generates a full accessible color scale from this hex. Takes precedence over `accentColor` when set. |
| `customAccentColorContrast` | hex string  | —         | Override the auto-detected contrast color for `customAccentColor` (e.g. `'#ffffff'` to force white button text). Only used when `customAccentColor` is set. |
| `customGrayColor`           | hex string  | —         | Arbitrary hex value for the gray scale. Takes precedence over `grayColor` when set.                                                                         |

**Named accent colors:** `tomato`, `red`, `ruby`, `crimson`, `pink`, `plum`, `purple`, `violet`, `iris`, `indigo`, `blue`, `cyan`, `teal`, `jade`, `green`, `grass`, `brown`, `orange`, `amber`, `yellow`, `lime`, `mint`, `sky`

**Named gray scales:** `gray`, `mauve`, `slate`, `sage`, `olive`, `sand`

Use `customAccentColor` when a named color isn't close enough to your brand — for example, `customAccentColor: '#5a05ff'`. If Mesa's auto-detected contrast color doesn't meet your accessibility requirements, pair it with `customAccentColorContrast`.

***

### Layout

| Property  | Type                                                 | Default    | Description                                                                           |
| --------- | ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| `radius`  | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'medium'` | Border radius scale applied globally to all interactive components.                   |
| `scaling` | `'90%' \| '95%' \| '100%' \| '105%' \| '110%'`       | `'100%'`   | Overall UI density / scaling factor. Useful for fitting the embed in compact layouts. |

***

### Copy Overrides

These fields let you customize the text and content shown in the embed. All are optional; Mesa's defaults are used for any field you omit.

#### Intro Screen

| Field                    | Default                                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `introScreenTitle`       | `"Get paid in 30 days via ACH"`                                                                                            |
| `introScreenDescription` | Mesa default — use this to name the platform (e.g. `"Get paid via ACH as soon as your invoices are authorized in Coupa."`) |
| `introScreenButtonText`  | `"Get Started"`                                                                                                            |
| `featureCards`           | Array of `{ title, description }` cards — replaces Mesa's default feature list                                             |

#### Auth

| Field            | Default                 |
| ---------------- | ----------------------- |
| `signUpTitle`    | `"Create your account"` |
| `signUpSubtitle` | Mesa default            |
| `signInTitle`    | `"Welcome back"`        |
| `signInSubtitle` | Mesa default            |

#### Dashboard

| Field                        | Default                                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `dashboardTitle`             | `"Mesa"`                                                                                                        |
| `statsBar`                   | `false` hides the stats bar entirely; a `string[]` replaces the default stat items                              |
| `paymentTrigger`             | `'submission'` or `'approval'` — controls payment timing language throughout the UI. Defaults to `'approval'`   |
| `paymentScheduleDescription` | Template for net-days program descriptions. Use `{netDays}` as the placeholder (e.g. `"Net {netDays} via ACH"`) |

#### Instant Payout

| Field                        | Default                                                   |
| ---------------------------- | --------------------------------------------------------- |
| `getPaidNowText`             | `"Get Paid Now"`                                          |
| `getPaidNowButtonColor`      | `#5A05FF` — background of injected instant payout buttons |
| `getPaidNowButtonHoverColor` | Auto-derived (one scale step darker)                      |

***

### Full Type Definition

```ts
type FeatureCard = {
  title: string;
  description: string;
};

type ThemeConfig = {
  // Color
  accentColor?: string;               // named color (e.g., 'violet', 'blue')
  grayColor?: string;                 // named gray scale (e.g., 'slate', 'mauve')
  customAccentColor?: string;         // arbitrary hex — generates full color scale
  customAccentColorContrast?: string; // override auto-detected contrast color for customAccentColor
  customGrayColor?: string;           // arbitrary hex — generates full gray scale

  // Layout
  radius?: 'none' | 'small' | 'medium' | 'large' | 'full';
  scaling?: '90%' | '95%' | '100%' | '105%' | '110%';

  // Content & copy overrides
  introScreenTitle?: string;
  introScreenDescription?: string;    // intro screen hero subheading (name the platform here)
  introScreenButtonText?: string;
  featureCards?: FeatureCard[];       // replaces default intro screen feature list
  signUpTitle?: string;
  signUpSubtitle?: string;
  signInTitle?: string;
  signInSubtitle?: string;
  dashboardTitle?: string;
  statsBar?: string[] | false;        // false hides the stats bar; array replaces default items
  paymentTrigger?: 'submission' | 'approval';  // payment timing language (default: 'approval')
  paymentScheduleDescription?: string;         // template for net-days descriptions, use {netDays}
  getPaidNowText?: string;
  getPaidNowButtonColor?: string;      // hex — background of injected instant payout buttons
  getPaidNowButtonHoverColor?: string; // hex — hover background (auto-derived if omitted)
};
```


## Theming

Mesa Embedded UI supports white-label theming so the embed matches your brand. There are two ways to apply theme configuration:

1. **At init via `InitOptions.theme`** — pass a `theme` object when calling `client.init()`. Applied during the auth handshake before any screen renders.
2. **Runtime via `client.updateTheme()`** — call this at any time after `init()` to live-update colors, radius, and copy without reinitializing.

***

### Init-Time Theme

Pass a `theme` object in `InitOptions` when calling `client.init()`. The embed applies this configuration during the auth handshake.

```ts
await client.init({
  containerId: 'mesa-container',
  jwtToken: token,
  theme: {
    accentColor: 'violet',
    grayColor: 'mauve',
    radius: 'large',
    introScreenButtonText: 'Get Paid Now',
  },
});
```

***

### Runtime Overrides

Call `client.updateTheme()` to update theme and copy overrides after the embed is initialized:

```ts
client.updateTheme({ accentColor: 'violet', radius: 'large', introScreenButtonText: 'Get Paid Now' });
```

Changes take effect immediately without reloading the iframe. See [ThemeConfig](/embedded-ui/theme-config) for all available properties.

***

### Example: Matching Your Brand

| Your brand              | Suggested `accentColor` or `customAccentColor` | Suggested `radius`    |
| ----------------------- | ---------------------------------------------- | --------------------- |
| Blue/fintech            | `'blue'` or `'indigo'`                         | `'medium'`            |
| Warm/consumer           | `'orange'` or `'amber'`                        | `'large'` or `'full'` |
| Enterprise/neutral      | `'slate'` or `'sage'`                          | `'small'` or `'none'` |
| Pixel-exact brand color | `customAccentColor: '#your-hex'`               | any                   |

Use `customAccentColor` with any hex value when a named color isn't a close enough match — Mesa generates a full accessible color scale from the hex automatically.


## User Flows

The Mesa embed is organized into four distinct screens. This guide explains each screen, how to control which one the embed opens on, and how to navigate between them at runtime.

***

### The Four Screens

| Screen                                 | Description                                                                                                                                                                       |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Intro**](#the-intro-screen)         | Pre-auth landing card. Introduces Mesa to new users and prompts them to get started. Customizable with `introScreenTitle`, `introScreenDescription`, and `introScreenButtonText`. |
| [**Auth**](#user-authentication)       | Sign-up and sign-in forms. New users create an account; returning users sign in.  Optionally Mesa support OIDC authentication for users.                                          |
| [**Onboarding**](#the-onboarding-flow) | Multi-step form that collects business and banking details to activate the Mesa product.                                                                                          |
| [**Dashboard**](#the-dashboard)        | The post-onboarding view. Shows summary cards and a tabbed invoice/payment/collections table.                                                                                     |

***

#### Entrypoints

The `entrypoint` option in `InitOptions` controls which screen the embed opens on when `init()` is called.

```ts
await client.init({
  containerId: 'mesa-container',
  jwtToken: token,
  entrypoint: 'intro', // default
});
```

| Value          | Opens on        | When to use                                            |
| -------------- | --------------- | ------------------------------------------------------ |
| `'intro'`      | Intro card      | Default. Best for new or unknown users.                |
| `'auth'`       | Sign-up/sign-in | Skip the landing card and go straight to auth.         |
| `'onboarding'` | Onboarding flow | User is authenticated but hasn't completed onboarding. |
| `'dashboard'`  | Dashboard       | User is authenticated and fully onboarded.             |

***

#### Navigation Methods

After `init()`, use these methods to navigate the embed programmatically:

| Method                           | Description                                                                |
| -------------------------------- | -------------------------------------------------------------------------- |
| `client.startIntroScreen(opts?)` | Navigate to the intro screen. Pass `{ email }` to pre-fill sign-up.        |
| `client.startAuth()`             | Navigate directly to sign-up, bypassing the intro screen.                  |
| `client.startOnboarding()`       | Navigate to the onboarding flow. User must be authenticated.               |
| `client.startDashboard()`        | Navigate to the dashboard. User must be authenticated and fully onboarded. |

See the [SDK Reference](/embedded-ui/sdk-reference) for full method signatures.

***

### The Intro Screen

The intro screen is a pre-auth landing card shown to users who haven't started the Mesa flow yet. It's designed to introduce the product and encourage sign-up.

You can customize all of its text via `ThemeConfig`:

```ts
client.updateTheme({
  introScreenTitle: 'Get paid faster',
  introScreenDescription: 'Access your outstanding invoices in minutes.',
  introScreenButtonText: 'Get Started',
});
```

See [ThemeConfig](/embedded-ui/theme-config#copy-overrides) for the full list of copy fields.

***

### User Authentication

Mesa's native user authentication involves creating and confirming an account for each new user.  Returning users can then sign in using the credentials created during sign up.

#### OIDC Authentication

Mesa also supports authenticating users via your preferred OpenID Provider such as Okta, Azure AD, and Google.  In this authentication flow, users do not use Mesa's native sign-up or sign-in forms but rather authenticate directly with your OpenID Provider to access resources on Mesa's servers.

The OpenID App Client/Application requirements are:

1. Configured for Mesa's sign-in redirect URI
2. Supports the Authorization Code flow
3. Allows the following scopes:
   * openid
   * email
   * profile

You'll need to share the Issuer Url, Client Id, and Client Secret with Mesa. Contact [support@joimesa.com](mailto\:support@joimesa.com) for more information in enabling OIDC Authentication with your integration.

Note that integrating your OpenID Provider with Mesa provides for *authentication*, but users will still need to complete onboarding in order to be fully *provisioned* with Mesa.

***

### The Onboarding Flow

Onboarding is a multi-step form that collects the information Mesa needs to activate the product for the user. The steps are:

1. **BusinessInfo** — business name, type, and address
2. **PaymentSchedule** — available options are controlled by `programCode` in the JWT payload (see [Auth Flow](/embedded-ui/auth-flow#jwt-payload-reference))
3. **BankInfo** — bank account details for payouts
4. **Terms** — acceptance of Mesa's terms of service
5. **Finishing** — confirmation and activation

***

### The Dashboard

The dashboard is the primary post-onboarding view. It includes:

* **3 summary cards** — key metrics for the user's account
* **Tabbed table** — invoices, payments, and collections in separate tabs

Two `ThemeConfig` fields affect the dashboard directly:

* `dashboardTitle` — the heading shown at the top of the dashboard (default: `"Mesa"`)
* `getPaidNowText` — the label on the invoice table action button (default: `"Get Paid Now"`)

***

### Common Patterns

#### Default: open on the intro screen

```ts
await client.init({
  containerId: 'mesa-container',
  jwtToken: token,
  entrypoint: 'intro',           // default — shows the pre-auth landing card
  email: 'user@example.com',     // optional — pre-fills sign-up email
});
```

#### Skip intro, open directly on sign-up

```ts
// Via init option:
await client.init({ containerId: 'mesa-container', jwtToken: token, entrypoint: 'auth' });

// Or navigate at runtime:
await client.startAuth();
```

#### Authenticated users go straight to dashboard

```ts
await client.init({
  containerId: 'mesa-container',
  jwtToken: token,
  entrypoint: 'dashboard',
});
```