Frontend packages - Pulse Collect

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
collect-react
collect-react-native

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

string

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

ClientAuth

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

string

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

string

API base the embed calls with the session token.

"payment" | "quote" | "status"

default:"payment"

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

"select" | "direct"

default:"select"

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

string[]

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

string[]

Narrow the payable assets. Same narrowing rules as networks.

EmbedTheme

Brand tokens (see Theming).

EmbedStrings

Copy overrides for the money-moment states.

number

default:"15000"

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

() => void

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

(orderId: string) => void

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

() => void

(lockedUntil: string) => void

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

Returned handle — EmbedHandle

HTMLIFrameElement

The mounted iframe element.

() => 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.

React bindings. Peer dependency: react >=18.

<PulseCollectPayment>

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

string

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.

PulseAuth

required

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

CheckoutRequest | null

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

string

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

FetchLike

number

default:"2500"

Status poll interval.

EmbedTheme

EmbedStrings

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

(orderId: string) => void

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

() => void

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

string

CSSProperties

<PulseRate>

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

string

(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

string

required

string

required

string

required

string

options — UseRateOptions

string

default:"/api/pulse/rate"

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

(params: RateParams) => Promise<RatePreview>

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

number

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

boolean

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

Returns — UseRateResult

RatePreview | null

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

boolean

Error | null

() => void

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

<PulseCollectPayment>

string

required

Single-order session token from the partner backend.

string

"select" | "direct"

default:"select"

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

string[]

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

string[]

Narrow payable assets (same narrowing rules as networks).

EmbedTheme

EmbedStrings

Copy overrides travel via URL params on React Native.

unknown

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

Callbacks — EmbedCallbacks

Delivered through the WebView message bridge.

() => void

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

(orderId: string) => void

() => void

(lockedUntil: string) => void

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

(height: number) => void

Shared embed types

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

string union

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

string union

payment, quote, status.

object

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

object

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

​PulseCollect.mount(target, options)

​Options — MountOptions

​Returned handle — EmbedHandle

​useSession(sessionToken)

​<PulseCollectPayment>

​<PulseCheckout>

​<PulseRate>

​useRate(params, options?)

​<PulseCollectPayment>

​Callbacks — EmbedCallbacks

​Shared embed types

PulseCollect.mount(target, options)

Options — MountOptions

Returned handle — EmbedHandle

useSession(sessionToken)

<PulseCollectPayment>

<PulseCheckout>

<PulseRate>

useRate(params, options?)

<PulseCollectPayment>

Callbacks — EmbedCallbacks

Shared embed types