Customization - Hypermid

The SDK is configured in four places, each with a different job. This page is the index of what you can tune; the deep dives live on their own pages.

A live playground for previewing these settings is coming. Until then, this page is the reference — every option here is real and current.

1. Look and feel — theming

How the hosted payment page renders: colours, font, and corner radius. Set as query parameters on the embed (or redirect) URL — no CSS, no build step.

Knob	Values
`theme`	`light` \| `dark` base preset
`accent`	accent / primary colour (hex, no `#`)
`bgPage`, `bgCard`, `border`	surface colours
`textPrimary`, `textMuted`, `textFaint`	text ramp
`font`	family name (best-effort system font unless Inter)
`radius`	card corner radius `0`–`24`; button radius derived

Full table, validation rules, and a worked example: Theming.

2. Presentation — redirect vs embed

A created session returns two URLs, and they are not interchangeable:

Field	Use it to
`url`	Redirect the payer (`/pay/:id`). Not framable — answers `X-Frame-Options: DENY`.
`embedUrl`	Embed in an iframe (`/embed?paymentId=…`). No framing headers.

redirect(session.url!);                    // full-page redirect
<iframe src={session.embedUrl!} />         // keep the payer on your site

Details, plus the connected-wallet bridge: Widget. When you embed the widget and your app already has a wallet connected, the parent bridge lends that connection to the iframe so the payer never reconnects. Its options are the behavioural hooks:

import { createParentBridge } from "@hypermid/sdk";

const bridge = createParentBridge({
  iframe: document.getElementById("hypermid") as HTMLIFrameElement,
  provider: walletClient.transport,   // any EIP-1193 provider
  address: connectedAddress,
  chainId: currentChainId,

  onReady: () => setFrameReady(true),
  onPaymentComplete: (paymentId, txHash, paidAmount) => showPending(txHash),
  onError: (paymentId, reason) => showError(reason),
});
bridge.start();

Option	Type	Notes
`iframe`	`HTMLIFrameElement`	The frame to bridge. Point it at `embedUrl`.
`provider`	EIP-1193 provider	From wagmi, Privy, viem, etc.
`address`	`0x${string}`	Currently connected address.
`chainId`	`number`	Currently connected chain.
`onReady`	`() => void`	Frame is ready to receive the connection.
`onPaymentComplete`	`(paymentId, txHash, paidAmount) => void`	Payer submitted a tx — a UI signal, not settlement.
`onError`	`(paymentId, reason) => void`	The frame reported a problem.
`apiBase`	`string`	Hardcoded to production by default; overriding is deliberate, not routine.

Keep it in sync with the wallet — tear the bridge down and start a new one when address or chainId changes, and call bridge.sendAddressChanged(address, chainId) / bridge.sendDisconnected() on wallet events. Call bridge.stop() on unmount.

onPaymentComplete fires when the payer submits a transaction, not when funds settle — cross-chain routes still have a bridge leg. Release goods on the webhook plus a session read, never on this callback.

4. Client options

Payment client — `PaymentsClientOptions`

Second argument to createCheckout / createDeposit / createWithdrawal / getPayment. Server-side only.

Option	Type	Default	Notes
`secretKey`	`string`	—	`sk_live_…` or `sk_test_…`. Required. Never in a browser.
`apiBase`	`string`	`https://server.hypermid.io`	Override the host.
`signal`	`AbortSignal`	—	For timeouts and cancellation.

const controller = new AbortController();
setTimeout(() => controller.abort(), 10_000);   // 10s ceiling

const session = await createCheckout(req, {
  secretKey: process.env.HYPERMID_SECRET_KEY!,
  signal: controller.signal,
});

Read client — `new Hypermid(config)`

For chains, tokens, quotes, status, and balances. Safe anywhere; the key is optional.

Option	Type	Default	Notes
`apiKey`	`string`	— (anonymous)	Publishable key, sent as `X-API-Key`. Not from a browser bundle.
`baseUrl`	`string`	`https://server.hypermid.io`	Override the host.
`timeout`	`number` (ms)	`30000`	Per-request timeout.
`fetch`	`typeof fetch`	global `fetch`	Custom fetch, already bound.

import { Hypermid } from "@hypermid/sdk";

const hypermid = new Hypermid({
  apiKey: process.env.HYPERMID_PUBLISHABLE_KEY,
  timeout: 8_000,
});

More: Read client.

5. Webhook verification — `verifyWebhook`

Handling the events Hypermid sends you. Verify against the raw body, before any JSON parsing.

Option	Type	Default	Notes
`toleranceSeconds`	`number`	`300`	Replay window. A verbatim delivery is accepted until it is this old.
`now`	`() => number`	`Date.now`	Clock override. For tests only.

import { verifyWebhook } from "@hypermid/sdk/webhooks";

const raw = await req.text();                       // RAW body, not parsed
const ok = verifyWebhook(raw, req.headers.get("x-hypermid-signature-v2"), secret, {
  toleranceSeconds: 120,                            // tighter replay window
});
if (!ok) return new Response("bad signature", { status: 401 });

Rotation-safe by design: during a secret rotation two signatures are sent and either verifies, so in-flight retries don’t fail. Full flow: Webhooks.

Sandbox

Every surface toggles to sandbox by the key, not a flag or a different host. Use an sk_test_… secret key (payments) or a test publishable key (read client); everything else is identical, testnets only. See Environments.

​1. Look and feel — theming

​2. Presentation — redirect vs embed

​3. Widget behaviour — createParentBridge

​4. Client options

​Payment client — PaymentsClientOptions

​Read client — new Hypermid(config)

​5. Webhook verification — verifyWebhook

​Sandbox

1. Look and feel — theming

2. Presentation — redirect vs embed

3. Widget behaviour — `createParentBridge`

4. Client options

Payment client — `PaymentsClientOptions`

Read client — `new Hypermid(config)`

5. Webhook verification — `verifyWebhook`

Sandbox