FloPayPaymentMethodSetupCopy Anchor Link

FloPayPaymentMethodSetup renders every payment method a setup session advertises and saves the customer's choice without a purchase or a charge. It takes the sessionId and nonce of a setup session that your server created with POST /v1/checkouts/sessions/setup.

For the full server and browser workflow, see Save and manage payment methods.

ImportCopy Anchor Link

import { FloPayPaymentMethodSetup } from '@flopay/react/payment-method-setup';

The @flopay/react/payment-method-setup entry loads a provider's script only when the session advertises one of that provider's methods. A session that advertises only a card requests no provider script at all. The component is also exported from @flopay/react, which suits a page that already renders FloPayCheckout.

The component is browser-only and does not need FloPayProvider.

UsageCopy Anchor Link

import { FloPayPaymentMethodSetup } from '@flopay/react/payment-method-setup';

export function AddPaymentMethod({ sessionId, nonce }: { sessionId: string; nonce: string }) {
  return (
    <FloPayPaymentMethodSetup
      sessionId={sessionId}
      nonce={nonce}
      onComplete={({ paymentMethod }) => {
        // Verified by FloPay. `paymentMethod` is present for a card.
        // List the customer's methods again from your server for every type.
        console.log('Saved', paymentMethod?.brand ?? 'payment method');
      }}
      onDecline={({ message }) => console.warn(message)}
      onError={(error) => console.error(error.code, error.retryable)}
      onCancel={() => console.log('Setup closed before it finished')}
    />
  );
}

PropsCopy Anchor Link

EventsCopy Anchor Link

onComplete is FloPay's decision, not the provider's. After a wallet, PayPal, or a bank method is approved, the component reads the setup session again until FloPay reports it completed, and only then fires onComplete.

What the component rendersCopy Anchor Link

The setup session is the single source of truth. The component renders exactly the methods the session lists in advertisedPaymentMethods and nothing else. It does no gateway selection, filtering, or inference, and there is no prop that adds or removes a method.

Methods are laid out the way FloPayCheckout lays them out, using the same components:

1. Wallets, such as Apple Pay and Google Pay.
2. PayPal.
3. One tile for each bank method. Pressing a tile opens that method's form and its Save button. Pressing it again closes the form.
4. An or add a card rule.
5. FloPay's hosted card form.

A session that advertises only a card renders the hosted card form alone, with no rule above it, exactly like FloPayCardSetup.

Methods that are left outCopy Anchor Link

A method the provider cannot offer in this browser is not drawn, and onError is not called:

• a wallet the device or browser does not have
• a method the provider does not support in the session currency, such as SEPA Direct Debit outside EUR

A bank method's tile appears only once the provider has confirmed that it can render the method. Only when no advertised method can be offered at all does onError receive payment_method_setup_unavailable.

CurrencyCopy Anchor Link

Stripe wallets and bank methods are given the currency the setup session carries, never a guessed one. FloPay returns the currency it resolved for the customer, or the currency of the card gateway it selected when none was resolved. To offer a currency-bound method, send the customer's currency when your server creates the setup session.

ErrorsCopy Anchor Link

onError receives a FloPayCardSetupError, which adds retryable to FloPayError. Keep the component mounted on a retryable error: the customer can try again, or choose another method.

A failing wallet, bank method, or PayPal never takes the card form down. The failed method is removed, the others stay mounted, and the error is retryable: true while another advertised method is still usable.

Returning from a provider redirectCopy Anchor Link

Some methods send the customer to the provider and back to the same page. To finish that setup, mount the component again with the same sessionId and nonce when the customer returns. It reads the provider's return parameters from the URL, removes them, and resolves the outcome through the same callbacks: a completed session fires onComplete, and a failed return fires onDecline.

Keep the open setup's sessionId and nonce somewhere that survives the navigation, such as the tab's session storage, and mount the component from them on return.

WordingCopy Anchor Link

The outcome overlay reads SAVING CARD..., CARD SAVED, and CARD NOT SAVED for a card, and SAVING PAYMENT METHOD..., PAYMENT METHOD SAVED, and PAYMENT METHOD NOT SAVED for every other method.

RelatedCopy Anchor Link

• Save and manage payment methods: the full workflow, including consent, listing, replacing, and removing.
• Payment methods REST reference: the setup-session, list, and delete contracts.
• FloPayCheckout: the purchase component.