Concepts

Monorepo Structure

packages/
  shared/    # Types, errors, constants, themes
  js/        # Core browser SDK (provider adapters, elements, payment API)
  react/     # React components and hooks
  node/      # Server-side SDK (sessions, webhooks, customers)
apps/
  docs/      # This documentation site

Package Roles

@flopay/shared

The foundation package. Contains TypeScript types (FloPayConfig, PaymentResult, TokenizedBody, etc.), the FloPayError class, theme constants (DEFAULT_APPEARANCE, FLAT_APPEARANCE, NIGHT_APPEARANCE), and element type definitions. All other packages depend on it.

@flopay/js

The core browser engine. Provides:

• loadFloPay(publishableKey) -- initializes the payment provider adapter and returns a FloPay instance (cached per key)
• FloPay -- the main SDK class with methods for creating elements, submitting, tokenizing, and confirming payments
• FloPayElements -- manages a group of payment input elements (mount, unmount, destroy)
• createCheckoutSession -- creates a session via the billing API and redirects to the hosted checkout page
• StripeAdapter -- the adapter that translates FloPay calls into Stripe.js calls

@flopay/react

React bindings built on top of @flopay/js:

• FloPayProvider -- context provider that initializes elements and makes the FloPay instance available via hooks
• CheckoutForm -- drop-in form using Stripe's combined PaymentElement
• SplitCardForm -- split card fields (CardNumber + Expiry + CVC) with optional PayPal button
• useFloPay() / useElements() -- hooks for accessing the SDK and elements from custom components

@flopay/node

Server-side SDK wrapping Stripe's Node library:

• flopay.checkout.sessions -- create, retrieve, expire sessions; list line items
• flopay.webhooks -- verify and construct webhook events
• flopay.customers -- create, retrieve, update customers

Adapter Pattern

FloPay uses an adapter pattern to abstract the payment provider:

Your Code  -->  FloPay API  -->  PaymentProviderAdapter  -->  Stripe.js
                                        ^
                                        |
                                  (future: Chargebee,
                                   Recurly, etc.)

The PaymentProviderAdapter interface defines methods like initialize, createElement, submitElements, createPaymentMethod, confirmCardPayment, and confirmPayment. Currently only StripeAdapter implements this interface. Adding a new provider means implementing the adapter without changing consumer code.

Provider / Elements / Hooks Pattern

React integration follows a layered pattern:

1. Provider -- FloPayProvider accepts a FloPay instance (or promise) and creates an elements group
2. Elements -- Components like PaymentElement, CardNumberElement render provider-specific input fields
3. Hooks -- useFloPay() returns the FloPay instance; useElements() returns the current FloPayElements group

<FloPayProvider flopay={loadFloPay('pk_test_...')} options={{ paymentMethodCreation: 'manual' }}>
  {/* Components here can use useFloPay() and useElements() */}
  <CheckoutForm sessionId="..." billingApiUrl="..." />
</FloPayProvider>