FloPay Docs

CheckoutForm

Drop-in checkout form that handles the full payment lifecycle by default. Renders a PaymentElement, optional AddressElement, error display, and a submit button.

const CheckoutForm: React.ForwardRefExoticComponent<
  CheckoutFormProps & React.RefAttributes<CheckoutFormRef>
>

Modes

Self-contained mode (default): Provide sessionId, billingApiUrl, email, userId, and onComplete. The form handles tokenization, intent creation, confirmation, 3DS, and backend submission automatically.
Override mode: Provide onTokenizedBody to handle backend submission yourself. The form tokenizes and confirms the payment, then delegates the final step to your callback.

Props

Name	Type	Required	Default	Description
`sessionId`	`string`	Yes	--	Checkout session ID (UUID from billing API).
`billingApiUrl`	`string`	Yes	--	Billing API base URL.
`email`	`string`	No	--	User's email (required for creating payment intents).
`userId`	`string`	No	--	User ID (required for processing payments).
`onComplete`	`(result: PaymentResult) => void`	No	--	Called when payment completes successfully.
`onError`	`(error: FloPayError) => void`	No	--	Called when a payment error occurs.
`onTokenizedBody`	`(tokenizedBody: TokenizedBody) => void`	No	--	Override: delegates backend submission to the caller.
`layout`	`'tabs' \| 'accordion' \| 'auto'`	No	`'auto'`	Layout style for the PaymentElement.
`submitLabel`	`string`	No	`'Pay'`	Label for the submit button.
`showAddress`	`boolean \| 'billing' \| 'shipping'`	No	`false`	Whether to show an address element. `true` defaults to `'billing'`.
`className`	`string`	No	--	Additional CSS class for the form wrapper.
`children`	`React.ReactNode`	No	--	Custom children (e.g. a custom submit button). Overrides the default button.
`firstName`	`string`	No	--	First name for billing.
`lastName`	`string`	No	--	Last name for billing.
`chv`	`string`	No	--	Checkout version for A/B tracking.
`isProcessing`	`boolean`	No	--	External processing state (used with `onTokenizedBody`).
`error`	`string \| null`	No	--	External error message (used with `onTokenizedBody`).
`onErrorChange`	`(error: string \| null) => void`	No	--	Called when internal error state changes.

CheckoutFormRef

Methods exposed via ref for external 3DS handling.

Method	Signature	Description
`handleNextAction`	`(clientSecret: string) => Promise<void>`	Trigger 3DS authentication with the given client secret. On success, dispatches the tokenized body.

Self-Contained Example

<CheckoutForm
  sessionId="uuid-xxx"
  billingApiUrl="https://api.example.com"
  email="user@example.com"
  userId="user_1"
  onComplete={(result) => router.push('/success')}
  onError={(err) => console.error(err)}
/>

Override Example

const formRef = useRef<CheckoutFormRef>(null);
 
<CheckoutForm
  ref={formRef}
  sessionId="uuid-xxx"
  billingApiUrl="https://api.example.com"
  email="user@example.com"
  onTokenizedBody={(body) => {
    myCustomProcessPayment(body).then((res) => {
      if (res.requires3DS) {
        formRef.current?.handleNextAction(res.clientSecret);
      }
    });
  }}
  isProcessing={loading}
  error={errorMsg}
/>

Internal Flow

Validate elements via submitElements()
Tokenize card via createPaymentMethod()
Create PaymentIntent via POST /v1/checkouts/payments/intents
Confirm card payment (handles 3DS automatically)
Submit token to POST /v1/checkouts/sessions/process
Handle 3ds_required responses with re-confirmation
Resume wallet payments after redirect (PayPal, etc.)

CheckoutForm

CheckoutForm

Modes

Props

CheckoutFormRef

Self-Contained Example

Override Example

Internal Flow

On this page