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 for the trade-off.

collect-js

The framework-agnostic loader. See Embedded iframe.

PulseCollect.mount(target, options)

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

sessionToken · string

The browser-safe credential: a single-order session token (cs_*). Pass this or auth.

auth · ClientAuth

Alternative to sessionToken — the result of useSession(cs_…).

embedUrl · string

Embed origin override — local dev or a partner-subdomain deployment.

apiUrl · string

API base the embed calls with the session token.

component · "payment" | "quote" | "status" · default: "payment"

Which piece to render: the full payment flow, a live quote only, or a status view only.

flow · "select" | "direct" · default: "select"

select: the user picks asset + network inside the embed. direct: skip selection and use the values pinned at session creation.

networks · string[]

Narrow the selectable networks. Intersected with the partner’s dashboard config — a mount can only narrow further, never re-enable a removed network.

assets · string[]

Narrow the payable assets. Same narrowing rules as networks.

theme · EmbedTheme

Brand tokens (see Theming).

strings · EmbedStrings

Copy overrides for the money-moment states.

readyTimeoutMs · number · default: "15000"

Ms to wait for the embed’s ready signal before onError("embed_load_timeout").

onReady · () => void

onStatusChange · (status: EmbedStatus, orderId: string) => void

onSuccess · (orderId: string) => void

UX signal only — credit a customer off the verified webhook, not this.

onQuoteExpired · () => void

onQuoteRefreshed · (lockedUntil: string) => void

onError · (code: string, message: string) => void

Returned handle — EmbedHandle

iframe · HTMLIFrameElement

The mounted iframe element.

unmount · () => void

Remove the iframe and detach the message listener.

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.

collect-react

React bindings. Peer dependency: react >=18.

<PulseCollectPayment>

The hosted embed as a React component. Props are all MountOptions above, plus:

className · string

style · 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.

<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.

auth · PulseAuth · required

apiKey mode (client → Pulse directly). Use useApiKey.

request · CheckoutRequest | null

The order to transact. Non-null → the modal opens; null/undefined → closed. The integrator owns this state.

baseUrl · string

Override the embed/engine host (e.g. a local or sandbox server).

fetchImpl · FetchLike

pollMs · number · default: "2500"

Status poll interval.

theme · EmbedTheme

strings · EmbedStrings

onStatusChange · (status: EmbedStatus, orderId: string) => void

onSuccess · (orderId: string) => void

onError · (code: string, message: string) => void

onClose · () => void

Fired by the × button and Esc. Omit → no ×, Esc inert (fully parent-controlled).

className · string

style · CSSProperties

<PulseRate>

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

className · string

children · (result: UseRateResult) => ReactNode

Custom renderer. Omit for the built-in 1 {from} = {rate} {to} line.

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

from · string · required

to · string · required

amount · string · required

network · string

options — UseRateOptions

endpoint · string · default: "/api/pulse/rate"

Your backend route that proxies pulse.rates.preview and returns a RatePreview JSON body.

fetcher · (params: RateParams) => Promise<RatePreview>

Custom transport (tRPC, GraphQL, …). Overrides endpoint.

refreshMs · number

Re-fetch every N ms to keep the locked rate fresh. Off by default.

enabled · boolean

Gate fetching. Defaults to true whenever amount is non-empty.

Returns — UseRateResult

data · RatePreview | null

{ rate, youSend, youReceive, expiresAt, quoteId? }.

loading · boolean

error · Error | null

refresh · () => void

collect-react-native

Same hosted embed inside a react-native-webview WebView. Peer dependencies: react >=18 and react-native-webview >=13. See React Native.

<PulseCollectPayment>

sessionToken · string · required

Single-order session token from the partner backend.

embedUrl · string

apiUrl · string

flow · "select" | "direct" · default: "select"

select: in-embed asset/network selection; direct: pinned.

networks · string[]

Narrow selectable networks (intersected with the partner config; never widens).

assets · string[]

Narrow payable assets (same narrowing rules as networks).

theme · EmbedTheme

strings · EmbedStrings

Copy overrides travel via URL params on React Native.

style · unknown

WebView style. When omitted, height follows the embed content.

Callbacks — EmbedCallbacks

Delivered through the WebView message bridge.

onReady · () => void

onStatusChange · (status: EmbedStatus, orderId: string) => void

onSuccess · (orderId: string) => void

onQuoteExpired · () => void

onQuoteRefreshed · (lockedUntil: string) => void

onError · (code: string, message: string) => void

onResize · (height: number) => void

Shared embed types

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

EmbedStatus · string union

loading, awaiting_payment, deposit_detected, deposit_confirmed, converting, completed, underpaid, overpaid, wrong_chain, expired, failed.

EmbedComponent · string union

payment, quote, status.

EmbedTheme · object

Brand tokens — primaryColor, borderRadius, mode, fontFamily, inkColor, mutedColor, backgroundColor, buttonTextColor, lineColor, successColor, dangerColor, pageBackgroundColor, density, minHeight, attribution. See Theming.

EmbedStrings · object

Copy overrides — title, subtitle, heroLabel, successTitle, successSubtitle, expiredTitle, expiredSubtitle, refreshButton, copyButton, copiedButton.