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

# Frontend packages

> Props and handles for the browser and native SDKs — @pulsebyshiga/collect-js, @pulsebyshiga/collect-react, and @pulsebyshiga/collect-react-native.

The client packages render the payment moment. The hosted embed
(`collect-js` / `<PulseCollectPayment>`) runs inside a Pulse-controlled iframe or
WebView and takes a session token (`cs_*`); the in-app SDK (`<PulseCheckout>`)
renders in your own DOM with an API key. See
[Choose a model](/render/choose-a-model) for the trade-off.

<Tabs>
  <Tab title="collect-js">
    The framework-agnostic loader. See [Embedded iframe](/render/embedded-iframe).

    ## PulseCollect.mount(target, options)

    ```ts theme={null}
    import PulseCollect, { useSession } from '@pulsebyshiga/collect-js';

    const handle = PulseCollect.mount(document.getElementById('pay')!, {
      auth: useSession(sessionToken),
      onSuccess: (orderId) => {/* UX signal only — credit off the webhook */},
    });
    ```

    `target` is the `HTMLElement` to mount into. Returns an `EmbedHandle`.

    ### Options — MountOptions

    <ParamField path="sessionToken" type="string">
      The browser-safe credential: a single-order session token (`cs_*`). Pass
      this or `auth`.
    </ParamField>

    <ParamField path="auth" type="ClientAuth">
      Alternative to `sessionToken` — the result of `useSession(cs_…)`.
    </ParamField>

    <ParamField path="embedUrl" type="string">
      Embed origin override — local dev or a partner-subdomain deployment.
    </ParamField>

    <ParamField path="apiUrl" type="string">
      API base the embed calls with the session token.
    </ParamField>

    <ParamField path="component" type="&#x22;payment&#x22; | &#x22;quote&#x22; | &#x22;status&#x22;" default="payment">
      Which piece to render: the full payment flow, a live quote only, or a
      status view only.
    </ParamField>

    <ParamField path="flow" type="&#x22;select&#x22; | &#x22;direct&#x22;" default="select">
      `select`: the user picks asset + network inside the embed. `direct`: skip
      selection and use the values pinned at session creation.
    </ParamField>

    <ParamField path="networks" type="string[]">
      Narrow the selectable networks. Intersected with the partner's dashboard
      config — a mount can only narrow further, never re-enable a removed
      network.
    </ParamField>

    <ParamField path="assets" type="string[]">
      Narrow the payable assets. Same narrowing rules as `networks`.
    </ParamField>

    <ParamField path="theme" type="EmbedTheme">
      Brand tokens (see [Theming](/render/theming)).
    </ParamField>

    <ParamField path="strings" type="EmbedStrings">
      Copy overrides for the money-moment states.
    </ParamField>

    <ParamField path="readyTimeoutMs" type="number" default="15000">
      Ms to wait for the embed's ready signal before `onError("embed_load_timeout")`.
    </ParamField>

    <ParamField path="onReady" type="() => void" />

    <ParamField path="onStatusChange" type="(status: EmbedStatus, orderId: string) => void" />

    <ParamField path="onSuccess" type="(orderId: string) => void">
      UX signal only — credit a customer off the verified webhook, not this.
    </ParamField>

    <ParamField path="onQuoteExpired" type="() => void" />

    <ParamField path="onQuoteRefreshed" type="(lockedUntil: string) => void" />

    <ParamField path="onError" type="(code: string, message: string) => void" />

    ### Returned handle — EmbedHandle

    <ResponseField name="iframe" type="HTMLIFrameElement">
      The mounted iframe element.
    </ResponseField>

    <ResponseField name="unmount" type="() => void">
      Remove the iframe and detach the message listener.
    </ResponseField>

    ### useSession(sessionToken)

    Wraps a single-order session token into `ClientAuth` for `mount` /
    `<PulseCollectPayment>`. There is deliberately no `useApiKey` here — an API
    key must never ship to a browser.
  </Tab>

  <Tab title="collect-react">
    React bindings. Peer dependency: `react >=18`.

    ## \<PulseCollectPayment>

    The hosted embed as a React component. Props are all
    [`MountOptions`](#options-mountoptions) above, plus:

    <ParamField path="className" type="string" />

    <ParamField path="style" type="CSSProperties" />

    Renders a container div and mounts the Pulse-controlled iframe into it;
    remounts only when the session (or `embedUrl` / `apiUrl`) changes. See
    [Embedded iframe](/render/embedded-iframe).

    ## \<PulseCheckout>

    In-app modal that renders the Pulse UI in your own DOM and talks to Pulse
    directly in `apiKey` mode. See [In-app checkout](/render/in-app-checkout).

    <ParamField path="auth" type="PulseAuth" required>
      `apiKey` mode (client → Pulse directly). Use `useApiKey`.
    </ParamField>

    <ParamField path="request" type="CheckoutRequest | null">
      The order to transact. Non-null → the modal opens; null/undefined →
      closed. The integrator owns this state.
    </ParamField>

    <ParamField path="baseUrl" type="string">Override the embed/engine host (e.g. a local or sandbox server).</ParamField>

    <ParamField path="fetchImpl" type="FetchLike" />

    <ParamField path="pollMs" type="number" default="2500">Status poll interval.</ParamField>

    <ParamField path="theme" type="EmbedTheme" />

    <ParamField path="strings" type="EmbedStrings" />

    <ParamField path="onStatusChange" type="(status: EmbedStatus, orderId: string) => void" />

    <ParamField path="onSuccess" type="(orderId: string) => void" />

    <ParamField path="onError" type="(code: string, message: string) => void" />

    <ParamField path="onClose" type="() => void">
      Fired by the × button and Esc. Omit → no ×, Esc inert (fully
      parent-controlled).
    </ParamField>

    <ParamField path="className" type="string" />

    <ParamField path="style" type="CSSProperties" />

    ## \<PulseRate>

    Drop-in rate line. Props are the `useRate` params and options below, plus:

    <ParamField path="className" type="string" />

    <ParamField path="children" type="(result: UseRateResult) => ReactNode">
      Custom renderer. Omit for the built-in `1 {from} = {rate} {to}` line.
    </ParamField>

    ## useRate(params, options?)

    Reads the live rate without creating an order — calls your backend proxy of
    `rates.preview` (or a custom `fetcher`). No API key touches the browser.

    **params — RateParams**

    <ParamField path="from" type="string" required />

    <ParamField path="to" type="string" required />

    <ParamField path="amount" type="string" required />

    <ParamField path="network" type="string" />

    **options — UseRateOptions**

    <ParamField path="endpoint" type="string" default="/api/pulse/rate">
      Your backend route that proxies `pulse.rates.preview` and returns a
      `RatePreview` JSON body.
    </ParamField>

    <ParamField path="fetcher" type="(params: RateParams) => Promise<RatePreview>">
      Custom transport (tRPC, GraphQL, …). Overrides `endpoint`.
    </ParamField>

    <ParamField path="refreshMs" type="number">
      Re-fetch every N ms to keep the locked rate fresh. Off by default.
    </ParamField>

    <ParamField path="enabled" type="boolean">
      Gate fetching. Defaults to true whenever `amount` is non-empty.
    </ParamField>

    **Returns — UseRateResult**

    <ResponseField name="data" type="RatePreview | null">
      `{ rate, youSend, youReceive, expiresAt, quoteId? }`.
    </ResponseField>

    <ResponseField name="loading" type="boolean" />

    <ResponseField name="error" type="Error | null" />

    <ResponseField name="refresh" type="() => void" />
  </Tab>

  <Tab title="collect-react-native">
    Same hosted embed inside a `react-native-webview` `WebView`. Peer
    dependencies: `react >=18` and `react-native-webview >=13`. See
    [React Native](/testing/react-native).

    ## \<PulseCollectPayment>

    <ParamField path="sessionToken" type="string" required>
      Single-order session token from the partner backend.
    </ParamField>

    <ParamField path="embedUrl" type="string" />

    <ParamField path="apiUrl" type="string" />

    <ParamField path="flow" type="&#x22;select&#x22; | &#x22;direct&#x22;" default="select">
      `select`: in-embed asset/network selection; `direct`: pinned.
    </ParamField>

    <ParamField path="networks" type="string[]">
      Narrow selectable networks (intersected with the partner config; never
      widens).
    </ParamField>

    <ParamField path="assets" type="string[]">
      Narrow payable assets (same narrowing rules as `networks`).
    </ParamField>

    <ParamField path="theme" type="EmbedTheme" />

    <ParamField path="strings" type="EmbedStrings">Copy overrides travel via URL params on React Native.</ParamField>

    <ParamField path="style" type="unknown">
      WebView style. When omitted, height follows the embed content.
    </ParamField>

    ### Callbacks — EmbedCallbacks

    Delivered through the WebView message bridge.

    <ParamField path="onReady" type="() => void" />

    <ParamField path="onStatusChange" type="(status: EmbedStatus, orderId: string) => void" />

    <ParamField path="onSuccess" type="(orderId: string) => void" />

    <ParamField path="onQuoteExpired" type="() => void" />

    <ParamField path="onQuoteRefreshed" type="(lockedUntil: string) => void" />

    <ParamField path="onError" type="(code: string, message: string) => void" />

    <ParamField path="onResize" type="(height: number) => void" />
  </Tab>
</Tabs>

## Shared embed types

Exported from `@pulsebyshiga/collect-js` and re-exported by the React packages.

<ResponseField name="EmbedStatus" type="string union">
  `loading`, `awaiting_payment`, `deposit_detected`, `deposit_confirmed`,
  `converting`, `completed`, `underpaid`, `overpaid`, `wrong_chain`, `expired`,
  `failed`.
</ResponseField>

<ResponseField name="EmbedComponent" type="string union">
  `payment`, `quote`, `status`.
</ResponseField>

<ResponseField name="EmbedTheme" type="object">
  Brand tokens — `primaryColor`, `borderRadius`, `mode`, `fontFamily`,
  `inkColor`, `mutedColor`, `backgroundColor`, `buttonTextColor`, `lineColor`,
  `successColor`, `dangerColor`, `pageBackgroundColor`, `density`, `minHeight`,
  `attribution`. See [Theming](/render/theming).
</ResponseField>

<ResponseField name="EmbedStrings" type="object">
  Copy overrides — `title`, `subtitle`, `heroLabel`, `successTitle`,
  `successSubtitle`, `expiredTitle`, `expiredSubtitle`, `refreshButton`,
  `copyButton`, `copiedButton`.
</ResponseField>