React SDK

What you can do

• Create a checkout session and render its payment surface from a React component.
• Present eligible cards, wallets, local payment methods, and PayPal from the session's configured gateways.
• Handle checkout completion, errors, declines, redirects, and authentication flows.

Who this is for

This connector is for React developers adding FloPay Checkout to a merchant application. Use the detailed React API reference when you need lower-level components, hooks, or full prop definitions.

Prerequisites

• A React application with a client-rendered checkout surface.
• A FloPay client ID for the environment used by the application.
• At least one product code configured for the checkout session.
• Success and cancellation routes that can receive buyers returning from an external flow.

Setup

Use FloPayCheckout for the recommended embedded React integration. It can create the checkout session inline, initialize the configured gateways, render the payment methods, and report the completed result.

1. Install the packages

pnpm add @flopay/react @flopay/js @flopay/shared

Install the same three packages when using npm or yarn. Declaring @flopay/shared directly makes the configuration import available to the application.

2. Configure the environment

Add your FloPay client ID to the public environment used by the checkout page:

NEXT_PUBLIC_FLOPAY_CLIENT_ID=client_123

Configure the SDK once when the application starts:

import { configureFlopay } from '@flopay/shared';

configureFlopay({ environment: 'staging' });

Use the environment that matches the gateway records and API environment you intend to test. See Configuration for the supported options.

3. Render checkout

The inline session path keeps session creation and the payment surface together. Supply account email before rendering because the billing session uses it during payment processing.

'use client';

import { FloPayCheckout } from '@flopay/react';

const checkout = {
  clientId: process.env.NEXT_PUBLIC_FLOPAY_CLIENT_ID!,
  currency: 'EUR',
  products: [{ code: 'your-product-code' }],
  account: {
    userId: 'user_123',
    email: 'customer@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
  },
  successUrl: '/success',
  cancelUrl: '/checkout',
};

export default function CheckoutPage() {
  return (
    <FloPayCheckout
      createSession={checkout}
      layout="buttons"
      onComplete={() => {
        window.location.href = '/success';
      }}
      onError={(error) => {
        console.error('Payment failed:', error.message);
      }}
    />
  );
}

successUrl and cancelUrl are still required for an embedded checkout because PayPal, wallets, and authentication can leave the page and return. You can also create the session on your backend and pass sessionId with its checkout nonce.

What FloPayCheckout handles

The component:

1. Creates or retrieves the checkout session.
2. Reads the session's gateways map.
3. Initializes Stripe and selects direct or Stripe-rendered PayPal.
4. Renders eligible cards, wallets, local payment methods, and PayPal.
5. Handles tokenization, confirmation, redirect resume, and 3DS.
6. Calls onComplete, onError, or onDecline with the result.

Supported features

Customize the integration

Use the detailed React reference when you need different control points:

• FloPayCheckout for every checkout prop, mode, callback, and theming option.
• FloPayProvider when you need to provide a loaded FloPay instance to lower-level components.
• CheckoutForm for the self-contained card form.
• SplitCardForm for cards, wallets, and PayPal in a composed layout.
• React hooks for SDK and checkout state inside custom children.

Known limits

• successUrl and cancelUrl remain required for embedded checkout because some payment and authentication flows redirect away from the page.
• Available payment methods depend on the active gateway records, checkout session, buyer, device, and browser.
• React callbacks report the browser-side result. Keep authenticated server-side webhook handling in place for payment lifecycle processing.
• Detailed props and lower-level composition patterns remain in the React API reference rather than this onboarding guide.

Next steps

• Node.js quick start for server-side session and webhook handling.
• Checkout session token when the backend creates the session.
• Theming to style checkout.
• Checkout analytics to receive merchant-owned instrumentation.