Browser SDK and events

Use initEmbeddedCheckout when the browser should lazily ask your server to create a session. Use createEmbeddedCheckout only when your application has already fetched that session.

Initialization

import {
  createEmbeddedCheckout,
  initEmbeddedCheckout,
} from '@paybytoken/checkout'

const recommended = await initEmbeddedCheckout({
  fetchCheckoutSession: createSessionOnMerchantServer,
})

const alreadyFetched = createEmbeddedCheckout({
  clientSecret: session.clientSecret,
  checkoutUrl: session.checkoutUrl,
})

Initialize only after the customer opens the payment step. If initialization fails before an instance is returned, show a retry that creates a new session. Do not loop on a rejected or expired client secret.

Lifecycle

checkout
  .on('ready', handleReady)
  .on('change', handleChange)
  .on('complete', handleComplete)
  .on('return', handleReturn)
  .on('cancel', handleCancel)
  .on('loaderror', handleLoadError)
  .on('error', handleError)

Event	Data	Use it for
`ready`	`amountTotal`, `currency`, `merchantName`	Remove a local skeleton or loading state.
`change`	`step`, optional `paymentIntentId`	Reflect `payment`, `confirming`, `completed` or `failed` presentation state.
`complete`	optional `paymentIntentId`, `transactionHash`	Show “payment submitted”; do not fulfill from this event.
`return`	optional payment IDs and `successUrl`	Navigate within the merchant experience.
`cancel`	optional `cancelUrl`	Restore the cart or close the payment step.
`loaderror`	`reason`, `message`	Replace an iframe load failure with a retry action.
`error`	`reason`, `message`, optional `paymentIntentId`	Explain a wallet, request or payment failure.

Every event also contains type and sessionId.

Mount and cleanup

checkout.mount('#paybytoken-checkout')

// Temporarily remove the iframe while keeping the session and handlers.
checkout.unmount()
checkout.mount('#paybytoken-checkout')

// Permanently release the in-memory credential and all listeners.
checkout.destroy()

An instance can have only one mounted checkout. Destroy it before replacing the container, switching providers or initializing another session.

Appearance

Account-level checkout branding remains the source of the merchant logo and display name. The browser SDK provides a constrained presentation layer:

const checkout = await initEmbeddedCheckout({
  fetchCheckoutSession: createSessionOnMerchantServer,
  locale: 'auto',
  appearance: {
    disableAnimations: false,
    variables: {
      colorPrimary: '#9FE870',
      colorPrimaryText: '#0E0F0C',
      colorBackground: '#F4F5F0',
      colorSurface: '#FFFFFF',
      colorText: '#0E0F0C',
      colorMutedText: '#626760',
      colorBorder: '#DFE3DC',
      borderRadius: 24,
    },
  },
})

Colors must be six-digit hex values. borderRadius accepts an integer from 0 through 32. Checkout respects prefers-reduced-motion; disableAnimations: true disables its animation for every customer. Safety, warning, error and success semantics cannot be overridden.

Update presentation without creating another session:

checkout.update({
  appearance: {
    disableAnimations: true,
    variables: { colorBackground: '#FFFFFF' },
  },
})

Browser SDK and events

Install

Initialization

Lifecycle

Mount and cleanup

Appearance

On this page

Full Explorer