One-click saved-payment button that runs FloPay's `auto` checkout mode inline and falls back to an in-page `FloPayCheckout` modal when authentication is required.

FloPayAutomaticPaymentButton

A client-side button that triggers FloPay's backend-driven auto checkout mode and keeps the user on the current page. Use it for upsells, add-ons, renewals, and other saved-payment journeys where you want a single button instead of a full checkout form.

import { FloPayAutomaticPaymentButton } from '@flopay/react';

<FloPayAutomaticPaymentButton
  sessionId="sess_abc123"
  theme="bold-dark"
  onSuccess={({ result, sessionId }) => router.refresh()}
>
  Add upsell — $0.80 today
</FloPayAutomaticPaymentButton>;

The button shares FloPay's shared processing, success, and decline modal states. When the saved-payment charge requires user interaction, the button opens a fallback FloPayCheckout modal using the same theme, so the button and its recovery modal stay visually consistent.

Props

Prop	Type	Default	Description
`sessionId`	`string`	—	Reuse a session your backend already created. Mutually exclusive with `createSession` and the inline-creation convenience props.
`nonce`	`string`	—	Session-bound checkout token (the `nonce` returned when `sessionId` was created). Required alongside `sessionId` on post-#640 backends — without it the session read and `/process` are rejected with `401 "Missing checkout session token."`. Ignored on the inline-creation path, where the SDK mints and forwards the nonce itself. See Checkout Session Token.
`createSession`	`InlineSessionDraft`	—	Create the session inline.
`clientId`	`string`	—	Inline-creation convenience prop forwarded onto the session draft.
`currency`	`string`	—	Inline-creation convenience prop.
`products`	`CheckoutProduct[]`	—	Inline-creation convenience prop.
`account`	`CheckoutAccount`	—	Inline-creation convenience prop.
`successUrl`	`string`	—	Inline-creation convenience prop.
`cancelUrl`	`string`	—	Inline-creation convenience prop.
`couponCodes`	`string[]`	—	Inline-creation convenience prop.
`tagsData`	`TagsData`	—	Inline-creation convenience prop.
`utmMetadata`	`Record<string, string \| null \| undefined>[]`	—	Inline-creation convenience prop.
`theme`	`ThemeId`	—	Styles the button and the fallback `FloPayCheckout` modal that opens when extra authentication is required. See Theming guide.
`appearance`	`FloPayAppearance`	—	Stripe-side appearance overrides. Wins over the resolved `theme` bundle's appearance.
`buttonsStyles`	`ButtonsLayoutStyles`	—	Per-field style overrides merged on top of the resolved `theme` bundle.
`onClick`	`() => void`	—	Fires when the button is pressed, before the auto flow begins.
`onSuccess`	`(event: { result: PaymentResult; sessionId: string }) => void`	—	Fires after the success modal state completes.
`onError`	`(error: FloPayError) => void`	—	Fires when the auto flow fails.
`onDecline`	`(decline: DeclineEvent) => void`	—	Fires when the failure can be classified as a decline or cancellation.
`children`	`ReactNode`	—	Button slot content. When omitted, the default embedded button content renders.

FloPayAutomaticPaymentButton also extends the standard React button props (disabled, className, aria-*, etc.).

Deprecated props

These props are accepted for back-compat and silently ignored. New code should not pass them.

Prop	Replacement	Notes
`buttonsTheme`	`theme`	Legacy preset (`'default' \| 'minimal' \| 'rounded' \| 'dark'`) still resolves via `resolveButtonsLayoutTheme()` for back-compat.
`paymentMethodId`	Removed — backend orchestration	The backend resolves the customer's latest vaulted PM via `userPaymentMethodRepository.getLatestByUserId(userUuid)`.
`checkoutMethod`	Removed — backend orchestration	The backend rebinds the session's gateway when the latest PM lives on a different provider than routing originally picked. The SDK no longer ships client-built `tokenizedData` to `createSession`.

Pass userId via account.userId so the backend can resolve the customer's saved payment method. Do not pass paymentMethodId or checkoutMethod from the client — they are silently ignored and the backend picks the PM and gateway.

Session Sources

Either reuse a backend-created session or pass inline-creation props. The button always forces checkoutMode="auto" under the hood.

Reuse a session created on your backend

<FloPayAutomaticPaymentButton
  sessionId="sess_abc123"
  nonce="nonce_abc123"
  theme="bold-dark"
  onSuccess={() => router.refresh()}
>
  Purchase Item
</FloPayAutomaticPaymentButton>

When you reuse a backend-created sessionId, pass the session's nonce too. A session read does not echo the nonce back, so the SDK cannot recover it on its own — omit it and the session read and /process are rejected with 401 "Missing checkout session token.". On the inline-creation path the SDK mints the nonce from the create response and forwards it for you (including into the fallback modal), so you do not pass it there.

Create the session inline

<FloPayAutomaticPaymentButton
  createSession={{
    clientId: 'client_123',
    currency: 'USD',
    account: {
      userId: 'user_123',
      email: 'customer@example.com',
    },
    products: [
      {
        code: 'upsell_ai_pack',
        name: 'AI Supercharger Pack',
        totalAmount: 249,
        quantity: 1,
      },
    ],
    successUrl: `${window.location.origin}/success`,
    cancelUrl: `${window.location.origin}/cancel`,
  }}
  theme="bold-dark"
>
  Purchase Item
</FloPayAutomaticPaymentButton>

Do not pass both sessionId and inline-creation props at the same time.

Authentication And Redirect Handling

The button does not hard-fail when extra authentication is needed:

when the saved payment method can complete immediately, the button shows the shared processing and success modal states
when the provider returns a redirect-capable flow (3DS or PayPal), the backend resumes and captures the result end-to-end — there is no longer a client-side payment_intent_client_secret URL-param watcher or sessionStorage handshake to wire up
when FloPay returns authentication_required without a direct redirect token, the button opens an inline FloPayCheckout modal on the same page so the user can finish authentication without navigating away; that fallback inherits the same theme passed to the button

FloPayAutomaticPaymentButton

FloPayAutomaticPaymentButton

Props

Deprecated props

Session Sources

Authentication And Redirect Handling

See Also

On this page