All-in-one checkout component that handles session fetching, provider initialization, and payment form rendering automatically.

FloPayCheckout

Recommended. FloPayCheckout is the simplest way to add payments to your app. It replaces the manual FloPayProvider + loadFloPay + PaymentAPI setup with a single component.

Basic Usage

import { FloPayCheckout } from '@flopay/react';
 
function CheckoutPage({ sessionId }: { sessionId: string }) {
  return (
    <FloPayCheckout
      sessionId={sessionId}
      onComplete={(result) => {
        window.location.href = '/success';
      }}
      onError={(err) => {
        console.error(err.type, err.message);
      }}
    />
  );
}

That's it. The component handles:

Fetching the checkout session from the billing API
Detecting the payment provider (Stripe, Chargebee, Recurly)
Extracting the publishable key from gatewayData
Initializing FloPay with the correct key
Rendering a SplitCardForm with card fields + PayPal
Injecting session data (email, userId, amount, currency) automatically

Props

Prop	Type	Default	Description
`sessionId`	`string`	—	Required. Checkout session UUID from the billing API.
`billingApiUrl`	`string`	`BILLING_API_URL`	Override the default billing API base URL.
`appearance`	`FloPayAppearance`	—	Visual theme for payment elements.
`locale`	`string`	`'auto'`	Locale for payment elements.
`fallbackPublishableKey`	`string`	—	Used if the session doesn't include `gatewayData.publishableKey`.
`onComplete`	`(result: PaymentResult) => void`	—	Called when payment succeeds.
`onError`	`(error: FloPayError) => void`	—	Called when payment fails.
`showPayPal`	`boolean`	`true`	Whether to show the PayPal button.
`submitLabel`	`string`	`'CONFIRM PAYMENT'`	Custom submit button text.
`loading`	`ReactNode`	Spinner	Custom loading UI while session loads.
`error`	`(err: FloPayError) => ReactNode`	Error message	Custom error UI if session fails to load.
`className`	`string`	—	CSS class for the form wrapper.
`children`	`ReactNode`	`SplitCardForm`	Override the default form (see below).

Custom Loading State

<FloPayCheckout
  sessionId={sessionId}
  loading={<MySkeletonLoader />}
  onComplete={handleSuccess}
/>

Custom Error State

<FloPayCheckout
  sessionId={sessionId}
  error={(err) => (
    <div className="error-banner">
      <p>Failed to load checkout: {err.message}</p>
      <button onClick={() => window.location.reload()}>Retry</button>
    </div>
  )}
  onComplete={handleSuccess}
/>

Custom Form (Children Override)

By default, FloPayCheckout renders a SplitCardForm. To use a different form component, pass it as children:

import { FloPayCheckout, CheckoutForm } from '@flopay/react';
 
<FloPayCheckout sessionId={sessionId}>
  <CheckoutForm
    onComplete={handleSuccess}
    layout="accordion"
    showAddress="billing"
  />
</FloPayCheckout>

When you provide children, FloPayCheckout auto-injects sessionId, billingApiUrl, email, userId, firstName, and lastName from the session data. You don't need to pass them manually. Explicit props on the child take precedence.

Comparison with Manual Setup

FloPayCheckout (recommended)

import { FloPayCheckout } from '@flopay/react';
 
<FloPayCheckout sessionId={sessionId} onComplete={handleSuccess} />

Manual Setup (advanced)

import { loadFloPay, PaymentAPI } from '@flopay/js';
import { FloPayProvider, SplitCardForm } from '@flopay/react';
 
const api = new PaymentAPI('https://api.stage.flopay.com');
const session = await api.getUnifiedCheckoutSession(sessionId);
const flopay = await loadFloPay(session.data.stripe?.publishableKey);
 
<FloPayProvider
  flopay={flopay}
  options={{ paymentMethodCreation: 'manual', amount: 4999, currency: 'usd' }}
>
  <SplitCardForm
    sessionId={sessionId}
    email="user@example.com"
    userId="user_123"
    onComplete={handleSuccess}
  />
</FloPayProvider>

Use the manual setup when you need full control over provider initialization, element options, or want to use the FloPay SDK outside of React.

FloPayCheckout

On this page