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

# Theming

> Match the hosted payment page to your brand with URL parameters — no CSS, no build step.

The hosted payment page — whether you [redirect](/sdk/widget) to `session.url`
or embed it in an iframe — reads its colours, font, and corner radius from
**query parameters on the URL**. Append them to the session URL (or to
`https://pay.hypermid.io/embed?paymentId=…`) and the page renders in your theme.
Nothing is built or uploaded; the parameters are read at load.

```
https://pay.hypermid.io/embed?paymentId=pay_123&theme=light&accent=00aa88&radius=12
```

## Parameters

| Param         | Value             | Effect                                                                                                   |
| ------------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
| `theme`       | `light` \| `dark` | The base preset every other param overrides. Defaults to `light`.                                        |
| `accent`      | hex               | Accent / primary colour — buttons, highlights.                                                           |
| `bgPage`      | hex               | Page background, behind the card.                                                                        |
| `bgCard`      | hex               | Card background.                                                                                         |
| `border`      | hex               | Border colour.                                                                                           |
| `textPrimary` | hex               | Primary text.                                                                                            |
| `textMuted`   | hex               | Secondary text.                                                                                          |
| `textFaint`   | hex               | Faint / tertiary text.                                                                                   |
| `font`        | family name       | Font family (see below).                                                                                 |
| `radius`      | `0`–`24`          | Card corner radius in px. The button radius is **derived** from it, so the page stays visually coherent. |

<Note>
  **Colours are hex *without* the `#`** — `accent=00aa88`, not `accent=%2300aa88`.
  Three to eight hex digits are accepted; anything else falls back to the preset
  value rather than erroring.
</Note>

### Colour ramp

`bgPage`, `bgCard`, `border`, and the three `text*` params are a full surface
ramp — set them together for a coherent custom palette rather than overriding
one in isolation. Any you omit keep the `theme` preset's value.

### Font

`font` takes a **family name only** (`font=Inter`, `font=Roboto`). It is not a
web-font loader: `Inter` ships with the page, and any other name is a
**best-effort system font** — it renders only if the payer's device has it,
otherwise the page falls back to Inter. The name is matched against a strict
pattern; punctuation that could carry CSS syntax is rejected.

### Radius

`radius` is a single bounded scale (0–24 px, capped so a card stays a card, not a
pill). You set the **card** radius; the button radius is computed from it to
preserve the design's proportions, so an embed cannot drift into an incoherent
mix of shapes.

## Worked example

A minty light theme with tighter corners:

```
?theme=light
&accent=00aa88
&bgPage=f4f7f6
&bgCard=ffffff
&border=e3ece9
&textPrimary=0c1f1a
&textMuted=5c6b66
&textFaint=9aa8a3
&font=Inter
&radius=10
```

Building it in code:

```ts theme={"system"}
const theme = new URLSearchParams({
  theme: "light",
  accent: "00aa88",
  bgPage: "f4f7f6",
  bgCard: "ffffff",
  border: "e3ece9",
  textPrimary: "0c1f1a",
  textMuted: "5c6b66",
  textFaint: "9aa8a3",
  font: "Inter",
  radius: "10",
});

const embedUrl = `${session.url}&${theme}`;
// or: `https://pay.hypermid.io/embed?paymentId=${session.id}&${theme}`
```

## Security

A merchant **cannot inject CSS** through these parameters. Every colour is passed
through a hex validator (`^[0-9a-fA-F]{3,8}$`) and `font` through a strict
name pattern; a value that does not match is discarded and the preset value is
used. There is no raw-style or stylesheet parameter by design — the theming
surface is exactly the table above and nothing more.

<Note>
  The legacy `@hypermid/checkout` package is deprecated. New integrations should
  create the session with `@hypermid/sdk`, then use its `session.url` or
  `session.embedUrl` on `pay.hypermid.io` and append the validated theme
  parameters shown above.
</Note>