Theming - Hypermid

The hosted payment page — whether you redirect 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.

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.

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:

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.

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.

​Parameters

​Colour ramp

​Font

​Radius

​Worked example

​Security

Parameters

Colour ramp

Font

Radius

Worked example

Security