Multiple configurations for your Connect accounts

Navigate to the payment method settings page 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.

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.

Standard Connected accounts can visit the Dashboard to 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 Dashboard payment method 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 method settings from your platform dashboard instead of the Stripe Dashboard, or if you have Custom or Express accounts who don’t have access to the Stripe Dashboard, 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.

curl https://api.stripe.com/v1/payment_method_configurations/
{{PAYMENT_METHOD_CONFIGURATION_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

{
  "object": "list",
  "data": [
    {
      "id": 
"{{PAYMENT_METHOD_CONFIGURATION_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"
}

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, or unrequested) and display_preference value.

  You can use the available field to know whether or not a buyer sees this payment method at checkout time. If available is true, that payment method’s capability is active and display_preference is on. If available is false, the payment method either doesn’t have an active capability or the display_preference value is off, and buyers won’t see it at checkout time. 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 right payment methods to buyers.

• display_preference has three components: overridable, preference, and value.

  • 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 effective display_preference value.

When a connected account owner takes action to turn on or off a payment method, you can update the display_preference 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.

curl https://api.stripe.com/v1/payment_method_configurations/
{{PAYMENT_METHOD_CONFIGURATION_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "affirm[display_preference][preference]"=on

{
  "id": 
"{{PAYMENT_METHOD_CONFIGURATION_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
}

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.

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.

If you’re using the Payment Element and creating a PaymentIntent before rendering the Payment Element, you can pass the parent ID into your PaymentIntent.

var stripe = Stripe('pk_12345...', {stripeAccount: 'acct_12345'});

await stripe.paymentIntents.create({
  amount: 1099,
  currency: 'usd',
  // In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
  automatic_payment_methods: {
    enabled: true
  },
  // Your parent configuration ID
  payment_method_configuration: 
'{{PAYMENT_METHOD_CONFIGURATION_ID}}'
});

If you’re using the Payment Element with the deferred intent creation integration path, you can pass the parent ID in to your elements session options.

const options = {
   mode: 'payment',
   amount: 1099,
   currency: 'usd',
   payment_method_configuration: 
'{{PAYMENT_METHOD_CONFIGURATION_ID}}'
}

If you’re creating a Checkout session, you can pass the parent ID in to your checkout session options.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel" \
  -d currency=usd \
  -d payment_method_configuration=
{{PAYMENT_METHOD_CONFIGURATION_ID}}