---
url: https://js-one.klappay.com/getting-started.md
---
# Getting started

`@klappay/one` is the embeddable payment button for Klappay One. It never
proposes a transaction, never signs anything, and never sees a private key
or a session token — it just opens a modal (an iframe, on desktop) or a
popup (mobile) pointing at Klappay's own hosted identity/wallet flow, and
relays the outcome back to your page via `postMessage`. Everything sensitive
— OTP, wallet selection, WalletConnect, signing — happens entirely on
Klappay's own origin. See [Protocol & security](/protocol) for exactly how
that boundary is enforced.

## Install

::: code-group

```bash [npm]
npm install @klappay/one
```

```bash [pnpm]
pnpm add @klappay/one
```

```bash [yarn]
yarn add @klappay/one
```

:::

Or via `<script>`, no build step required:

```html
<script src="https://js.klappay.com/one@1.js"></script>
```

Pin to a specific version instead of the `@1` major alias if you need a
frozen build — an exact version is also required if you want to add
`integrity`/`crossorigin` for Subresource Integrity, since `@1` is a moving
target and can't carry a fixed hash:

```html
<script
  src="https://js.klappay.com/one@1.2.3.js"
  integrity="sha384-..."
  crossorigin
></script>
```

## A charge, not an amount

Every checkout this button opens is tied to a `chargeId` — a `Charge`
your own backend already created against Klappay Core (with
[`@klappay/node`](https://node-sdk.klappay.com) or
[`@klappay/checkout-kit`](https://node-checkout-sdk.klappay.com)). The
button never takes an `amount`/`recipient`/`token` directly — the popup/
iframe fetches the real charge data itself once it opens, so nothing about
what's being paid ever needs to be trusted from client-side config. See
[Examples](/examples) for a full create-charge-then-render-button flow.

```ts
// on your own backend — never in the browser
import { createClient } from '@klappay/node'

const klap = createClient({ apiKey: process.env.KLAP_API_KEY! })
const charge = await klap.charges.create({
  amount: 25,
  currency: 'USD',
  expiresIn: 3600,
  acceptedPayments: [{ token: 'USDC', network: 'base' }],
})
// charge.id -> hand this to the button below
```

## Three ways to render the button

### Drop-in Web Component

```html
<klappay-button charge-id="ch_123" origin="https://klap.one" variant="black" size="md">
</klappay-button>
```

### Your own button

```html
<button data-klappay-one="ch_123" data-klappay-one-origin="https://klap.one">
  Pay with Klappay
</button>
```

Both are wired up automatically as soon as the script loads — no
JavaScript required for either, and both pick up elements added to the DOM
later too (a client-side router, an infinite-scroll list, a modal opened
after the fact). See [The button](/button) for every attribute.

### Programmatic

```ts
import { createKlappayOne } from '@klappay/one'

const klappayOne = createKlappayOne({
  chargeId: 'ch_123',
  origin: 'https://klap.one',
  onSuccess: (result) => {
    // UX signal only — confirm fulfillment via Klappay Core's webhook,
    // never from this callback alone. See /protocol.
  },
  onError: (error) => console.error(error),
  onCancel: () => console.log('payer closed the checkout'),
})

klappayOne.open()
```

See [Programmatic API](/programmatic) for the full `KlappayOneConfig`
shape, and [React](/react) for `<KlappayButton />` / `useKlappayOne()`.

## `origin`, one way or another

Every entry point needs to know which Klappay origin to open — there's no
baked-in default, since sandbox and production point at different hosts.
Pass it explicitly on every call, or set it once for the whole page:

```ts
import { configure } from '@klappay/one'

configure({ origin: 'https://klap.one', locale: 'en' })
```

`configure()` only affects the two zero-JS entry points (`<klappay-button>`
and `data-klappay-one`) — `createKlappayOne()` itself still requires
`origin` explicitly in its config; the programmatic API has no attribute to
fall back to, so there's no reason to make it implicit.

## Where to go next

* [`button.md`](/button) — every attribute `<klappay-button>` and
  `data-klappay-one` support, and the `success`/`error`/`cancel` events
  they dispatch.
* [`programmatic.md`](/programmatic) — the full `createKlappayOne()` API.
* [`react.md`](/react) — `<KlappayButton />` and `useKlappayOne()`.
* [`frameworks.md`](/frameworks) — Vue, Svelte, and anything else, since
  the core is a plain Web Component.
* [`modes.md`](/modes) — when you get an iframe/modal vs. a popup, and the
  automatic fallback between them.
* [`styling.md`](/styling) — `variant`/`size` and the CSS custom
  properties that cross the Shadow DOM boundary.
* [`errors.md`](/errors) — every error code, where each one comes from.
* [`protocol.md`](/protocol) — the `postMessage` wire format, the
  non-negotiable security invariants, and why `onSuccess` is never proof
  of payment.
* [`examples.md`](/examples) — full create-charge-then-render-button
  integrations, one per stack.

## For LLMs and agents

This site (built from these same files with VitePress) publishes
[`llms.txt`](/llms.txt) — a link index of every doc page — and
[`llms-full.txt`](/llms-full.txt) — the full content of every doc page
concatenated into one plain-text file. Point an agent, RAG pipeline, or MCP
server at either as a lightweight way to give it the whole package's
documentation without scraping HTML. Both regenerate on every deploy, so
they never drift from what's on this page.

---

---
url: https://js-one.klappay.com/button.md
---
# The button

Two zero-JavaScript entry points, both wired up by `core/klappay-one.ts`
under the hood — neither is a second implementation, both just build a
`KlappayOneConfig` from attributes and call `createKlappayOne(config).open()`.

## `<klappay-button>`

A real Custom Element (`customElements.define('klappay-button', ...)`),
rendered inside a Shadow DOM so neither the host page's CSS nor Klappay's
own leaks across the boundary:

```html
<klappay-button
  charge-id="ch_123"
  origin="https://klap.one"
  variant="black"
  size="md"
  locale="en"
  mode="iframe"
></klappay-button>
```

| Attribute | Required | Description |
| --- | --- | --- |
| `charge-id` | Yes | The `Charge` this checkout is for. |
| `origin` | Only if not [`configure()`'d](/getting-started#origin-one-way-or-another) | Which Klappay origin to open. |
| `variant` | No | `white` | `yellow` | `black` — defaults to `black`. See [Styling](/styling). |
| `size` | No | `sm` | `md` | `lg` — defaults to `md`. See [Styling](/styling). |
| `locale` | No | Forwarded to the checkout — falls back to `configure()`'s `locale`. |
| `mode` | No | `iframe` | `popup` — forces a mode instead of the [device default](/modes). |

`variant`/`size` are reactive — changing either attribute after the element
is already on the page (`el.setAttribute('variant', 'white')`) updates the
rendered button immediately, via `attributeChangedCallback`.

### Events

```ts
const button = document.querySelector('klappay-button')
button.addEventListener('success', (event) => console.log(event.detail)) // PaymentResult
button.addEventListener('error', (event) => console.log(event.detail)) // KlappayOneError
button.addEventListener('cancel', () => console.log('payer closed the checkout'))
```

A second click before the first checkout settles is ignored — the button
disables itself (`this.#button.disabled = true`) the moment it opens the
popup/iframe, and re-enables on whichever of `success`/`error`/`cancel`
fires first. That's what stops a fast double-click from opening two
popups/iframes stacked on top of each other.

Missing `charge-id` or `origin` (and no [`configure()`](/getting-started#origin-one-way-or-another)
default) logs a `console.error` and does nothing on click — it never
throws, so one misconfigured button on a page doesn't take the rest of the
page down with it.

## Your own button: `data-klappay-one`

For when you already have a button and don't want a second custom element
in your markup — any clickable element works, not just `<button>`:

```html
<button data-klappay-one="ch_123" data-klappay-one-origin="https://klap.one">
  Pay with Klappay
</button>
```

| Attribute | Required | Description |
| --- | --- | --- |
| `data-klappay-one` | Yes | The `chargeId` — also what marks the element for auto-wiring. |
| `data-klappay-one-origin` | Only if not [`configure()`'d](/getting-started#origin-one-way-or-another) | Which Klappay origin to open. |
| `data-klappay-one-locale` | No | Falls back to `configure()`'s `locale`. |
| `data-klappay-one-mode` | No | `iframe` | `popup` — forces a mode instead of the [device default](/modes). |

Same `success`/`error`/`cancel` `CustomEvent`s as `<klappay-button>` above,
dispatched on the element itself. There's no `variant`/`size` here — this
path renders nothing, it only adds a click handler to markup you already
control, so styling is entirely up to your own CSS.

While a checkout is in flight the element carries a `data-klappay-one-busy`
attribute (added on click, removed on `success`/`error`/`cancel`) — the
same double-click guard as `<klappay-button>`, just expressed as an
attribute instead of the native `disabled` property, since the wired
element isn't necessarily a form control.

```css
[data-klappay-one][data-klappay-one-busy] {
  opacity: 0.6;
  pointer-events: none;
}
```

### Elements added after the script loads

Both `wireExisting()` (run once on load) and a `MutationObserver`
(`observeNewElements()`, watching `document.body` for the lifetime of the
page) wire up `[data-klappay-one]` elements — so a button rendered by a
client-side router, injected by a third-party script, or added inside a
modal opened later all get wired automatically, with no manual
`re-wire()` call needed anywhere in your code.

## Choosing between the two

Reach for `<klappay-button>` when you want Klappay's own button styling
(pick a `variant`/`size` and move on) — it's the fastest path and the one
[the button preview in `klap-app`](https://github.com/klappay/klap-one)
matches exactly. Reach for `data-klappay-one` when the button already needs
to match a design system you don't control from here — your own markup,
your own CSS, this package only adds the click handler.

---

---
url: https://js-one.klappay.com/programmatic.md
---
# Programmatic API

For anything the two zero-JS entry points can't express — opening the
checkout from your own event handler, deferring `origin` resolution, or
building a fully custom trigger element — call `createKlappayOne()`
directly. `ui/klappay-button.ts` and `ui/auto-wire.ts` are themselves thin
callers into this exact function; there's no separate logic path hiding
behind the markup-based entry points.

```ts
import { createKlappayOne } from '@klappay/one'

const klappayOne = createKlappayOne({
  chargeId: 'ch_123',
  origin: 'https://klap.one',
  locale: 'en',
  mode: 'iframe',
  onReady: () => console.log('checkout loaded'),
  onSuccess: (result) => {
    // result: PaymentResult — see below. UX signal only, see /protocol.
  },
  onError: (error) => {
    // error: KlappayOneError — see /errors.
  },
  onCancel: () => console.log('payer closed the checkout'),
})

document.querySelector('#pay-button')!.addEventListener('click', () => {
  klappayOne.open()
})
```

## `KlappayOneConfig`

```ts
interface KlappayOneConfig {
  chargeId: string
  origin: string
  locale?: string
  mode?: 'iframe' | 'popup'
  onReady?: () => void
  onSuccess?: (result: PaymentResult) => void
  onError?: (error: KlappayOneError) => void
  onCancel?: () => void
}
```

| Field | Description |
| --- | --- |
| `chargeId` | Required. The `Charge` this checkout is for — created ahead of time on your backend. |
| `origin` | Required. Which Klappay origin to open — no default, since sandbox and production point at different hosts. |
| `locale` | Forwarded to the checkout. |
| `mode` | `'iframe'` | `'popup'` — forces a mode instead of the [device default](/modes). |
| `onReady` | Fires once the popup/iframe signals it has loaded (`klappay:ready`). Useful for hiding a loading spinner over the trigger button. |
| `onSuccess` | Fires with a `PaymentResult` once the payer completes payment. **Not proof of payment** — see [Protocol & security](/protocol#onsuccess-is-a-ux-signal-never-proof-of-payment). |
| `onError` | Fires with a `KlappayOneError` — see [Errors](/errors) for every code. |
| `onCancel` | Fires when the payer closes the popup/iframe without completing payment, by any means — an explicit Cancel button inside the checkout, the browser's native close button, alt-F4, swiping away a mobile popup. |

## `PaymentResult`

```ts
interface PaymentResult {
  txHash: string
  walletAddress: string
  network: string
  amount: string
  confirmedAt: string
}
```

Every field here is public on-chain data by the time this fires — a
transaction hash, a wallet address, which network, how much, and when it
confirmed. None of it is a secret, and none of it is a substitute for your
backend's own webhook-driven fulfillment.

## `open()`

```ts
interface KlappayOne {
  open: () => void
}
```

Calling `open()` again while a checkout from a previous `open()` call is
still in flight opens a second, independent popup/iframe — `createKlappayOne()`
itself does no de-duplication; that's what `ui/klappay-button.ts`'s
`disabled` guard and `ui/auto-wire.ts`'s `data-klappay-one-busy` guard exist
for on the two markup-based entry points. If you're calling `open()` from
your own click handler, guard it the same way:

```ts
let busy = false
button.addEventListener('click', () => {
  if (busy) return
  busy = true
  klappayOne.open()
})
// then clear `busy` in onSuccess/onError/onCancel
```

Each call to `open()` generates its own `requestId` (`crypto.randomUUID()`)
internally — that's what lets the bridge tell which `open()` call a given
`postMessage` response belongs to, so more than one `createKlappayOne()`
instance can safely coexist on the same page (e.g. one button per line
item in a cart). See [Protocol & security](/protocol) for the full wire
format.

## `configure()` / `getGlobalConfig()`

```ts
import { configure, getGlobalConfig } from '@klappay/one'

configure({ origin: 'https://klap.one', locale: 'en' })
getGlobalConfig() // -> { origin: 'https://klap.one', locale: 'en' }
```

Sets the page-wide default `origin`/`locale` that `<klappay-button>` and
`data-klappay-one` fall back to when they don't carry their own
`origin`/`locale` attribute. `createKlappayOne()` itself never reads this —
the programmatic API always requires `origin` explicitly, since it has no
natural attribute to fall back to and no excuse to make a required field
implicit.

---

---
url: https://js-one.klappay.com/react.md
---
# React

`@klappay/one/react` is a thin wrapper over `core/createKlappayOne` — it
doesn't reimplement anything, it just registers the same `<klappay-button>`
Custom Element used elsewhere and gives it idiomatic React props/events.
`react` is a peer dependency (`>=18`, optional) — nothing here loads unless
you actually `import` from the `/react` subpath.

## `<KlappayButton />`

```tsx
import { KlappayButton } from '@klappay/one/react'

function Checkout({ chargeId }: { chargeId: string }) {
  return (
    <KlappayButton
      chargeId={chargeId}
      origin="https://klap.one"
      variant="black"
      size="md"
      onSuccess={(result) => {
        // UX signal only — see /protocol.
        console.log('paid', result.txHash)
      }}
      onError={(error) => console.error(error.code, error.message)}
      onCancel={() => console.log('payer closed the checkout')}
    />
  )
}
```

```ts
interface KlappayButtonProps {
  chargeId: string
  origin?: string
  locale?: string
  variant?: KlappayButtonVariant
  size?: KlappayButtonSize
  onSuccess?: (result: PaymentResult) => void
  onError?: (error: KlappayOneError) => void
  onCancel?: () => void
}
```

Under the hood, `<KlappayButton />` renders the real `<klappay-button>`
element (via a `ref`) and attaches/detaches native
`success`/`error`/`cancel` event listeners in a `useEffect` — the same
events documented in [The button](/button), just handed to you as props
instead of `addEventListener` calls. `origin` is optional here only
because it can come from [`configure()`](/getting-started#origin-one-way-or-another)
instead; set one or the other before rendering.

## `useKlappayOne()`

For a fully custom trigger — your own button, a menu item, a keyboard
shortcut — skip the rendered element entirely and drive `open()` yourself:

```tsx
import { useKlappayOne } from '@klappay/one/react'

function BuyButton({ chargeId }: { chargeId: string }) {
  const klappayOne = useKlappayOne({
    chargeId,
    origin: 'https://klap.one',
    onSuccess: (result) => console.log('paid', result.txHash),
  })

  return <button onClick={() => klappayOne.open()}>Buy now</button>
}
```

`useKlappayOne()` keeps your latest `config` in a `ref` and always calls
`createKlappayOne()` fresh on `open()` — so passing a new inline
`onSuccess`/`onError` on every render (as in the example above) is fine and
doesn't need `useCallback`; it never creates a stale closure over an old
`chargeId` the way storing a single `createKlappayOne()` instance in
`useState` on mount would.

## TypeScript: the `<klappay-button>` JSX intrinsic

Importing from `@klappay/one/react` also augments the global JSX namespace
so `<klappay-button>` type-checks if you ever render the raw element
directly instead of going through `<KlappayButton />`:

```tsx
import '@klappay/one/react'

;<klappay-button charge-id="ch_123" origin="https://klap.one" variant="black" />
```

You won't normally need this — `<KlappayButton />` above covers the same
ground with proper React event props — but it's there for cases like
server-rendering the tag name directly or interop with a non-React tree
mounted alongside your app.

## Next.js and other SSR frameworks

Both `@klappay/one` and `@klappay/one/react` are safe to import anywhere
Node evaluates them — `registerKlappayButton()` no-ops when
`customElements`/`HTMLElement` don't exist (there's no browser to define
the element against), instead of throwing. Rendering `<klappay-button>`/
`<KlappayButton />` during SSR/static generation emits the plain tag as
inert markup; it becomes the real interactive button once the client
bundle loads and `registerKlappayButton()` runs for real, upgrading the
already-present element in place — the same progressive-enhancement
behavior undefined Custom Elements get natively.

That said, every example in this repo still keeps `@klappay/one` out of
the server render entirely (`next/dynamic({ ssr: false })` below, Nuxt's
`<ClientOnly>`, SvelteKit's `export const ssr = false` — see
[Other frameworks](/frameworks#server-side-rendering)) — not to dodge a
crash, but because a payment button has zero SSR value: there's nothing
to index, and skipping the inert-then-upgraded render avoids a visible
pop-in the instant hydration finishes. Treat the pattern below as a UX
default worth keeping, not a workaround you still need:

```tsx
'use client'

import dynamic from 'next/dynamic'

const KlappayButton = dynamic(() => import('@klappay/one/react').then((m) => m.KlappayButton), {
  ssr: false,
})

export function CheckoutButton({ chargeId }: { chargeId: string }) {
  return <KlappayButton chargeId={chargeId} origin={process.env.NEXT_PUBLIC_KLAP_ONE_ORIGIN!} />
}
```

One more wrinkle specific to webpack (Next's default bundler, as opposed
to Turbopack): `@klappay/one/react`'s `package.json` `exports` only
declares `types`/`import` conditions (ESM only, no `require`) — webpack's
resolver can fail on that combination specifically for a code-split
`import()` like the one `next/dynamic` generates. If you hit a resolution
error there, alias the subpath straight at the built file in
`next.config.ts`:

```ts
import path from 'node:path'
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@klappay/one/react': path.resolve(process.cwd(), 'node_modules/@klappay/one/dist/react/index.js'),
    }
    return config
  },
}

export default nextConfig
```

Every other framework with an SSR pass needs the equivalent of `ssr: false`
— see [Other frameworks](/frameworks) for Vue's `<ClientOnly>` and
SvelteKit's `export const ssr = false`. See
[Examples](/examples) for a full Next.js app with a Route Handler that
creates the `Charge` server-side, and the repo's
[`examples/nextjs/`](https://github.com/klappay/klap-one-js/tree/main/examples/nextjs)
for the complete, verified working files.

---

---
url: https://js-one.klappay.com/frameworks.md
---
# Other frameworks

`react/index.tsx` is the only framework wrapper this package ships — not
because other frameworks aren't supported, but because they don't need
one. `<klappay-button>` is a real
[Custom Element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements),
and `data-klappay-one` is a plain DOM attribute — both work natively in
every framework's own templating, with no adapter package required. Adding
a `vue/`/`svelte/` subpath here would just be a second implementation of
logic that already lives once in `core/`, which is exactly the kind of
duplication this package's own conventions rule out.

## Server-side rendering

Importing `@klappay/one`/`@klappay/one/react` in Node (SSR, static
generation, prerendering) is safe — `registerKlappayButton()` no-ops
when `customElements`/`HTMLElement` don't exist instead of throwing.
`<klappay-button>` renders as inert markup server-side and becomes the
real interactive button once the client bundle hydrates and registers it
for real — the same progressive-enhancement behavior an undefined Custom
Element gets natively in any browser.

Every framework example in this repo still keeps `@klappay/one` out of
the server render anyway — not to avoid a crash, but because a payment
button has zero SSR value (nothing to index) and skipping the
inert-then-upgraded render avoids a visible pop-in the instant hydration
finishes. Each framework's own mechanism for "this component is
browser-only":

* **Nuxt** — wrap the component in `<ClientOnly>` (see [Nuxt](#nuxt) below).
* **SvelteKit** — `export const ssr = false` in that route's `+page.ts`
  (see [SvelteKit](#sveltekit) below).
* **Next.js** — `next/dynamic(..., { ssr: false })`, see
  [React](/react#next-js-and-other-ssr-frameworks) for the full pattern
  (plus a webpack-resolver wrinkle specific to Next's default bundler,
  unrelated to the SSR question).
* **Plain Vue/Svelte/Angular without SSR** (a Vite SPA, for instance) —
  nothing to do here at all; none of this matters until something
  actually executes your components in Node before they reach a browser.

## Vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { configure } from '@klappay/one'

const props = defineProps<{ chargeId: string }>()
const button = ref<HTMLElement>()

configure({ origin: 'https://klap.one' })

function onSuccess(event: Event) {
  const result = (event as CustomEvent).detail
  console.log('paid', result.txHash)
}
</script>

<template>
  <klappay-button
    ref="button"
    :charge-id="props.chargeId"
    variant="black"
    size="md"
    @success="onSuccess"
  />
</template>
```

Vue's `@success` template syntax maps directly onto the native
`CustomEvent` dispatched by `<klappay-button>` (see [The button](/button))
— no wrapper needed. If your build tooling warns about an unknown custom
element, tell Vue's compiler to treat `klappay-button` as one:

```ts
// vite.config.ts
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'klappay-button',
        },
      },
    }),
  ],
})
```

### Nuxt

Nuxt renders every component server-side by default (Nitro's SSR).
Importing `@klappay/one` there [no longer crashes](#server-side-rendering),
but a payment button still has nothing worth server-rendering — wrap it in
Nuxt's built-in `<ClientOnly>` to skip straight to the client-only render:

```vue
<template>
  <ClientOnly>
    <klappay-button :charge-id="chargeId" @success="onSuccess" />
  </ClientOnly>
</template>
```

See the repo's
[`examples/nuxt/`](https://github.com/klappay/klap-one-js/tree/main/examples/nuxt)
for the complete, verified working app, including the
`vue.compilerOptions.isCustomElement` config from above wired into
`nuxt.config.ts`.

## Svelte

```svelte
<script lang="ts">
  import { configure } from '@klappay/one'

  export let chargeId: string

  configure({ origin: 'https://klap.one' })

  function onSuccess(event: CustomEvent) {
    console.log('paid', event.detail.txHash)
  }
</script>

<klappay-button charge-id={chargeId} variant="black" size="md" on:success={onSuccess} />
```

Svelte's `on:success` binds the same native `CustomEvent` directly — same
pattern as Vue above, no adapter package.

### SvelteKit

SvelteKit server-renders every route by default too. Importing
`@klappay/one` there [no longer crashes](#server-side-rendering), but same
reasoning as Nuxt above — opt that specific route out of SSR in its
`+page.ts` rather than render an inert button that only pops in once
hydrated:

```ts
// src/routes/checkout/+page.ts
export const ssr = false
```

This makes the route (and everything it imports, including
`@klappay/one`) render client-only, same effect as Nuxt's `<ClientOnly>`
above — just expressed as a route-level flag instead of a wrapper
component, since SvelteKit's SSR opt-out is per-route, not per-component.
See the repo's
[`examples/sveltekit/`](https://github.com/klappay/klap-one-js/tree/main/examples/sveltekit)
for the complete, verified working app.

## Angular

```html
<klappay-button
  [attr.charge-id]="chargeId"
  variant="black"
  size="md"
  (success)="onSuccess($event)"
></klappay-button>
```

```ts
@Component({
  selector: 'app-checkout',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  templateUrl: './checkout.component.html',
})
export class CheckoutComponent {
  onSuccess(event: CustomEvent) {
    console.log('paid', event.detail.txHash)
  }
}
```

`CUSTOM_ELEMENTS_SCHEMA` tells Angular's template compiler `klappay-button`
is an intentional custom element, not a typo'd component selector.

## No framework at all

The two markup-based entry points in [The button](/button) — `<klappay-button>`
and `data-klappay-one` — need nothing beyond the `<script>` tag itself; see
[Getting started](/getting-started) and the
[vanilla example](/examples#vanilla-no-bundler) for the complete picture.

## The pattern to notice

Every snippet above does the same three things: load `@klappay/one` (script
tag or `import`), render the tag or attribute your framework already
understands, and listen for the same `success`/`error`/`cancel`
`CustomEvent`s documented in [The button](/button). There's no framework-
specific state machine to get subtly wrong, because there isn't a second
one to write — `core/klappay-one.ts` is the only place `open()`,
`postMessage` listening, and mode selection are implemented, no matter
which of the entry points above triggers it.

---

---
url: https://js-one.klappay.com/modes.md
---
# iframe vs. popup

`createKlappayOne()` picks one of two renderers before every `open()`
call: an iframe/modal, or a popup. Both talk the exact same
[bridge protocol](/protocol) and accept the exact same
[`KlappayOneConfig`](/programmatic) — the only difference is how the
checkout is mounted, chosen for you unless you override it.

## The default

```ts
function resolveMode(config) {
  return config.mode ?? (isMobileUserAgent(navigator.userAgent) ? 'popup' : 'iframe')
}
```

* **Desktop → iframe/modal.** A backdrop-dismissible overlay, isolated in
  Shadow DOM so neither your page's CSS nor Klappay's leaks across the
  boundary (see `core/iframe.ts`).
* **Mobile → popup.** Detected by user agent (`Android|iPhone|iPad|iPod`),
  mirroring `klap-one`'s own `web/src/lib/is-mobile.ts` heuristic exactly.
  Mobile defaults to a popup because whether a backgrounded iframe's
  WalletConnect relay connection survives the OS switching to the wallet
  app and back hasn't been verified — a top-level popup tab doesn't have
  that risk.

Pass `mode: 'iframe' | 'popup'` in config (or the `mode` /
`data-klappay-one-mode` attribute) to force one or the other regardless of
device:

```ts
createKlappayOne({ chargeId, origin, mode: 'popup' })
```

## The automatic iframe → popup fallback

If a merchant's Content-Security-Policy blocks `frame-src`/`child-src` for
Klappay's origin, an iframe would otherwise sit there blank forever with
no way for the payer to tell what went wrong. `openViaIframe()` guards
against exactly that: if the frame never sends a `klappay:ready` message
within `READY_TIMEOUT_MS` (10 seconds), it automatically retries the same
checkout as a popup before giving up. Only if the popup attempt *also*
times out (or gets blocked) does `onError` finally fire with
`FRAME_TIMEOUT` — see [Errors](/errors).

This fallback only exists on the iframe path. A popup that's actually
blocked by the browser is detected immediately (`popup === null || popup.closed`
right after `window.open()`), so there's no equivalent "popup → iframe"
fallback to build — a blocked popup fails fast with `POPUP_BLOCKED`
instead of waiting out a timeout.

## Detecting a closed popup

Unlike an iframe (which fires a real `postMessage` on cancel from an
in-page Cancel button), a popup can be closed by means the page inside it
never gets a chance to react to — the browser's native close button,
alt-F4, swiping it away on mobile. `createKlappayOne()` polls
`popup.closed` every 500ms for exactly that reason (the same fallback
OAuth-popup libraries use) and fires `onCancel` the moment it detects the
popup is gone, even if no `klappay:cancel` message ever arrived.

## Dismissing the iframe

Clicking the semi-transparent backdrop behind the iframe reports as a
cancel, same as closing a popup does — `event.target === backdrop` is
checked so clicks that land on the iframe itself (or bubble from inside
it, which they can't, being cross-origin) never trigger a false dismiss.

A backdrop-dismiss click and a genuine `postMessage` (a real `success`/
`error`/`cancel` arriving the same tick) can race — a `settled` guard
inside `openViaIframe()` makes sure your config's callbacks fire exactly
once per checkout no matter which trigger wins that race.

## Resizing

The iframe starts at a fixed `420×720` and resizes in response to
`klappay:resize` messages the checkout sends as its own content's height
changes — you never need to guess a height up front or leave dead
whitespace around a shorter step in the flow (e.g. an error screen).

---

---
url: https://js-one.klappay.com/styling.md
---
# Styling

Only the **button** this package renders is customizable — the popup/
iframe content (`one-id`) never is. Klappay One isn't a white-label
product: a payer needs to recognize "this is Klappay asking me for
approval," the same way Apple Pay/Google Pay buttons only ever vary
color/size, never the branding behind them. See
[Protocol & security](/protocol#the-popupiframe-content-is-never-white-labeled)
for why that boundary is a non-negotiable invariant, not just a current
limitation.

## `variant` and `size`

Three color presets, three sizes — deliberately not an arbitrary color
system (no `primaryColor: '#ff00ff'`):

```html
<klappay-button charge-id="ch_123" variant="black" size="md"></klappay-button>
```

| `variant` | Background | Text |
| --- | --- | --- |
| `white` (default background) | `#ffffff` | `#111111` |
| `yellow` | `#f2b90c` | `#111111` |
| `black` (default) | `#111111` | `#ffffff` |

| `size` | Height |
| --- | --- |
| `sm` | `32px` |
| `md` (default) | `40px` |
| `lg` | `48px` |

Both attributes are reactive — changing them after the element is mounted
updates the rendered button immediately, no re-render/remount needed.

## CSS custom properties across the Shadow DOM boundary

`<klappay-button>` renders inside a Shadow DOM, isolating your page's CSS
from leaking into the button (and vice versa) — a generic `button { ... }`
rule on your page can't accidentally break Klappay's button just by
existing. A handful of CSS custom properties are the one thing
deliberately exposed to cross that boundary, enough to fit the button into
your page's design without opening the door to reimplementing the whole
component:

```css
klappay-button {
  --klappay-radius: 4px;
  --klappay-font-family: 'Inter', sans-serif;
  --klappay-button-height: 44px;
  --klappay-background: #2563eb;
  --klappay-color: #ffffff;
}
```

| Property | Affects |
| --- | --- |
| `--klappay-radius` | Corner radius (default `8px`). |
| `--klappay-font-family` | Font stack (default `system-ui, sans-serif`). |
| `--klappay-button-height` | Overrides the `size` preset's height. |
| `--klappay-background` | Overrides the `variant` preset's background. |
| `--klappay-color` | Overrides the `variant` preset's text color. |

`--klappay-background`/`--klappay-color` still key off whichever `variant`
you set — they override that variant's colors specifically, they don't
replace the variant system with an unbounded one. If you need a color
outside the three presets entirely, set `variant="black"` (or any) and
override both properties together, as in the example above.

## Your own button (`data-klappay-one`)

The [`data-klappay-one`](/button#your-own-button-data-klappay-one) path
renders nothing of its own — it only adds a click handler to markup you
already control. There's no Shadow DOM, no `variant`/`size`, and no CSS
custom properties to reach for: style the element with your own CSS the
same way you'd style any other button on your page.

```css
[data-klappay-one] {
  border-radius: 4px;
  font-family: 'Inter', sans-serif;
}
[data-klappay-one][data-klappay-one-busy] {
  opacity: 0.6;
  pointer-events: none;
}
```

---

---
url: https://js-one.klappay.com/errors.md
---
# Errors

```ts
interface KlappayOneError {
  code: string
  message: string
}
```

`code` is deliberately an open string, not a fixed union type. Most codes
come from `one-id`'s own bridge and can grow over time without a matching
release of this package — treat `code` as a value to log/branch on for the
handful you specifically care about, not an exhaustive list to switch over.

## Codes this package generates itself

Only two — everything else in `onError` originates on Klappay's side and
is forwarded verbatim.

| Code | When | Where |
| --- | --- | --- |
| `POPUP_BLOCKED` | `window.open()` returned `null`, or the returned window is already `.closed` — the browser's popup blocker stepped in. Only reachable on the popup path (mobile default, or `mode: 'popup'`). | `core/klappay-one.ts` |
| `FRAME_TIMEOUT` | No `klappay:ready` message arrived within 10 seconds. On the iframe path, this only fires *after* the [automatic popup fallback](/modes#the-automatic-iframe-popup-fallback) also times out — a CSP blocking the frame doesn't stop there, it retries as a popup first. | `core/klappay-one.ts` / `core/bridge.ts` |

```ts
onError: (error) => {
  if (error.code === 'POPUP_BLOCKED') {
    showMessage('Please allow popups for this site and try again.')
    return
  }
  if (error.code === 'FRAME_TIMEOUT') {
    showMessage('The checkout failed to load. Check your network and try again.')
    return
  }
  showMessage(error.message)
}
```

## Codes from `one-id`

Everything else — `payment_failed`, `wallet_error`, and any code
`one-id`'s own identity/wallet/payment flow raises — is relayed through
`core/bridge.ts` unchanged, as a `klappay:error` message. This package
never inspects or transforms those codes; they're validated for shape
(`code`/`message` both present) but not for a specific known set. Building
a fixed union type here would mean every new error `one-id` introduces
needs a matching release of `@klappay/one` just to keep types accurate —
an open `string` avoids that coupling entirely.

For a UI that wants to handle more than the two codes above, fall back to
displaying `error.message` (already a payer-facing string) for anything
that isn't `POPUP_BLOCKED`/`FRAME_TIMEOUT` specifically, rather than
hard-coding a `switch` over codes that may not exist yet.

## `onCancel` is not an error

Closing the popup/iframe without completing payment — by any means, see
[iframe vs. popup](/modes) — fires `onCancel`, never `onError`. There's no
`code` for "the payer changed their mind"; that's an expected outcome,
not a failure one.

---

---
url: https://js-one.klappay.com/protocol.md
---
# Protocol & security

`@klappay/one` runs in a merchant's own page — a completely different
threat model than a package that only ever touches a trusted backend's own
secrets. Everything below is this package's own `CLAUDE.md` non-negotiable
invariants, written out in full — not defaults you can configure away.

## What this package never has access to

* **A private key.** The payer's own wallet app signs everything — that
  happens entirely inside `one-id` (a different origin, a different
  repo). This package never proposes or builds a transaction itself.
* **A session token.** The payer's session lives in `one-id`'s own cookie,
  on Klappay's origin — this package never reads or stores anything from
  that popup/iframe beyond the public `PaymentResult` it relays via
  `postMessage`.

If you ever find yourself reaching for a private key or a session token
inside application code that imports `@klappay/one`, that's a sign the
design needs to change, not that this package needs a new escape hatch.

## The `postMessage` wire format

The same contract `one-js` and `one-id` both implement — canonical here,
mirrored by hand on the `klap-one` side (`web/src/lib/bridge.ts`), since
there's no shared package between the two repos to enforce it:

```ts
type BridgeMessage =
  | { type: 'klappay:ready'; requestId: string }
  | { type: 'klappay:resize'; requestId: string; height: number }
  | { type: 'klappay:success'; requestId: string; result: PaymentResult }
  | { type: 'klappay:error'; requestId: string; error: { code: string; message: string } }
  | { type: 'klappay:cancel'; requestId: string }
```

* **`chargeId`/`requestId`/`locale`/`returnOrigin` travel in the popup/
  iframe URL itself** (`/id/?chargeId=X&requestId=Y&locale=en&returnOrigin=https://merchant.com`)
  — none of these values are secret, and putting them in the URL avoids a
  race a bidirectional handshake would otherwise have ("did my config
  `postMessage` arrive before the page was ready?"). `postMessage` only
  carries the **return** path, `one-id` → `one-js`.
* **`requestId`** is generated fresh by `core/klappay-one.ts`
  (`crypto.randomUUID()`, not a secret) on every `open()` call — it's what
  lets a single page with more than one button/charge tell which `open()`
  call a given response belongs to.
* **Every message the checkout sends targets `returnOrigin` specifically**
  as its `postMessage` `targetOrigin` (never `'*'`) — defense in depth,
  since nothing in these messages is actually secret (a public `txHash`, a
  public wallet address, an error code), but there's still no reason to
  use a wildcard target when the real one is already known.

## `core/bridge.ts` validates every message before trusting it

This is the specific invariant this repository's own test suite exists to
protect (`src/core/bridge.test.ts`):

```ts
function onMessage(event: MessageEvent): void {
  if (event.origin !== klapOneOrigin) return
  if (!isBridgeMessage(event.data) || event.data.requestId !== requestId) return
  // ... only now is event.data trusted
}
```

Two checks, both required, in this order:

1. **`event.origin` must match the configured Klappay origin exactly.**
   A message from any other origin — including a malicious page that
   somehow gets a reference to your window — is silently dropped.
2. **`event.data.requestId` must match the specific `open()` call in
   flight.** Even a genuine message from the correct origin, but for a
   *different* checkout (a stale popup left open, or a second button on
   the same page), is silently dropped rather than partially trusted.

A message failing either check is dropped with no error surfaced and no
partial trust extended — it's simply as if the message never arrived, not
a degraded "trust some of it" path.

## The popup/iframe content is never white-labeled

`variant`/`size` only ever style the **button** this package renders —
`one-id`'s own content inside the popup/iframe is 100% Klappay's, always,
on every integration, with no merchant branding/logo anywhere in it. This
isn't a missing feature; it's deliberate, the same reasoning Apple Pay and
Google Pay apply to their own buttons: a payer needs to recognize "this is
Klappay asking me for approval" regardless of which merchant embedded the
button. See [Styling](/styling) for the actual customization surface.

## `onSuccess` is a UX signal, never proof of payment

The same principle Stripe applies to its own webhook: **never release a
product because the browser said "it worked."** The tab can close mid-flow,
the network can drop the confirmation, and a callback is trivially easy for
an integrator to misuse as if it were authoritative. `onSuccess` exists for
UX — show a "Paid!" screen, redirect to a thank-you page — while real
fulfillment (releasing the product, marking an order paid in your own
database) has to come from Klappay Core's own `charge.confirmed` webhook,
the same webhook system Core uses for everything else.

```ts
// WRONG — releases the product based only on the client-side callback
onSuccess: (result) => releaseProductDirectly(result.txHash)

// RIGHT — onSuccess only drives UX; your backend releases the product
// once it receives Klappay Core's charge.confirmed webhook
onSuccess: (result) => {
  showThankYouScreen(result.txHash)
  router.push(`/order/awaiting-confirmation?tx=${result.txHash}`)
}
```

See `@klappay/node`'s [webhook verification](https://node-sdk.klappay.com/webhooks)
docs for constructing and verifying that event server-side.

## No `eval`/`Function` over anything from the network

The button's markup/CSS is a static template compiled into this package's
build (`ui/klappay-button.ts`'s `#css()`, `core/iframe.ts`'s `css()`) —
never HTML built from an API response. There's no code path in this
package that interprets a string from a network response as executable
code or markup.

## Mirrored, not shared

`core/bridge.ts`'s `BridgeMessage` type mirrors `klap-one`'s own
`web/src/lib/bridge.ts` by hand — there's no shared package between the
two repositories enforcing the two stay in sync, since `one-js` ships to
npm/a public CDN and `klap-one`'s backend code never should. Any change to
the wire format has to land in both places deliberately.

---

---
url: https://js-one.klappay.com/examples.md
---
# Examples

Full create-a-charge-then-render-a-button integrations, one per stack. All
four follow the same shape: a tiny backend creates a `Charge` with
[`@klappay/node`](https://node-sdk.klappay.com) (your `KLAP_API_KEY` never
reaches the browser), then hands the resulting `chargeId` to `@klappay/one`
on the client.

Want to clone and run one instead of reading it here? See
[`examples/`](https://github.com/klappay/klap-one-js/tree/main/examples) in
the repo — four standalone, `pnpm install && pnpm dev`-ready apps. Each
always depends on `@klappay/one`'s `latest` npm release, so they double as
a live integration check, not a frozen snapshot — see the repo's own
[`examples/README.md`](https://github.com/klappay/klap-one-js/tree/main/examples#readme)
for the "test against local, unpublished changes" workflow and the CI
fallback behind it.

## Vanilla (no bundler)

Mirrors `klap-checkout`'s own zero-build setup — the `<script>` tag build
straight from `node_modules`, no `import` resolution in the browser at
all:

```ts
// src/server.ts — Hono
import { serveStatic } from '@hono/node-server/serve-static'
import { Hono } from 'hono'
import { createClient } from '@klappay/node'

const klap = createClient({
  apiKey: process.env.KLAP_API_KEY!,
  baseUrl: process.env.KLAP_BASE_URL!,
})

const app = new Hono()

// The IIFE build, served straight from node_modules — always matches
// whatever version is actually installed, no copying into ./public.
app.use(
  '/vendor/one/*',
  serveStatic({
    root: './node_modules/@klappay/one/dist',
    rewriteRequestPath: (path) => path.replace(/^\/vendor\/one/, ''),
  }),
)

app.post('/api/charges', async (c) => {
  const charge = await klap.charges.create({
    amount: 25,
    currency: 'USD',
    expiresIn: 3600,
    acceptedPayments: [{ token: 'USDC', network: 'base' }],
  })
  return c.json({ chargeId: charge.id })
})

export { app }
```

```html
<!-- public/index.html -->
<script src="/vendor/one/index.global.js"></script>
<button id="pay">Pay $25</button>
<script>
  document.getElementById('pay').addEventListener('click', async () => {
    const { chargeId } = await fetch('/api/charges', { method: 'POST' }).then((r) => r.json())
    KlappayOne.createKlappayOne({
      chargeId,
      origin: 'https://klap.one',
      onSuccess: (result) => alert(`Paid! ${result.txHash}`),
      onError: (error) => alert(error.message),
    }).open()
  })
</script>
```

See [The button](/button) for the zero-JS `<klappay-button>` / `data-klappay-one`
alternatives to the manual `createKlappayOne()` call above — either works
equally well once the script tag is loaded this way.

## Next.js (App Router)

A Route Handler for charge creation, a Client Component for the button —
see [React](/react) for why `<KlappayButton />` needs a `'use client'`
boundary.

`lib/klap.ts`:

```ts
import { createClient } from '@klappay/node'

export const klap = createClient({
  apiKey: process.env.KLAP_API_KEY!,
  baseUrl: process.env.KLAP_BASE_URL!,
})
```

`app/api/charges/route.ts`:

```ts
import { NextResponse } from 'next/server'
import { klap } from '@/lib/klap'

export async function POST() {
  const charge = await klap.charges.create({
    amount: 25,
    currency: 'USD',
    expiresIn: 3600,
    acceptedPayments: [{ token: 'USDC', network: 'base' }],
  })
  return NextResponse.json({ chargeId: charge.id })
}
```

`app/checkout/CheckoutButton.tsx`:

```tsx
'use client'

import { useState } from 'react'
import { KlappayButton } from '@klappay/one/react'

export function CheckoutButton() {
  const [chargeId, setChargeId] = useState<string | null>(null)

  if (!chargeId) {
    return (
      <button
        onClick={async () => {
          const res = await fetch('/api/charges', { method: 'POST' })
          const data = await res.json()
          setChargeId(data.chargeId)
        }}
      >
        Start checkout
      </button>
    )
  }

  return (
    <KlappayButton
      chargeId={chargeId}
      origin={process.env.NEXT_PUBLIC_KLAP_ONE_ORIGIN!}
      onSuccess={(result) => console.log('paid', result.txHash)}
    />
  )
}
```

## Nuxt

Nitro server route for charge creation, a Vue component around the raw
`<klappay-button>` element — see [Other frameworks](/frameworks#vue) for
the `isCustomElement` compiler option Nuxt needs.

`server/api/charges.post.ts`:

```ts
import { createClient } from '@klappay/node'

const klap = createClient({
  apiKey: process.env.KLAP_API_KEY!,
  baseUrl: process.env.KLAP_BASE_URL!,
})

export default defineEventHandler(async () => {
  const charge = await klap.charges.create({
    amount: 25,
    currency: 'USD',
    expiresIn: 3600,
    acceptedPayments: [{ token: 'USDC', network: 'base' }],
  })
  return { chargeId: charge.id }
})
```

`app/components/CheckoutButton.vue`:

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { configure } from '@klappay/one'

const chargeId = ref<string | null>(null)
configure({ origin: useRuntimeConfig().public.klapOneOrigin })

async function start() {
  const data = await $fetch('/api/charges', { method: 'POST' })
  chargeId.value = data.chargeId
}

function onSuccess(event: Event) {
  console.log('paid', (event as CustomEvent).detail.txHash)
}
</script>

<template>
  <button v-if="!chargeId" @click="start">Start checkout</button>
  <klappay-button v-else :charge-id="chargeId" @success="onSuccess" />
</template>
```

## SvelteKit

A `+server.ts` route for charge creation, the raw `<klappay-button>`
element directly in the Svelte template:

`src/routes/api/charges/+server.ts`:

```ts
import { json } from '@sveltejs/kit'
import { createClient } from '@klappay/node'
import { KLAP_API_KEY, KLAP_BASE_URL } from '$env/static/private'

const klap = createClient({ apiKey: KLAP_API_KEY, baseUrl: KLAP_BASE_URL })

export async function POST() {
  const charge = await klap.charges.create({
    amount: 25,
    currency: 'USD',
    expiresIn: 3600,
    acceptedPayments: [{ token: 'USDC', network: 'base' }],
  })
  return json({ chargeId: charge.id })
}
```

`src/routes/checkout/+page.svelte`:

```svelte
<script lang="ts">
  import { configure } from '@klappay/one'
  import { PUBLIC_KLAP_ONE_ORIGIN } from '$env/static/public'

  let chargeId: string | null = null
  configure({ origin: PUBLIC_KLAP_ONE_ORIGIN })

  async function start() {
    const res = await fetch('/api/charges', { method: 'POST' })
    const data = await res.json()
    chargeId = data.chargeId
  }

  function onSuccess(event: CustomEvent) {
    console.log('paid', event.detail.txHash)
  }
</script>

{#if !chargeId}
  <button on:click={start}>Start checkout</button>
{:else}
  <klappay-button charge-id={chargeId} on:success={onSuccess} />
{/if}
```

## Every example uses the public `/v1` API

Same as `@klappay/node`/`@klappay/checkout-kit`'s own examples: every
example above calls `klap.charges.create()` against Core's public,
API-key-authenticated `/v1` surface — the same access any external
merchant integration has. That means each example only ever creates
charges under the `KLAP_API_KEY` you provide; see each example's own
README for exactly which environment variables to set before running it.