# Update a Stripe Checkout integration to use Managed Payments Learn how to update your existing Stripe integration to use Managed Payments. Update your existing [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) integration to use [Managed Payments](https://docs.stripe.com/payments/managed-payments/how-it-works.md). The Stripe merchant of record solution handles indirect tax compliance in more than 80 countries, along with fraud prevention, dispute management, and transaction-level customer support. You can only enable Managed Payments for new subscriptions purchased through a Managed Payments Checkout Session. Existing subscriptions aren’t eligible. If you don’t have an existing Checkout integration, [set up Managed Payments](https://docs.stripe.com/payments/managed-payments/set-up.md) instead. ## Before you begin - Your [hosted page](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=stripe-hosted) or [embedded page](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=embedded-page) integration must 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. - Enable Managed Payments in your [Dashboard](https://dashboard.stripe.com/settings/managed-payments). - Make sure your products meet the [eligibility requirements](https://docs.stripe.com/payments/managed-payments/eligibility.md) before processing a payment with Managed Payments. - Use an API version of `2025-03-31.basil` or [later](https://docs.stripe.com/changelog.md). > #### 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. ## Configure your products for Managed Payments Use the Dashboard or API to set a *tax code* (A tax code is the category of your product for tax purposes) for each of your *products* (Products represent what your business sells—whether that's a good or a service). To calculate taxes, you must select a tax code that’s [eligible for Managed Payments](https://docs.stripe.com/payments/managed-payments/eligibility.md#eligible-tax-codes). #### Dashboard To update a product’s tax code: 1. Go to the [Product catalog](https://dashboard.stripe.com/products) in the Dashboard. 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 are labeled `Eligible for Managed Payments`. 1. Click **Update product**. 1. Repeat these steps for every product you want to use with Managed Payments. #### 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 step for every 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. #### 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 Set the `managed_payments[enabled]` parameter by updating your server’s call to the [Checkout Session API](https://docs.stripe.com/api/checkout/sessions/create.md). #### Subscriptions ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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 "<>:" \ -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] 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. #### Subscriptions | Category | Parameter | Reason | | ------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Adaptive Pricing | `adaptive_pricing` | Adaptive Pricing is always enabled for Managed Payments. | | 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. Learn more about [configuring payment method settings](https://support.stripe.com/questions/payment-method-configurations-for-managed-payments) 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 to calculate sales tax. If you provide the ID of an existing [customer_account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_account) or [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) when you create the Checkout Session, that object is updated with any changes to the customer’s 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. | | `invoice_creation` | #### One-time payments | 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. Learn more about [configuring payment method settings](https://support.stripe.com/questions/payment-method-configurations-for-managed-payments) 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 to calculate sales tax. If you provide the ID of an existing [customer_account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_account) or [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) when you create the Checkout Session, that object is updated with any changes to the customer’s 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. For additional information, see [Testing](https://docs.stripe.com/testing.md). ### 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 address, phone number, and the test card number `4242 4242 4242 4242` with any CVC and an expiration date in the future. ### Payment details #### Subscriptions 1. After you confirm the test payment, go to the [Transactions](https://dashboard.stripe.com/test/payments) page in the Dashboard. 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 > > When a customer purchases a subscription through Managed Payments, it only authorizes Managed Payments to charge their payment method. Make sure you obtain the appropriate consent from your customer to charge this payment method for any transactions outside of Managed Payments. #### One-time payments 1. After you confirm the test payment, go to the [Transactions](https://dashboard.stripe.com/test/payments) page in the Dashboard. 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 (if purchased) - [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 you 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 already included 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, Managed Payments adds tax on top of the price you set, by default. To change the default, go to the [Tax settings](https://dashboard.stripe.com/settings/tax) page in the Dashboard, and update the **Include tax in prices** setting.