FloPay SDK

FloPay is a payment SDK that wraps provider-specific APIs (currently Stripe) behind a unified, provider-agnostic interface. It handles card payments, PayPal, 3D Secure authentication, and checkout session management so you can integrate payments without coupling your application to any single provider.

Packages

The SDK is split into four packages:

Key Features

• Provider-agnostic adapter pattern -- swap from Stripe to another provider without changing your integration code
• Self-contained checkout forms -- CheckoutForm and SplitCardForm handle the full payment lifecycle (tokenize, create intent, confirm, process, 3DS retry) out of the box
• 3D Secure handled automatically -- both forms detect 3ds_required responses and trigger the authentication flow transparently
• PayPal support -- SplitCardForm renders a PayPal button alongside card fields with a separate Elements instance, matching Stripe's architecture requirements
• Built-in theming -- three bundled themes (default, flat, night) with customizable CSS variables
• Structured errors -- FloPayError provides typed error categories (validation_error, api_error, network_error, etc.) with factory helpers

How It Works

Your App
  |
  v
FloPayProvider (React context)
  |
  v
CheckoutForm / SplitCardForm
  |
  v
@flopay/js  -->  StripeAdapter  -->  Stripe.js
  |
  v
Billing API  (session creation, payment processing)

1. Initialize -- call loadFloPay(publishableKey) to get a FloPay instance
2. Wrap -- use <FloPayProvider> to make the instance available via React context
3. Render -- drop in <CheckoutForm> or <SplitCardForm> with a session ID
4. Handle success -- the onComplete callback fires when payment succeeds

Next Steps

• Installation -- set up your project
• React Quick Start -- build your first checkout
• Node.js Quick Start -- create sessions server-side
• Concepts -- understand the architecture