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	Predefined theme to apply.
`variables`	`FloPayThemeVariables`	No	Custom theme variable overrides.
`rules`	`Record<string, Record<string, string>>`	No	CSS-like rules keyed by selector (e.g. `".Input"`, `".Label"`).

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

`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.
`status`	`'open' \| 'complete' \| 'expired'`	Yes	Current session status.
`amount`	`number`	Yes	Total amount in smallest currency unit (cents). Aggregated from items + subscriptions.
`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'`).
`items`	`CheckoutSessionItem[]`	No	One-time purchase items from the billing API.
`subscriptions`	`CheckoutSessionSubscription[]`	No	Subscription plans from the billing API.
`successUrl`	`string`	No	Redirect URL after successful payment.
`cancelUrl`	`string`	No	Redirect URL on cancellation.
`coupons`	`string[]`	No	Applied coupon codes.
`createdAt`	`string`	No	Session creation timestamp.
`gateway`	`BillingProvider`	No	Payment provider (`'stripe'`, `'chargebee'`, `'recurly'`).
`gatewayData`	`{ publishableKey?: string; paypalPublishableKey?: string \| null }`	No	Provider-specific data. When `paypalPublishableKey` is `null` or missing, PayPal is disabled for the session.
`accountData`	`object`	No	Full account data (userId, email, name, address).
`tagsData`	`TagsData`	No	Analytics/pixel tracking tags.

`CheckoutSessionItem`

A one-time item from a checkout session response.

Name	Type	Required	Description
`uuid`	`string`	Yes	Item UUID.
`checkoutSessionId`	`string`	Yes	Parent session UUID.
`providerItemId`	`string`	Yes	Provider's item/product ID.
`providerItemName`	`string`	Yes	Display name.
`quantity`	`number`	Yes	Quantity.
`totalAmount`	`number`	Yes	Original price (major units, e.g. 24.95).
`overrideAmount`	`number \| null`	Yes	Discounted price, or `null` if no discount.
`currency`	`string`	Yes	ISO 4217 currency code.

`CheckoutSessionSubscription`

A subscription plan from a checkout session response.

Name	Type	Required	Description
`uuid`	`string`	Yes	Subscription UUID.
`checkoutSessionId`	`string`	Yes	Parent session UUID.
`providerPlanId`	`string`	Yes	Provider's plan ID.
`providerPlanName`	`string`	Yes	Display name.
`quantity`	`number`	Yes	Quantity.
`totalAmount`	`number`	Yes	Original price (major units).
`overrideAmount`	`number \| null`	Yes	Discounted price, or `null` if no discount.
`currency`	`string`	Yes	ISO 4217 currency code.

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; paypalPublishableKey?: string }`	Stripe-specific data. `paypalPublishableKey` is the dedicated Stripe account for PayPal; `undefined` means PayPal is disabled.

Server-side

`CheckoutItem`

A one-time purchase item for checkout session creation.

Name	Type	Required	Description
`providerItemId`	`string`	Yes	The provider's item/product ID (e.g. Stripe price ID).
`providerItemName`	`string \| null`	No	Display name for the item.
`quantity`	`number`	No	Quantity. Defaults to `1`.
`totalAmount`	`number`	Yes	The regular (full) price in the given currency.
`overrideAmount`	`number \| null`	No	A discounted price to charge instead of `totalAmount`.
`currency`	`string`	No	ISO 4217 currency code. Defaults to `'USD'`.

`CheckoutSubscription`

A recurring subscription plan for checkout session creation.

Name	Type	Required	Description
`providerPlanId`	`string`	Yes	The provider's plan ID.
`providerPlanName`	`string \| null`	No	Display name for the plan.
`quantity`	`number`	No	Quantity. Defaults to `1`.
`totalAmount`	`number`	Yes	The regular (full) price in the given currency.
`overrideAmount`	`number \| null`	No	A discounted price to charge instead of `totalAmount`.
`currency`	`string`	No	ISO 4217 currency code. Defaults to `'USD'`.

`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.
`items`	`CheckoutItem[]`	No	One-time purchase items.
`subscriptions`	`CheckoutSubscription[]`	No	Recurring subscription plans.
`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.

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

`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