# Update a Stripe Checkout integration to use Managed Payments Learn how to update your existing Stripe integration to use Managed Payments. > #### Terms of service required > > You must accept the [Managed Payments terms of service](https://stripe.com/legal/managed-payments) in the [Dashboard](https://dashboard.stripe.com/settings/managed-payments) before you can use Managed Payments. Update your existing [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) integration to use Managed Payments. Your integration must already accept payments by creating *Checkout Sessions* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription) in `payment` or `subscription` mode. If you don’t have an existing Checkout integration, see [Set up Managed Payments](https://docs.stripe.com/payments/managed-payments/set-up.md) instead. ### Reasons to update A Managed Payments integration enables Stripe to take on the responsibility for indirect taxes compliance, fraud prevention, customer transaction support, and order management for you. To learn more, see [How Managed Payments works](https://docs.stripe.com/payments/managed-payments/how-it-works.md). ### Existing subscriptions During this preview, you can only enable Managed Payments for new subscriptions purchased through a Managed Payments Checkout Session. Existing subscriptions aren’t eligible. ## Before you begin - You have an existing Stripe Checkout integration (either [hosted](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=stripe-hosted) or [embedded form](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=embedded-form)) that creates Checkout Sessions in `payment` or `subscription` mode. - Activate Managed Payments in your [Dashboard](https://dashboard.stripe.com/settings/managed-payments). - Ensure your products meet the [eligibility requirements](https://docs.stripe.com/payments/managed-payments/how-it-works.md#eligibility) for Managed Payments. To process a payment through Managed Payments, all the products the customer purchases must meet eligibility. - Use a [preview API version](https://docs.stripe.com/sdks/versioning.md#public-preview-release-channel) of `2025-04-30.preview` or later for Checkout Session creation. ## Configure your products for Managed Payments To calculate taxes, Managed Payments requires your *products* (Products represent what your business sells—whether that's a good or a service) have a set *tax code* (A tax code is the category of your product for tax purposes). To see the eligible tax codes, see [How Managed Payments works](https://docs.stripe.com/payments/managed-payments/how-it-works.md#eligible-product-tax-codes). Use the Dashboard or the API to set a tax code for each of your products. #### Dashboard To update a product’s tax code: 1. Navigate to the **Dashboard** > [Product catalog](https://dashboard.stripe.com/products). 1. Click the overflow menu (⋯) next to the product you want to update. 1. Click **Edit product**. 1. Select a **Product tax code**. Eligible tax codes will be labelled “**Eligible** for Managed Payments”. 1. Click **Update product**. #### API To update a product’s tax code: ```curl curl https://api.stripe.com/v1/products/{{PRODUCT_ID}} \ -u "<>:" \ -d tax_code={{TAX_CODE}} ``` Repeat this for each product you want to use with Managed Payments. If you create your products inline when creating your [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md), include `tax_code` in the `product_data` object. For example, depending on whether you accept subscriptions or one-time payments: #### Subscriptions ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][product_data][name]=Basic subscription" \ -d "line_items[0][price_data][product_data][tax_code]={{TAX_CODE}}" \ -d "line_items[0][price_data][recurring][interval]=month" \ -d "line_items[0][quantity]=1" \ -d mode=subscription \ --data-urlencode "success_url=https://example.com/success" ``` #### One-time payments ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][product_data][name]=1000 tokens" \ -d "line_items[0][price_data][product_data][tax_code]={{TAX_CODE}}" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` ## Enable Managed Payments when creating your Checkout Session Update your server’s call to the [Checkout Session API](https://docs.stripe.com/api/checkout/sessions/create.md) to set the `managed_payments[enabled]` parameter and use a [Preview API version](https://docs.stripe.com/sdks/versioning.md#public-preview-release-channel). For example: #### Subscriptions ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ -d "managed_payments[enabled]=true" \ -d mode=subscription \ --data-urlencode "success_url=https://example.com/success" ``` #### One-time payments ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ -d "managed_payments[enabled]=true" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` ## Remove unsupported parameters [Server-side] #### Subscriptions To act as the merchant of record, Stripe controls some parts of the Checkout Session. As a result, some parameters aren’t available when using Managed Payments, and you must remove them when creating Managed Payments Checkout Sessions. | Category | Parameter | Reason | | ------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tax | `automatic_tax` | Managed Payments handles tax calculation and withholding for you. | | `tax_id_collection` | | `subscription_data.default_tax_rates` | | Payment methods | `payment_method_configuration` | Managed Payments controls the payment methods available in the Checkout Session using [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) to display the most relevant payment methods to your customer. Refer to [Payment method configurations](https://support.stripe.com/questions/payment-method-configurations-for-managed-payments) for information about how to configure payment method settings for Managed Payments. | | `payment_method_options` | | `payment_method_types` | | Customer update | `customer_update[name]` | Managed Payments requires that your customer has a name and a valid billing address in order to calculate sales tax. If you provide the ID of an [existing customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) when you create the Checkout Session, the [Customer](https://docs.stripe.com/api/customers/object.md) is updated with any changes to their name or billing address. | | `customer_update[address]` | | Shipping | `shipping_address_collection` | Managed Payments only supports digital products, so shipping information is never collected. | | `shipping_options` | | Connect | `subscription_data.application_fee_percent` | Managed Payments doesn’t support Connect integrations. | | `subscription_data.on_behalf_of` | | `subscription_data.transfer_data` | | Post-sale | `subscription_data.invoice_settings` | Managed Payments handles post-sale actions, such as invoicing and confirmation emails for you. | | `invoice_creation` | #### One-time payments To act as the *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account), Stripe controls some parts of the Checkout Session. As a result, some parameters aren’t available when using Managed Payments, and you must remove them when creating Managed Payments Checkout Sessions. | Category | Parameter | Reason | | ------------------------------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tax | `automatic_tax` | Managed Payments handles tax calculation and withholding for you. | | `tax_id_collection` | | Payment methods | `excluded_payment_method_types` | Managed Payments controls the payment methods available in the Checkout Session using [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) to display the most relevant payment methods to your customer. Refer to [Payment method configurations](https://support.stripe.com/questions/payment-method-configurations-for-managed-payments) for information about how to configure payment method settings for Managed Payments. | | `adaptive_pricing` | | `payment_intent_data.setup_future_usage` | | `payment_method_configuration` | | `payment_method_options.{payment_method}.setup_future_usage` | | `payment_method_types` | | Customer update | `customer_update[name]` | Managed Payments requires that your customer has a name and a valid billing address in order to calculate sales tax. If you provide the ID of an [existing customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) when you create the Checkout Session, the [Customer](https://docs.stripe.com/api/customers/object.md) is updated with any changes to their name or billing address. | | `customer_update[address]` | | Shipping | `shipping_address_collection` | Managed Payments only supports digital products, so shipping information is never collected. | | `shipping_options` | | `payment_intent_data.shipping` | | Connect | `payment_intent_data.application_fee_amount` | Managed Payments doesn’t support Connect integrations. | | `payment_intent_data.on_behalf_of` | | `payment_intent_data.transfer_data` | | `payment_intent_data.transfer_group` | | Post-sale | `invoice_creation` | Managed Payments handles post-sale actions such as invoicing and confirmation emails for you. | | `payment_intent_data.statement_descriptor` | | `payment_intent_data.statement_descriptor_suffix` | | `payment_intent_data.receipt_email` | ## Testing Test that your integration works correctly for your customers. ### Checkout 1. Start your server and go to your checkout page (for example, from [Build your checkout](https://docs.stripe.com/payments/managed-payments/set-up.md#build-your-checkout)). 1. Click the checkout button to be redirected to the Managed Payments checkout page. 1. On the checkout page, enter different billing addresses to see how Managed Payments calculates tax for customers in different locations. 1. To process the payment, enter your email, phone number, and the test card number `4242 4242 4242 4242` with any CVC and an expiration date in the future. For additional information, see [Testing](https://docs.stripe.com/testing.md). ### Payment details #### Item 1 1. After you confirm the test payment, go to the **Dashboard** > [Transactions](https://dashboard.stripe.com/test/payments) 1. Click your test payment to view the payment details. This page shows the: - Product that was purchased - [Subscription](https://docs.stripe.com/api/subscriptions.md) that was created - [Invoice](https://docs.stripe.com/api/invoices.md) that was created - Amount of tax calculated and withheld through Managed Payments - Statement descriptor that displays on your customer’s statements > #### Customer authorization > > The payment method attached to the subscription is only authorized to be charged by Managed Payments. To use it for non-Managed-Payments transactions, you must obtain customer authorization. #### Item 2 1. After you confirm the test payment, go to the **Dashboard** > [Transactions](https://dashboard.stripe.com/test/payments) 1. Click your test payment to view the payment details. This page shows the: - Product that was purchased - [Subscription](https://docs.stripe.com/api/subscriptions.md) that was created - [Invoice](https://docs.stripe.com/api/invoices.md) that was created - Amount of tax calculated and withheld through Managed Payments - Statement descriptor that displays on your customer’s statements #### Preview the receipt 1. Under **Receipt history**, click **View receipt**. 1. Click **Send receipt** to preview the receipt email sent to your customer. > In sandbox mode, you won’t receive receipt emails automatically after purchase but can manually send them using the instructions above. ### Link [Link](https://docs.stripe.com/payments/link.md) acts as the merchant of record at checkout and provides subscription management and transaction support on the [Link website](https://link.com). You can test how Link works during checkout by creating a Link account during an initial Checkout Session. After you create the Link account, attempt another session using the same email address. To authenticate, use the test passcode `000000`. Test purchases won’t appear in the Link app. You can test the order management tools in the Link app by creating a Link account during a live mode Checkout Session. ## Optional: Configure the tax behavior of your prices The [tax_behavior](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#tax-behavior) of a price specifies whether tax is added on top of the price you set (`tax_behavior: exclusive`) or included already in the price (`tax_behavior: inclusive`). Managed Payments uses the [tax behavior specified on your price](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#set-tax-behavior-on-price). If you don’t specify the price’s tax behavior, by default, Managed Payments adds tax on top of the price you set. To change the default, go to the **Dashboard** > [Tax settings](https://dashboard.stripe.com/settings/tax) and update the **Include tax in prices** setting.