Types

Appearance

FloPayThemeVariables

Theme variables that map to CSS custom properties on FloPay elements.

FloPayAppearance

Controls the visual appearance of all FloPay elements.

ThemeBundleId

type ThemeBundleId =
  | 'modern-light'
  | 'modern-dark'
  | 'bold-light'
  | 'bold-dark'
  | 'glass-light'
  | 'glass-dark';

Identifier for one of the six bundled themes shipped by @flopay/shared. Each ThemeBundleId resolves to a paired FloPayAppearance and ButtonsLayoutStyles via THEMES and resolveTheme.

ThemeId

type ThemeId = 'classic' | ThemeBundleId;

Value accepted by the theme prop on FloPayCheckout, FloPayAutomaticPaymentButton, and SplitCardForm. 'classic' is a no-op marker that preserves the historic FloPay look (#EDEDFF wrapper, #4A49FF indigo submit) so consumers can declare a default explicitly; resolveTheme returns undefined for it.

ThemeBundle

type ThemeBundle = {
  appearance: FloPayAppearance;
  buttonsLayout: ButtonsLayoutStyles;
};

A pre-built pair of an appearance and a buttons-layout style set. Returned from THEMES and resolveTheme.

ButtonsLayoutStyles

Style overrides for the React-rendered wrapper, submit button, and inputs around the Stripe Elements. See ButtonsLayoutStyles Reference on FloPayCheckout for the full field list.

AVS

AVSFieldConfig

Per-field AVS configuration accepted by enableAVS on FloPayCheckout and SplitCardForm. Each field accepts true (always show), false / omitted (hidden), or string[] (show only for those ISO 3166-1 alpha-2 country codes).

import type { AVSFieldConfig } from '@flopay/shared';

const config: AVSFieldConfig = {
  country: true,
  postal_code: true,
  address_line_1: ['US', 'CA'],
};

See the AVS guide for resolution rules, defaults, and theming.

BillingDetails

Billing details forwarded to supported payment flows for AVS checks.

address properties:

Checkout Session

GatewayEnvironmentEnum

type GatewayEnvironmentEnum = 'stage' | 'production';

Per-gateway environment marker on a session response. stage points at the gateway's sandbox credentials; production points at live credentials.

CheckoutGatewayDto

A single gateway entry on a checkout session response.

CheckoutGatewaysDto

Map of gateways available on a checkout session. Each entry is CheckoutGatewayDto | null. A null (or missing) entry means that gateway is not configured for the client and the SDK should not render its payment UI.

Customer

A customer attached to a checkout session.

RecurringInterval

Recurring interval configuration for subscription line items.

PriceData

Inline product data when no pre-created price is referenced.

LineItem

A single line item within a checkout session.

FloPayEnvironment

type FloPayEnvironment = 'staging' | 'production';

The environment determines which billing API URL is used. Set it with configureFlopay({ environment }). See Configuration.

CheckoutMode

type CheckoutMode = 'full' | 'auto' | 'confirm';

Controls the checkout UI behavior. full shows the payment form, confirm shows a confirm button (uses saved PM), auto auto-submits with a saved PM.

CheckoutSession

Represents a FloPay checkout session. Includes both computed fields (like amount) and the full raw data from the billing API.

CheckoutProductType

type CheckoutProductType = 'item' | 'subscription';

Discriminator describing whether a checkout product is a one-time item or a recurring subscription. Mirrors the backend's ProductTypeEnum.

CheckoutSessionProduct

A single product from a checkout session response. type distinguishes one-time items from recurring subscriptions so both share one unified list. Returned on CheckoutSession.products from billing API v1.1.3 or later.

Payment Results

CaptureMethod

type CaptureMethod = 'automatic' | 'manual';

Omit the field (or use automatic) for immediate capture. manual is supported only for eligible one-time card carts.

PaymentResult

The result of a payment confirmation attempt.

PayPalPaymentResult

Result from the Stripe-hosted PayPal confirmation or redirect-resume flow.

Checkout Instruments

The public, versioned projection of the SDK's internal checkout taxonomy, delivered through the onInstrument callback on FloPayCheckout and FloPayProvider. Available from SDK 1.7.0. See Checkout analytics for the funnel-building guide.

FloInstrumentEvent

type FloInstrumentEvent =
  | {
      schemaVersion: typeof FLO_INSTRUMENT_SCHEMA_VERSION;
      gateway?: BillingProvider;
      name: FloInstrumentLifecycleName;
    }
  | {
      schemaVersion: typeof FLO_INSTRUMENT_SCHEMA_VERSION;
      gateway?: BillingProvider;
      name: 'checkout_error';
      phase: FloInstrumentErrorPhase;
    };

A discriminated union on name. Narrow on name === 'checkout_error' before reading phase.

FloInstrumentLifecycleName

type FloInstrumentLifecycleName =
  | 'checkout_mount'
  | 'sdk_loaded'
  | 'form_rendered'
  | 'card_expanded'
  | 'tokenize'
  | 'process_attempt'
  | '3ds_challenge';

Progress through the checkout. checkout_mount, sdk_loaded, form_rendered, and card_expanded arrive at most once per logical checkout; tokenize, process_attempt, and 3ds_challenge may repeat once per attempt. See Building a funnel.

FloInstrumentErrorPhase

type FloInstrumentErrorPhase = 'session_create' | 'sdk_load' | 'process' | 'wallets';

Which stage a checkout_error failed in: session creation, SDK or gateway initialisation, payment processing, or wallet intent creation. This is a technical failure of the checkout, not a card decline — declines arrive through onDecline.

Provider Config

FloPayConfig

Top-level configuration for initializing FloPay.

Adapter

PaymentProviderAdapter

Abstraction layer for payment providers. Currently only Stripe is implemented (StripeAdapter).

Billing Types

BillingProvider

type BillingProvider = 'recurly' | 'chargebee' | 'stripe';

Supported upstream billing providers.

TokenizedBody

Token payload produced by client-side tokenization.

CheckoutModeKind

type CheckoutModeKind = 'tokenize' | 'redirect';

Checkout mode: tokenize client-side or redirect to a hosted page.

NormalizedCheckoutSession

Provider-agnostic normalized checkout session.

data properties:

Server-side

CheckoutProduct

Unified product input for checkout session creation. Mirrors the backend's CreateCheckoutProductBodyDto. Pass these via CreateSessionParams.products when you want the new shape; otherwise the SDK folds legacy items / subscriptions into this shape before sending.

Minimum entry: { code }. code is required in practice (see above). quantity is required by the backend CreateCheckoutProductBodyDto, but the SDK defaults it to 1 before sending, so callers may omit it. type is deprecated and no longer needed — the backend resolves item vs subscription from the catalog. name and totalAmount are display-only — the backend resolves names and prices from the catalog. overrideAmount is deprecated and ignored on input; it is computed server-side and returned only on the session response.

CheckoutAccount

Buyer's account information for session creation.

TagsData

Analytics / pixel tags forwarded to the checkout page.

CreateSessionParams

Parameters for creating a checkout session via the billing API.

InlineSessionParams

Inline session-creation params used by FloPayCheckout's createSession prop. Same shape as CreateSessionParams (without billingApiUrl / checkoutBaseUrl, which are resolved from configuration), plus the same four analytics fields. The SDK populates them automatically when not provided. Session-level currency is required and follows the same validation/error path as CreateSessionParams.

It also accepts one creation-strategy field:

DetachedCheckoutSession

Two-phase result of a detached checkout-session create, returned by PaymentAPI.createDetachedSession().

interface DetachedCheckoutSession {
  shell: NormalizedCheckoutSession;
  sessionId: string;
  nonce: string;
  claimed: Promise<NormalizedCheckoutSession>;
}

Nothing may be charged until claimed settles — the billing API rejects process / intent / decline calls on an unclaimed session with 409 checkout_session_data_attachment_required, and holds an unclaimed vault charge with a retryable 503.

CheckoutSessionResult

type CheckoutSessionResult =
  | { status: 201; redirectUrl: string }
  | { status: 204 }
  | { status: number };

Result from creating a checkout session. 201 includes a redirect URL, 204 means payment method already on file.

ProcessPaymentParams

Data submitted when processing a payment (tokenized card/wallet data).

accountData properties:

CreateCustomerParams

Parameters for creating a customer.

UpdateCustomerParams

Parameters for updating a customer.

WebhookEvent

A direct Stripe webhook event returned by @flopay/node's webhooks.constructEvent helper. This is not FloPay's normalized outbound merchant webhook envelope; see Webhook payloads for that contract.

Currency

CurrencyInfo

Currency information mapped to a country.

CountryOption

A country option for UI select elements.