Multiple payment method configurations for your connected accounts

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:

1. Go to your Payment methods settings.
2. Click a payment method in the Payment configurations section, then click the overflow menu () > Manage configuration.
3. Under Configuration status, enable the Active option.
4. Click Save changes to apply your updates.

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.

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.

curl https://api.stripe.com/v1/payment_method_configurations/
{{PAYMENT_METHOD_CONFIGURATION_ID}} \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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 determine whether a customer sees this payment method at checkout. If available is true, the payment method’s capability is active and display_preference is on. If available is false, either the payment method doesn’t have an active capability, or the display_preference value is off, meaning customers won’t see it at checkout.

  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 customers.

• 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 property. This stores the connected account owner’s preference for that payment method, and we use it to determine whether customers see the payment method.

curl https://api.stripe.com/v1/payment_method_configurations/
{{PAYMENT_METHOD_CONFIGURATION_ID}} \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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 customer’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.

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

Some payment methods, such as Apple Pay, Google Pay, and Link, aren’t included as separate payment method types on a PaymentIntent. They’re available when you specify card as the type. You can use the Payment Method Configurations API to let connected account owners opt in or out of these specific payment methods. Enabling them requires card payments to be enabled.

Use targeted marketing messaging to encourage connected account owners to opt in to specific payment methods they’re eligible for.

Check the display preference of a payment method configuration to determine when to promote a payment method. You can determine whether a connected account owner has interacted with a payment method in the configuration by reading the display_preference.preference value. If the value is none, then the connected account owner hasn’t changed the default configuration, and you might consider marketing that payment method to them. If the value is on or off, then the connected account owner has already specified a preference about using that payment method.