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

# Customize Appearance

> Brand the checkout page with your colors and logo

Brand the hosted checkout page with your colors, logo, and typography. Pass an `appearance` object when you [create a session](/guides/payments/checkout/create-session) or [payment link](/guides/payments/checkout/payment-links).

<Info>
  **Current checkout layout:** On desktop, the customer sees a **soft outer page background** (default lavender) with a **single centered card** (\~960px): **payment form on the left** (\~56%) and **order summary on the right** (\~44%), plus a **brand bar** above the card. On mobile, branding and summary stack above the form. There is no API flag to switch to a different layout.
</Info>

The full field list and edge cases (including fields accepted by the API but not yet used in the UI) are in the [Appearance Reference](/guides/payments/checkout/appearance-reference).

## Basic Customization

```json theme={null}
{
  "merchantId": "your_merchant_id",
  "merchantName": "My Store",
  "amount": "25.00",
  "successUrl": "https://mystore.com/success",
  "cancelUrl": "https://mystore.com/cancel",
  "errorUrl": "https://mystore.com/error",
  "appearance": {
    "primaryColor": "#4F46E5",
    "buttonBackgroundColor": "#4F46E5",
    "textColor": "#111827"
  }
}
```

`merchantName` is **required** when creating a session; it is stored on the session and drives the **store title** next to your logo (it is not set through `appearance` alone).

## Appearance Options (common)

### Colors

| Option                  | Description                                                                                                                                                                           | Example     |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |
| `primaryColor`          | Main brand color (accents, selected payment method border, default pay button chain)                                                                                                  | `"#4F46E5"` |
| `primaryHoverColor`     | Primary hover                                                                                                                                                                         | `"#4338CA"` |
| `secondaryColor`        | Secondary accents where used                                                                                                                                                          | `"#64748B"` |
| `backgroundColor`       | Sets global/custom fallbacks (inputs, many panels). **Not** the outer lavender canvas behind the desktop card—use `cssVariables` with key `page-background` for that (see reference). | `"#FFFFFF"` |
| `textColor`             | Default text                                                                                                                                                                          | `"#111827"` |
| `borderColor`           | Borders and some dividers                                                                                                                                                             | `"#D1D5DB"` |
| `buttonBackgroundColor` | Pay button background (overrides `primaryColor` for the button)                                                                                                                       | `"#4F46E5"` |
| `buttonHoverColor`      | Pay button hover                                                                                                                                                                      | `"#4338CA"` |

### Logo

| Option             | Description                                                                                                                | Example                          |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |
| `logoUrl`          | HTTPS URL to your logo                                                                                                     | `"https://mystore.com/logo.png"` |
| `logoPosition`     | `inline` (default) or `top`                                                                                                | `"inline"`                       |
| `logoMaxHeight`    | Present in the API model; **not applied** by the live page today (logo size follows `logoPosition` and viewport).          | `"50px"`                         |
| `showMerchantName` | If `true`, show name with logo. If omitted/false with a logo, **logo only**. Without `logoUrl`, the **name always shows**. | `true`                           |

### Layout (inside the desktop card)

| Option                | Description                                                        | Example     |
| :-------------------- | :----------------------------------------------------------------- | :---------- |
| `leftSideBackground`  | **Order summary** column (visually the **right** side of the card) | `"#F9FAFB"` |
| `rightSideBackground` | **Payment form** column (visually the **left** side of the card)   | `"#FFFFFF"` |
| `formBackground`      | Form container / panel fill                                        | `"#FFFFFF"` |
| `mobileBackground`    | Mobile sections (summary, donation block, etc.)                    | `"#FFFFFF"` |
| `borderRadius`        | Corner scale for themed controls                                   | `"lg"`      |

Valid `borderRadius` values: `none`, `sm`, `base`, `lg`, `xl`, `full`.

## Example: Dark panels

```json theme={null}
{
  "appearance": {
    "primaryColor": "#8B5CF6",
    "buttonBackgroundColor": "#8B5CF6",
    "buttonHoverColor": "#7C3AED",
    "backgroundColor": "#1F2937",
    "textColor": "#F9FAFB",
    "borderColor": "#374151",
    "leftSideBackground": "#111827",
    "rightSideBackground": "#1F2937",
    "formBackground": "#374151"
  }
}
```

## Example: Brand colors + logo

```json theme={null}
{
  "appearance": {
    "primaryColor": "#FF6B00",
    "primaryHoverColor": "#E55D00",
    "logoUrl": "https://mystore.com/logo.png",
    "showMerchantName": true
  }
}
```

## Outer page background (desktop)

The area **behind** the centered card uses CSS variable `--custom-page-background` (default lavender). Set it via `appearance.cssVariables`:

```json theme={null}
{
  "appearance": {
    "primaryColor": "#4F46E5",
    "cssVariables": {
      "page-background": "#EEF2FF"
    }
  }
}
```

Values in `cssVariables` are sanitized as **colors or size/dimension values** (e.g. `px`, `em`, `%`). Values that don't parse as either are silently dropped. Use `customCss` for arbitrary styling (within [security limits](/guides/payments/checkout/appearance-reference#custom-css)).

<Note>
  As a shorthand, you can also set `pageBackground` directly in the `appearance` object instead of via `cssVariables`:

  ```json theme={null}
  {
    "appearance": {
      "primaryColor": "#4F46E5",
      "pageBackground": "#EEF2FF"
    }
  }
  ```

  Both forms are equivalent. `cssVariables.page-background` takes precedence if both are set.
</Note>

## Full options

See the [Appearance Reference](/guides/payments/checkout/appearance-reference) for every key, mobile overrides, cart colors, `customCss`, accessibility warnings, and limitations (for example **pay button label** is derived from tax context—not a single `appearance` string).