FloPay Docs

Appearance

`FloPayThemeVariables`

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

Name	Type	Required	Description
`colorPrimary`	`string`	No	Primary brand color.
`colorBackground`	`string`	No	Background color for elements.
`colorText`	`string`	No	Text color.
`colorDanger`	`string`	No	Color for error states.
`borderRadius`	`string`	No	Border radius (e.g. `"8px"`).
`fontFamily`	`string`	No	Font family stack.
`fontSizeBase`	`string`	No	Base font size (e.g. `"16px"`).
`spacingUnit`	`string`	No	Base spacing unit (e.g. `"4px"`).

`FloPayAppearance`

Controls the visual appearance of all FloPay elements.

Name	Type	Required	Description
`theme`	`'default' \| 'flat' \| 'night' \| 'none'`	No	Stripe-level base theme passed through to Elements. Distinct from the SDK-level `ThemeId` prop on React components.
`variables`	`FloPayThemeVariables`	No	Custom theme variable overrides.
`rules`	`Record<string, Record<string, string>>`	No	CSS-like rules keyed by selector (e.g. `".Input"`, `".Input:focus"`, `".Label"`, `".Tab"`, `".Tab--selected"`).

`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.

Removed: the securityFooter field on ButtonsLayoutStyles is gone alongside the "Secure Card Checkout" green footer it styled. Drop any buttonsStyles.securityFooter overrides — they are now ignored.

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).

Name	Type	Required	Description
`country`	`boolean \| string[]`	No	Country dropdown
`postal_code`	`boolean \| string[]`	No	ZIP / postal code
`address_line_1`	`boolean \| string[]`	No	Street address
`address_line_2`	`boolean \| string[]`	No	Apt, suite, unit (always optional even when visible)
`city`	`boolean \| string[]`	No	City / town
`state`	`boolean \| string[]`	No	State / province / region. Renders as a dropdown for `US` and `CA`, free text otherwise

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 Stripe billing_details for AVS checks. Used by ConfirmPaymentParams and PaymentProviderAdapter.createPaymentMethod.

Name	Type	Required	Description
`email`	`string`	No	Buyer email
`name`	`string`	No	Cardholder full name
`address`	`object`	No	Address fields (see below)

address properties:

Name	Type	Required	Description
`country`	`string`	No	ISO 3166-1 alpha-2 country code
`postal_code`	`string`	No	ZIP / postal code
`line1`	`string`	No	Street address
`line2`	`string`	No	Apt, suite, unit
`city`	`string`	No	City
`state`	`string`	No	State / province

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.

Name	Type	Required	Description
`publishableKey`	`string`	Yes	Publishable key for client-side initialization of that gateway.
`environment`	`GatewayEnvironmentEnum`	Yes	`'stage'` or `'production'`. Drives sandbox vs live selection on the SDK side (for example which PayPal JS SDK environment to load).

`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.

Name	Type	Required	Description
`stripe`	`CheckoutGatewayDto \| null`	No	Stripe gateway entry (renders card fields, Apple Pay, Google Pay, and the Stripe-rendered PayPal fallback).
`paypal`	`CheckoutGatewayDto \| null`	No	Direct PayPal gateway entry. Present when the client has provisioned a `provider_type=paypal` gateway. When present, the SDK renders PayPal via the PayPal JS SDK directly instead of the Stripe-rendered fallback. See the Direct PayPal guide.

`Customer`

A customer attached to a checkout session.

Name	Type	Required	Description
`id`	`string`	Yes	Customer ID.
`email`	`string`	Yes	Customer email.
`firstName`	`string`	No	First name.
`lastName`	`string`	No	Last name.
`gender`	`string`	No	Gender.
`city`	`string`	No	City.
`state`	`string`	No	State or province.
`country`	`string`	No	Country code.
`zip`	`string`	No	Postal / ZIP code.
`line1`	`string`	No	Street address (line 1).
`line2`	`string`	No	Apt, suite, unit (line 2).

`RecurringInterval`

Recurring interval configuration for subscription line items.

Name	Type	Required	Description
`interval`	`'month' \| 'year'`	Yes	Billing interval.
`intervalCount`	`number`	No	Number of intervals between billings.

`PriceData`

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

Name	Type	Required	Description
`currency`	`string`	Yes	ISO 4217 currency code.
`unitAmount`	`number`	Yes	Price per unit in smallest currency unit.
`productData`	`{ name: string; description?: string }`	Yes	Product name and optional description.
`recurring`	`RecurringInterval`	No	Recurring billing configuration.

`LineItem`

A single line item within a checkout session.

Name	Type	Required	Description
`price`	`string`	No	Reference to a pre-created price object on the provider.
`priceData`	`PriceData`	No	Inline price data (used when no `price` reference exists).
`quantity`	`number`	Yes	Quantity of this line item.

`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.

Name	Type	Required	Description
`id`	`string`	Yes	Session ID (UUID).
`clientSecret`	`string`	Yes	Client secret (nonce) for client-side confirmation.
`mode`	`'payment' \| 'subscription' \| 'setup'`	Yes	Session mode. `'subscription'` is inferred when any product has `type: 'subscription'`.
`status`	`'open' \| 'complete' \| 'expired'`	Yes	Current session status.
`amount`	`number`	Yes	Total amount in smallest currency unit (cents). Aggregated from `products[]`.
`currency`	`string`	Yes	ISO 4217 currency code.
`lineItems`	`LineItem[]`	No	Line items in the session.
`customer`	`Customer`	No	Customer attached to the session.
`metadata`	`Record<string, string>`	No	Arbitrary key-value metadata.
`checkoutMode`	`CheckoutMode`	No	Checkout mode from the billing API (`'full'`, `'auto'`, `'confirm'`).
`products`	`CheckoutSessionProduct[]`	No	Products you would like to include in this checkout
`successUrl`	`string`	No	Redirect URL after successful payment.
`cancelUrl`	`string`	No	Redirect URL on cancellation.
`coupons`	`string[]`	No	Applied coupon codes.
`subtotalAmount`	`number`	No	Pre-discount total in cart-currency major units. Populated by billing API ≥ v1.1.2.
`discountAmount`	`number`	No	Total reduction from applied coupons in cart-currency major units. Populated by billing API ≥ v1.1.2.
`totalAmount`	`number`	No	Final charge amount in cart-currency major units (subtotal − discount, clamped ≥ 0). Populated by billing API ≥ v1.1.2.
`createdAt`	`string`	No	Session creation timestamp.
`gateways`	`CheckoutGatewaysDto`	No	Map of gateways available on this session. Each entry is a `CheckoutGatewayDto` or `null`. The SDK reads `gateways.stripe` to initialize card / Apple Pay / Google Pay, and `gateways.paypal` to render direct PayPal. When `gateways.paypal` is `null` or missing, the SDK falls back to the Stripe-rendered PayPal path.
`accountData`	`object`	No	Full account data (userId, email, name, address).
`tagsData`	`TagsData`	No	Analytics/pixel tracking tags.

Breaking change. The previous top-level gateway: BillingProvider field and gatewayData: { publishableKey, paypalPublishableKey } shape have been replaced by gateways: { stripe, paypal }. There is no longer a single gateway discriminator on the session response — Flo supports multiple gateways on the same session and the SDK consumes the per-gateway entries directly. See the Direct PayPal guide for migration notes.

`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.

Name	Type	Required	Description
`uuid`	`string`	Yes	Product UUID.
`checkoutSessionId`	`string`	Yes	Parent session UUID.
`type`	`CheckoutProductType`	No	`'subscription'` for recurring plans, `'item'` for one-time products. Optional to mirror `CheckoutProduct.type`; when omitted, consumers treat the product as an `'item'` for display ordering.
`code`	`string`	No	Preferred catalog code.
`name`	`string \| null`	No	Display-only name. Resolved from the catalog server-side; the SDK falls back to the display cache when missing.
`description`	`string \| null`	No	Display-only description from the catalog.
`quantity`	`number`	Yes	Quantity.
`totalAmount`	`number`	No	Display-only. Populated from cache when the server omits it.
`overrideAmount`	`number \| null`	No	Backend-computed per-line override, server-authoritative. On subscription trial lines: `0` for a free trial (nothing charged today) or the resolved trial charge for a paid trial; absent on non-trial lines. See Trials.
`currency`	`string`	No	Deprecated — prefer the session-level `currency` on `CheckoutSession`.
`metadata`	`Record<string, unknown> \| null`	No	Arbitrary metadata from the catalog.

Display-only fields (name, totalAmount) may be null / undefined on the wire when the backend resolves them from the catalog. The SDK merges values you previously stashed via cacheSessionDisplayData on top of the server response so order summaries stay populated across the redirect round-trip. Server values always win where present; the cache is a fallback only. overrideAmount, by contrast, is computed by the backend (server-authoritative) — you never supply it.

Payment Results

`PaymentResult`

The result of a payment confirmation attempt.

Name	Type	Required	Description
`status`	`'succeeded' \| 'processing' \| 'requires_action' \| 'failed'`	Yes	Payment status.
`paymentIntentId`	`string`	No	ID of the PaymentIntent.
`error`	`FloPayError`	No	Error if payment failed.

`ConfirmPaymentParams`

Parameters for confirming a payment.

Name	Type	Required	Description
`clientSecret`	`string`	Yes	Client secret of the PaymentIntent or SetupIntent.
`returnUrl`	`string`	No	Redirect URL after 3-D Secure or wallet authentication.

`CreatePaymentMethodResult`

Result from creating a payment method (tokenizing card fields).

Name	Type	Required	Description
`paymentMethodId`	`string \| null`	Yes	The created payment method ID, or `null` on failure.
`error`	`FloPayError`	No	Error if tokenization failed.

`ConfirmCardPaymentParams`

Parameters for confirming a card payment with a known client secret.

Name	Type	Required	Description
`clientSecret`	`string`	Yes	Client secret of the PaymentIntent.
`paymentMethodId`	`string`	Yes	ID of the payment method to confirm with.

`ConfirmCardPaymentResult`

Result from confirming a card payment.

Name	Type	Required	Description
`status`	`'succeeded' \| 'processing' \| 'requires_action' \| 'requires_capture' \| 'failed'`	Yes	Confirmation status.
`paymentIntentId`	`string`	No	ID of the PaymentIntent.
`paymentMethodId`	`string`	No	ID of the payment method used.
`error`	`FloPayError`	No	Error if confirmation failed.

Elements

`ElementType`

type ElementType =
  | 'payment'
  | 'card'
  | 'cardNumber'
  | 'cardExpiry'
  | 'cardCvc'
  | 'address';

The type of payment element to render.

`ElementChangeEvent`

Emitted when an element's internal state changes.

Name	Type	Required	Description
`elementType`	`ElementType`	Yes	Which element emitted the event.
`complete`	`boolean`	Yes	Whether the element is complete and valid.
`empty`	`boolean`	Yes	Whether the element is empty.
`error`	`{ message: string; type: string }`	No	Validation error details.
`value`	`Record<string, unknown>`	No	Non-sensitive field values (e.g. address).

`ElementOptions`

Configuration options when creating an element.

Name	Type	Required	Description
`appearance`	`FloPayAppearance`	No	Appearance overrides.
`clientSecret`	`string`	No	Client secret for the PaymentIntent or SetupIntent.
`amount`	`number`	No	Total amount in smallest currency unit (cents). Used when no `clientSecret`.
`currency`	`string`	No	ISO 4217 currency code (lowercase). Used with `amount`.
`paymentMethodCreation`	`'manual' \| 'auto'`	No	How payment methods are created. `'manual'` = tokenize only, `'auto'` = provider handles it.
`layout`	`'tabs' \| 'accordion' \| 'auto'`	No	Layout style for the payment element.
`defaultValues`	`Record<string, unknown>`	No	Pre-filled default values.
`readOnly`	`boolean`	No	Whether the element is read-only.
`mode`	`'billing' \| 'shipping'`	No	Address element mode.

`MountedElement`

A payment element that has been created and can be mounted into the DOM.

Method	Signature	Description
`mount`	`(container: HTMLElement) => void`	Mount the element into a DOM container.
`unmount`	`() => void`	Unmount the element from the DOM.
`update`	`(options: Partial<ElementOptions>) => void`	Update element options.
`on`	`(event: string, handler: (...args: unknown[]) => void) => void`	Subscribe to an event.
`off`	`(event: string, handler: (...args: unknown[]) => void) => void`	Unsubscribe from an event.
`destroy`	`() => void`	Destroy the element and release resources.

Provider Config

`FloPayConfig`

Top-level configuration for initializing FloPay.

Name	Type	Required	Description
`publishableKey`	`string`	Yes	Your FloPay publishable key (e.g. `pk_test_...`).
`billingApiUrl`	`string`	No	Billing API base URL (e.g. `https://api.stage.flopay.com`).
`locale`	`string`	No	Locale code (e.g. `"en"`).
`appearance`	`FloPayAppearance`	No	Default appearance for all elements.
`apiVersion`	`string`	No	API version header value.

Adapter

`PaymentProviderAdapter`

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

Member	Signature	Description
`name`	`readonly string`	Provider name.
`initialize`	`(config: FloPayConfig) => Promise<void>`	Initialize the provider.
`createElement`	`(type: ElementType, options: ElementOptions) => Promise<MountedElement>`	Create a mountable element.
`getElement`	`(type: ElementType) => MountedElement \| null`	Get existing element by type.
`submitElements`	`() => Promise<{ error?: FloPayError }>`	Submit elements for validation.
`createPaymentMethod`	`() => Promise<CreatePaymentMethodResult>`	Tokenize card fields into a payment method.
`confirmCardPayment`	`(params: ConfirmCardPaymentParams) => Promise<ConfirmCardPaymentResult>`	Confirm a card payment.
`confirmPayment`	`(params: ConfirmPaymentParams) => Promise<PaymentResult>`	Confirm a payment using mounted elements.
`confirmPayPalPayment`	`(params: { billingApiUrl: string; sessionId: string; email: string; returnUrl: string }) => Promise<ConfirmCardPaymentResult>`	Create and confirm a PayPal payment.
`resumePayPalPayment`	`() => Promise<ConfirmCardPaymentResult \| null>`	Resume a PayPal payment after redirect.
`getRawProvider`	`() => unknown`	Get the raw underlying provider instance (e.g. Stripe object).
`createPayPalElements`	`(options: ElementOptions) => unknown`	Create a secondary Elements group for PayPal.
`destroy`	`() => void`	Tear down the provider and release resources.

Billing Types

`BillingProvider`

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

Supported upstream billing providers.

`TokenizedBody`

Token payload produced by client-side tokenization.

Name	Type	Required	Description
`id`	`string`	No	Token or payment method ID.
`type`	`string`	No	Token type (e.g. `"card"`).
`threeDSecureActionResultTokenId`	`string`	No	3DS action result token.
`originalPaymentMethodId`	`string`	No	Original reusable payment method ID to preserve across 3DS retries.
`isPaypal`	`boolean`	No	Whether this is a PayPal payment.

`CheckoutModeKind`

type CheckoutModeKind = 'tokenize' | 'redirect';

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

`NormalizedCheckoutSession`

Provider-agnostic normalized checkout session.

Name	Type	Required	Description
`provider`	`BillingProvider`	Yes	The billing provider.
`mode`	`CheckoutModeKind`	Yes	Checkout mode.
`data`	`object`	Yes	Provider-specific data (see below).
`raw`	`unknown`	No	Raw API response.

data properties:

Name	Type	Description
`hostedUrl`	`string`	URL for hosted checkout (redirect mode).
`clientToken`	`string`	Client token for tokenization.
`session`	`CheckoutSession`	Normalized session object.
`chargebee`	`{ site?: string; publishableKey?: string; dropInToken?: string; sessionId?: string }`	Chargebee-specific data.
`stripe`	`{ clientSecret?: string; publishableKey?: string; environment?: GatewayEnvironmentEnum }`	Stripe-specific data, derived from `gateways.stripe`.
`paypal`	`{ publishableKey?: string; environment?: GatewayEnvironmentEnum }`	Direct PayPal data, derived from `gateways.paypal`. When omitted, the SDK falls back to the Stripe-rendered PayPal path. See the Direct PayPal guide.

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.

Name	Type	Required	Description
`type`	`CheckoutProductType`	No	Deprecated — no longer needed. The backend resolves item vs subscription from the catalog `code`. Pass it only to refine the client-side optimistic display shown before the session response loads (subscriptions are listed first). Safe to omit.
`code`	`string`	Yes*	Catalog code — the product identifier. Optional in the type signature, but required in practice: the SDK throws if neither `code` nor the deprecated `providerItemId` / `providerPlanId` is set, and the backend rejects products without it.
`name`	`string \| null`	No	Display-only name. Falls back to the deprecated `itemName` / `subscriptionName` when omitted.
`quantity`	`number`	No	Quantity. Defaults to `1`.
`totalAmount`	`number`	No	Display-only regular price (major units). Backend resolves prices from the catalog; pass this to seed the display cache.
`overrideAmount`	`number \| null`	No	Deprecated — ignored by the backend on input and slated for removal. `overrideAmount` is computed server-side and only appears on the session response (see `CheckoutSessionProduct`); you cannot set it here.
`currency`	`string`	No	Deprecated — prefer the session-level `currency` on `CreateSessionParams` / `InlineSessionParams`.
`metadata`	`Record<string, unknown> \| null`	No	Arbitrary metadata forwarded to the backend.

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.

Name	Type	Required	Description
`userId`	`string`	Yes	User ID.
`firstName`	`string`	No	First name.
`lastName`	`string`	No	Last name.
`email`	`string`	Yes	Email address.
`country`	`string \| null`	No	Country code.
`gender`	`string \| null`	No	Gender.
`city`	`string \| null`	No	City.
`state`	`string \| null`	No	State or province.
`zip`	`string \| null`	No	Postal / ZIP code.
`addressLine1`	`string \| null`	No	Street address (line 1).
`addressLine2`	`string \| null`	No	Apt, suite, unit (line 2).

`TagsData`

Analytics / pixel tags forwarded to the checkout page.

Name	Type	Required	Description
`googleContainerId`	`string \| null`	No	Google Tag Manager container ID.
`sessionId`	`string \| null`	No	Analytics session ID.
`testEventCode`	`string \| null`	No	Test event code for pixel testing.

`CreateSessionParams`

Parameters for creating a checkout session via the billing API.

Name	Type	Required	Description
`billingApiUrl`	`string`	Yes	Base URL of the billing API.
`checkoutBaseUrl`	`string`	Yes	Base URL of the checkout frontend.
`clientId`	`string`	Yes	Client ID for the checkout session.
`currency`	`string`	Required	Session-level ISO 4217 currency code. The SDK resolves it from this field first, then per-line `currency` on `items` / `subscriptions` / `products`. Throws `FloPayError({ type: 'validation_error', code: 'CurrencyRequired' })` synchronously — before the HTTP request — when nothing can be resolved.
`products`	`CheckoutProduct[]`	No	Unified products array. When supplied, it is sent verbatim and `items` / `subscriptions` are ignored.
`items`	`CheckoutItem[]`	No	Deprecated — one-time purchase items. Folded into `products[]` before send; prefer `products`.
`subscriptions`	`CheckoutSubscription[]`	No	Deprecated — recurring subscription plans. Folded into `products[]` before send; prefer `products`.
`account`	`CheckoutAccount`	Yes	Buyer's account information.
`successUrl`	`string`	Yes	URL to redirect to after successful payment.
`cancelUrl`	`string`	Yes	URL to redirect to if the user cancels.
`checkoutMode`	`'confirm' \| 'auto' \| 'full'`	No	Checkout mode. Defaults to `'confirm'`.
`couponCodes`	`string[]`	No	Coupon codes to apply.
`tagsData`	`TagsData`	No	Pixel / analytics tags.
`redirectParams`	`Record<string, string>`	No	Extra query params appended to the checkout redirect URL.
`setCookie`	`boolean`	No	Whether to set the `checkout_data` cookie. Defaults to `true`.
`timeoutMs`	`number`	No	Request timeout in milliseconds. Defaults to `12000`.
`utmMetadata`	`Record<string, string \| null \| undefined>[]`	No	UTM and funnel tracking metadata.
`avsCheck`	`boolean`	No	Whether AVS will be enabled for this session. See Checkout Analytics.
`avsConfig`	`AVSFieldConfig`	No	Resolved per-field AVS exposure for analytics.
`checkoutType`	`'standard_checkout' \| 'embedded_checkout'`	No	Checkout surface.
`checkoutLayout`	`'default_layout' \| 'buttons_layout' \| 'custom_layout'`	No	Checkout layout.

Session-level currency is required. Post-#760 backends enforce @IsNotEmpty on the field. The SDK pre-validates and throws FloPayError({ type: 'validation_error', code: 'CurrencyRequired' }) before issuing the request when neither currency nor any per-line currency resolves. Pass currency at the top of the session for the cleanest behavior.

`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.

`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).

Name	Type	Required	Description
`sessionId`	`string`	Yes	Checkout session ID.
`tokenizedData`	`TokenizedBody`	No	Tokenized card/wallet data.
`accountData`	`object`	Yes	Account data for the payment (see fields below).
`chv`	`string`	No	Checkout version for A/B tracking.
`returnUrl`	`string`	No	Current page URL for redirect-capable auth flows (3DS, PayPal).
`avsCheck`	`boolean`	No	Whether AVS was enabled for this checkout. Auto-set by the SDK. See Checkout Analytics.
`avsConfig`	`AVSFieldConfig`	No	Resolved per-field exposure (which AVS fields the buyer actually saw, given their country). Auto-set by the SDK.
`checkoutType`	`'standard_checkout' \| 'embedded_checkout'`	No	Checkout surface. Auto-set by the SDK.
`checkoutLayout`	`'default_layout' \| 'buttons_layout' \| 'custom_layout'`	No	Checkout layout. Auto-set by the SDK.

accountData properties:

Name	Type	Required	Description
`userId`	`string`	Yes	User ID
`email`	`string`	Yes	Email
`firstName`	`string`	Yes	First name
`lastName`	`string`	Yes	Last name
`country`	`string`	No	Country code (only sent when AVS `country` field was visible)
`zip`	`string`	No	Postal / ZIP (only sent when AVS `postal_code` was visible)
`addressLine1`	`string`	No	Street address (only sent when AVS `address_line_1` was visible)
`addressLine2`	`string`	No	Apt / suite (only sent when AVS `address_line_2` was visible)
`city`	`string`	No	City (only sent when AVS `city` was visible)
`state`	`string`	No	State / province (only sent when AVS `state` was visible)

`CreateCustomerParams`

Parameters for creating a customer.

Name	Type	Required	Description
`email`	`string`	Yes	Customer email.
`name`	`string`	No	Customer full name.
`metadata`	`Record<string, string>`	No	Arbitrary metadata.

`UpdateCustomerParams`

Parameters for updating a customer.

Name	Type	Required	Description
`email`	`string`	No	Updated email.
`name`	`string`	No	Updated name.
`metadata`	`Record<string, string>`	No	Updated metadata.

`WebhookEvent`

A webhook event from FloPay.

Name	Type	Required	Description
`id`	`string`	Yes	Event ID.
`type`	`string`	Yes	Event type (e.g. `"payment_intent.succeeded"`).
`data`	`Record<string, unknown>`	Yes	Event data payload.
`created`	`number`	Yes	Unix timestamp of event creation.

Currency

`CurrencyInfo`

Currency information mapped to a country.

Name	Type	Required	Description
`currency`	`string`	Yes	ISO 4217 currency code (e.g. `"EUR"`).
`symbol`	`string`	Yes	Currency symbol (e.g. `"$"`).
`country`	`string`	Yes	Country name.
`countryCode`	`string`	Yes	ISO 3166-1 alpha-2 country code.
`tax`	`number`	Yes	`0` = no tax, `1` = tax (VAT) applies.

`CountryOption`

A country option for UI select elements.

Name	Type	Required	Description
`code`	`string`	Yes	ISO 3166-1 alpha-2 country code.
`name`	`string`	Yes	Country display name.
`flag`	`string`	Yes	Flag emoji.

Types

On this page