React Quick Start

This guide shows the recommended FloPay integration: render FloPayCheckout, let it create the session inline, and keep the payment form embedded on your page.

Prerequisites

• Packages installed (Installation)
• Environment configured (Configuration)
• A FloPay client ID
• A success URL and cancel URL in your app

1. Configure FloPay

Set your FloPay client ID:

NEXT_PUBLIC_FLOPAY_CLIENT_ID=client_123

Then configure the SDK once at app startup:

import { configureFlopay } from '@flopay/shared';
 
configureFlopay({ environment: 'staging' });

This tells the SDK which billing API to use. See Configuration for the supported setup options.

2. Render the Embedded Checkout

The simplest embedded flow matches the demo's one-shot approach: pass createSession instead of a pre-created sessionId.

'use client';
 
import { FloPayCheckout } from '@flopay/react';
import { configureFlopay } from '@flopay/shared';
 
configureFlopay({ environment: 'staging' });
 
const checkoutParams = {
  clientId: process.env.NEXT_PUBLIC_FLOPAY_CLIENT_ID!,
  items: [
    {
      providerItemId: 'omni-ai-booster',
      providerItemName: 'AI Supercharger Pack',
      totalAmount: 249,
      overrideAmount: 80,
      currency: 'EUR',
    },
  ],
  account: {
    userId: 'user_123',
    email: 'customer@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
  },
  successUrl: '/success',
  cancelUrl: '/checkout',
};
 
export default function CheckoutPage() {
  return (
    <FloPayCheckout
      createSession={checkoutParams}
      layout="buttons"
      onComplete={() => {
        window.location.href = '/success';
      }}
      onError={(error) => {
        console.error('Payment failed:', error.message);
      }}
    />
  );
}

That's the embedded integration. No pre-created session ID and no separate session-creation API route.

FloPayCheckout handles everything:

1. Posts the createSession payload to the billing API
2. Uses the returned session data to detect the payment provider and read gatewayData.publishableKey / gatewayData.paypalPublishableKey
3. Initializes the FloPay SDK automatically
4. Renders the embedded buttons layout with cards, wallets, and PayPal
5. Runs the full payment flow: tokenize → create intent → confirm → process → 3DS retry
6. Calls onComplete with the PaymentResult

3. Collect Data Before Rendering

If the customer picks a product, enters an email, or chooses a plan in the UI first, build the final createSession payload in state and pass it to FloPayCheckout only when they're ready to start checkout.

That is the pattern used by the demo's embedded page: collect the product + account data, then render FloPayCheckout with the finished payload.

Next Steps

• FloPayCheckout Guide — all embedded checkout options
• FloPayCheckout API Reference — all props and customization options
• Node.js Quick Start — add webhook handling for the embedded flow
• Theming — customize the checkout UI