PaybytokenDocs
SDK · React

React integration

Mount embedded Paybytoken checkout with the React SDK.

@paybytoken/react wraps the framework-independent checkout SDK and manages mount, update and destroy behavior for a React component.

Install

pnpm add @paybytoken/react

Render embedded checkout

'use client'

import { useCallback, useMemo, useState } from 'react'
import { PaybytokenEmbeddedCheckout } from '@paybytoken/react'

export function Payment() {
  const [error, setError] = useState<string>()

  const fetchCheckoutSession = useCallback(async () => {
    const response = await fetch('/api/paybytoken/checkout-session', {
      method: 'POST',
    })

    if (!response.ok) {
      throw new Error('Checkout session could not be created')
    }

    return response.json()
  }, [])

  const options = useMemo(
    () => ({
      fetchCheckoutSession,
      locale: 'auto' as const,
      appearance: {
        variables: {
          colorPrimary: '#9FE870',
          colorPrimaryText: '#0E0F0C',
          borderRadius: 20,
        },
      },
    }),
    [fetchCheckoutSession],
  )

  if (error) {
    return <button onClick={() => setError(undefined)}>Try again</button>
  }

  return (
    <PaybytokenEmbeddedCheckout
      options={options}
      onReady={() => console.log('Checkout is ready')}
      onComplete={({ data }) => showPaymentSubmitted(data)}
      onCancel={() => restoreCart()}
      onLoadError={({ data }) => setError(data.message ?? 'Checkout could not load')}
      onInitializationError={(cause) =>
        setError(cause instanceof Error ? cause.message : 'Checkout could not start')
      }
    />
  )
}

The session route is the same as the one in the embedded quickstart.

Keep initialization inputs stable

Keep fetchCheckoutSession and an optional walletProvider reference stable with useCallback, useMemo or a module-level function. Changing either reference creates a new checkout instance and a new session.

Appearance and locale changes update the existing checkout instance without creating another payment session.

Component props

PropPurpose
optionsSession callback, locale, appearance, timeout and optional wallet provider.
onReadyCheckout UI is ready.
onChangeThe payment step changed.
onCompleteA payment was submitted; confirm server-side before fulfillment.
onCancelThe customer canceled checkout.
onReturnCheckout requested navigation back to the merchant.
onLoadErrorThe managed iframe could not load.
onInitializationErrorSession creation or SDK initialization failed before mount.
onErrorA payment or wallet action failed.

On this page

API Workbench

Full Explorer

Open in new tab