Multiple configurations for your Connect accounts
Learn how to allow your connected accounts to display different sets of payment methods to their buyers in different scenarios.
Use this feature if your platform is using dynamic payment methods and supports setting different types of payment methods for different types of transactions (for example, subscriptions versus one-time checkout) or for different invoice amounts (for example, invoices more than a certain dollar amount can be paid using BNPL).
Create a new payment method configurationDashboard
Navigate to the Payment methods settings for your connected accounts in the Stripe Dashboard. This is where you control your platform level “parent” configurations. Your connected accounts receive a “child” configuration for each parent that they can customize within the constraints you set below.
You start with one parent configuration by default. To create an additional configuration, click Add new configuration, and give it a name.
To make sure that the payment method configuration you want to enable is set to active
in the Dashboard:
- Go to your Payment methods settings.
- Click a payment method in the Payment configurations section, then click the overflow menu () > Manage configuration.
- Under Configuration status, enable the Active option.
- Click Save changes to apply your updates.

Set the default state for each payment methodDashboard
You can apply the default setting for each payment method to your new parent configuration, and control what customizations your connected accounts can make. Use the dropdown to select the desired setting:
- On by default the payment method is on by default. Connected accounts can turn it on and off.
- Off by default the payment method is off by default. Connected accounts can turn it on and off.
- Blocked turns the payment method off for all connected accounts. Connected accounts can’t turn it on, but the platform can override this for individual connected accounts.

Allow your connected accounts to customize their payment methods
Connected accounts with access to the full Stripe Dashboard can turn payment methods on or off if the payment method has been set to either On by default
or Off by default
. Your connected accounts see the newly created child configuration in their Payment methods settings. Your connected accounts can use the dropdown menu at the top of the page to choose a configuration to edit.
If you want your connected accounts to customize their Payment methods settings from your platform dashboard instead of the Stripe Dashboard, or if you have connected accounts who don’t have Stripe Dashboard access, you can integrate with the Payment Method Configurations API.
Use the Payment Method Configurations API with the connected account ID and child configuration ID to read the current state of a payment method for a specific connected account on that configuration.
{ "object": "list", "data": [ { "id":
, "object": "payment_method_configuration", "name": "My Custom Configuration", "active": true, "is_default": true, "livemode": false, "parent":"{{PAYMENT_METHOD_CONFIGURATION_ID}}", "acss_debit": { "available": false, "display_preference": { "overridable": true, "preference": "off", "value": "off" } }, "affirm": { "available": false, "display_preference": { "overridable": true, "preference": "off", "value": "off" } }, "afterpay_clearpay": { "available": false, "display_preference": { "overridable": true, "preference": "off", "value": "off" } }, ... additional payment methods } ], "has_more": false, "url": "/v1/payment_method_configurations" }"{{PAYMENT_METHOD_CONFIGURATION_ID}}"
If successful, the return list displays each payment method and includes two parameters outlining availability and display preference.
available
is the combination of capability value (active
,inactive
,pending
, orunrequested
) anddisplay_
value.preference You can use the
available
field to determine whether a buyer sees this payment method at checkout. Ifavailable
istrue
, the payment method’s capability is active anddisplay_
is on. Ifpreference available
isfalse
, either the payment method doesn’t have an active capability, or thedisplay_
value is off, meaning buyers won’t see it at checkout.preference To simplify your integration and take advantage of other features, use payment methods that you manage from the Dashboard at checkout, which automatically reads this parameter and shows the appropriate payment methods to buyers.
display_
has three components:preference overridable
,preference
, andvalue
.overridable
is read-only, and indicates whether the connected account’s preference can override the default set above.preference
is writable, and stores the connected account’s preference.value
is read-only, and reflects the effectivedisplay_
value.preference
Note
Only payment methods that are relevant in the connected account’s country are shown in the API response and are configurable. Check country support.
When a connected account owner takes action to turn on or off a payment method, you can update the display_
preference
attribute. This stores the connected account owner’s preference for that payment method and is used to determine whether buyers see the payment method.
{ "id":
, "object": "payment_method_configuration", "name": "My Custom Configuration", "active": true, "is_default": true, "livemode": false, "acss_debit": { "available": false, "display_preference": { "overridable": true, "preference": "off", "value": "off" } }, "affirm": { "available": true, "display_preference": { "overridable": true, "preference": "on", "value": "on" } }, "afterpay_clearpay": { "available": false, "display_preference": { "overridable": true, "preference": "off", "value": "off" } }, ... additional payment methods }"{{PAYMENT_METHOD_CONFIGURATION_ID}}"
When your connected accounts turn on payment methods with the API, Stripe intelligently ranks the payment methods based on the buyer’s location, order size, and other factors to always show the highest converting payment methods first.
Use the configuration in your checkout flow
Pass the parent configuration ID when rendering your checkout flow to use your new configuration. Stripe automatically looks up the child configuration for the associated connected account and uses their customized settings.
OptionalApple Pay and Google Pay
Apple Pay and Google Pay aren’t included as separate payment method types on a PaymentIntent and are confirmed only when supplying card. With the Payment Method Configurations API, you can let connected account owners opt in or opt out of these specific payment methods and prevent them from showing up in the UI. Enabling Apple Pay and Google Pay requires card to be enabled.