Payment method settings

Render a connected account’s Payment Method Configuration to enable customization of payment methods displayed at checkout. Connected accounts can customize their checkout payment methods and provide the necessary compliance details for their usage.

The embedded payment method settings uses the Payment Method Configurations and Account Capabilities APIs to display a list of customizable payment methods to your connected accounts. If a connected account requires additional compliance data prior to requesting the payment method capability, the component indicates this and collects the necessary information in advance.

Requirements

Your integration must use dynamic payment methods to automatically apply the connected account’s preferences during checkout. In prebuilt payment UIs such as Payment Element and Checkout, Stripe handles the logic for displaying eligible payment methods for each transaction.

Disable Stripe user authentication

Use the disable_stripe_user_authentication feature to control whether the component requires Stripe user authentication.

By default, this parameter is false.

This value can only be true for accounts where controller.requirement_collection is application.

We recommend implementing 2FA or equivalent security measures as a best practice. For account configurations that support this feature, such as Custom accounts, you assume liability for connected accounts if they can’t pay back negative balances.

The disable_stripe_user_authentication property is nullable and defaults to false. If you omit it or set it to null, the component requires Stripe user authentication.

Integrate the component

When creating an Account Session, enable payment method settings by specifying payment_method_settings in the components parameter.

curl https://api.stripe.com/v1/account_sessions \
  -u "sk_test_Hrs6SAopgFPF0bZXSN3f6ELN:" \
  -d "account=
{{CONNECTED_ACCOUNT_ID}}" \
  -d "components[payment_method_settings][enabled]=true"

After creating the account session and initializing ConnectJS, you can render the payment method settings component in the frontend:

// Include this element in your HTML
const paymentMethodSettings = stripeConnectInstance.create('payment-method-settings');
container.appendChild(paymentMethodSettings);

Platform-level controls

The embedded payment method settings component respects the platform-level defaults that you configure in the Dashboard or the Payment Method Configurations API.

For payment methods that you configure as On by default or Off by default, the connected account can override that preference in the component. If you’ve set a payment method to Blocked, it’s completely hidden in the component.

Multiple payment method configurations

With default settings, the embedded payment method settings component shows the connected account’s default payment method configuration. To use multiple payment method configurations, set the payment-method-configuration attribute.

Supported parameters

This embedded component supports the following parameters:

See the integration guide for next steps.