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

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.

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

`CheckoutSession`

Represents a FloPay checkout session.

Name	Type	Required	Description
`id`	`string`	Yes	Session ID.
`clientSecret`	`string`	Yes	Client secret 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.
`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.

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.
`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 }`	Stripe-specific data.

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.

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

`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`	`{ userId: string; email: string; firstName: string; lastName: string; zip?: string; country?: string }`	Yes	Account data for the payment.
`chv`	`string`	No	Checkout version for A/B tracking.

`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