Payment Method Configurations API

In the Stripe Dashboard, set the platform-level default for individual payment methods in the Manage payment methods for your connected accounts page to edit the default-enabled payment methods.

In the Dashboard, click the gear icon in the top-right corner to open the Product settings page. Click the Payment methods link in the Payments section.

As a platform, you can set payment method preferences for your platform and for your connected accounts. The settings for Your account apply to your direct payment traffic. For example, if you charge your users a monthly fee to use your platform through your own checkout page, use the Your Account settings to manage those payments.

The settings for Your connected accounts enable you to manage the payment methods that the connected accounts on your platform can accept.

To set the default state for all connected accounts on your platform, click the Edit settings link under Your connected accounts.

For each payment method, use the dropdown to select the desired setting:

• Off by default connected accounts can turn the payment method on or off. The default is off.
• Blocked turns the payment method off for all connected accounts. Connected account owners can’t opt in.
• On by default connected accounts can turn the payment method on or off. The default is on.

Use the Payment Method Configurations API with the connected account ID to read the current state of a payment method for a specific connected account. If the connected account has more than one configuration you can filter the results by your application’s client_id, located in your Connect settings.

curl -G https://api.stripe.com/v1/payment_method_configurations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d application=
{{CLIENT_APPLICATION_ID}}

{
  "object": "list",
  "data": [
    {
      "id": 
"{{PAYMENT_METHOD_CONFIGURATION_ID}}",
      "object": "payment_method_configuration",
      "name": "Default",
      "active": true,
      "is_default": true,
      "livemode": false,
      "application": 
"{{CLIENT_APPLICATION_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 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, that payment method either doesn’t have an active capability or the display_preference value is off and buyers won’t see this payment method at checkout time. To simplify your integration and take advantage of other features, use dynamic payment methods at checkout time 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 the payment method is shown to buyers.

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": "Default",
  "active": true,
  "is_default": true,
  "livemode": false,
  "application": 
"{{CLIENT_APPLICATION_ID}}",
  "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
}

You can manage payment methods from the Dashboard. Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. This shows buyers in your checkout flow only the payment methods where available is true.

If you want to pre-fetch the available payment methods for a connected account before you render your checkout page, call the Payment Method Configurations API to get the list of payment methods. Use those with available set to true.

Some payment methods, such as Apple Pay and Link, 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.

Use targeted marketing messaging to encourage connected account owners to opt in to specific payment methods they are eligible for but haven’t yet opted in to.

Call the GET method to retrieve the status of the payment method configuration to determine when to promote a payment method. You can determine if a connected account owner has interacted with your configuration before by reading the display_preference value. If the display_preference preference is none, the connected account owner hasn’t changed the default configuration. If the preference value is on or off, the connected account owner has interacted with the configuration and you can choose whether to suppress the marketing message.