Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in
OverviewAccept a paymentUpgrade your integration
Online payments
OverviewFind your use caseRecurring payments
In-person payments
Payment Methods
Payment operations
Balances and settlement timeReceiptsRefunds and cancellations
Advanced integrations
Beyond payments

Update a Stripe Checkout integration to use Managed PaymentsPublic preview

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 in the Dashboard before you can use Managed Payments.

Update your existing Stripe Checkout integration to use Managed Payments. Your integration must already accept payments by creating Checkout Sessions in payment or subscription mode.

If you don’t have an existing Checkout integration, see Set up Managed Payments 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.

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 or embedded form) that creates Checkout Sessions in payment or subscription mode.
  • Activate Managed Payments in your Dashboard.
  • Ensure your products meet the eligibility requirements for Managed Payments. To process a payment through Managed Payments, all the products the customer purchases must meet eligibility.
  • Make sure you’re using API version 2025-03-31.basil or higher.

Configure your products for Managed Payments

To calculate taxes, Managed Payments requires your products have a set tax code. To see the eligible tax codes, see How Managed Payments works.

Use the Dashboard or the API to set a tax code for each of your products.

To update a product’s tax code:

  1. Navigate to the Dashboard > Product catalogue.
  2. Click the overflow menu () next to the product you want to update.
  3. Click Edit product.
  4. Select a Product tax code. Eligible tax codes will be labelled “Eligible for Managed Payments”.
  5. Click Update product.

Repeat this for each product you want to use with Managed Payments.

If you create your products inline when creating your Checkout Session, include tax_code in the product_data object. For example, depending on whether you accept subscriptions or one-time payments:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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"

Enable Managed Payments when creating your Checkout Session

Update your server’s call to the Checkout Session API to set the managed_payments[enabled] parameter and include ;managed_payments_preview=v1 in your version header.

For example:

Command Line
cURL
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2026-01-28.clover; managed_payments_preview=v1" \
  -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"

Remove unsupported parameters
Server-side

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.

CategoryParameterReason
Taxautomatic_taxManaged Payments handles tax calculation and withholding for you.
tax_id_collection
subscription_data.default_tax_rates
Payment methodspayment_method_configurationManaged Payments controls the payment methods available in the Checkout Session using dynamic payment methods to display the most relevant payment methods to your customer. Refer to Payment method configurations for information about how to configure payment method settings for Managed Payments.
payment_method_options
payment_method_types
Customer updatecustomer_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 when you create the Checkout Session, the Customer is updated with any changes to their name or billing address.
customer_update[address]
Shippingshipping_address_collectionManaged Payments only supports digital products, so shipping information is never collected.
shipping_options
Connectsubscription_data.application_fee_percentManaged Payments doesn’t support Connect integrations.
subscription_data.on_behalf_of
subscription_data.transfer_data
Post-salesubscription_data.invoice_settingsManaged Payments handles post-sale actions such as invoicing and confirmation emails for you.

Testing

Test that your integration works correctly for your customers.

Checkout

  1. Start your server and go to your checkout page (for example, http://localhost:4242/checkout.html from Build your checkout).
  2. Click the checkout button to be redirected to the Managed Payments checkout page.
  3. On the checkout page, enter different billing addresses to see how Managed Payments calculates tax for customers in different locations.
  4. To process the payment, enter your email address, phone number, and the test card number 4242 4242 4242 4242 with any CVC and an expiry date in the future.

For additional information, see Testing.

Payment details

  1. After you confirm the test payment, go to the Dashboard > Payments list
  2. Click your test payment to view the payment details. This page shows the:
    • Product that was purchased
    • Subscription that was created
    • Invoice that was created
    • Amount of tax calculated and withheld through Managed Payments
    • Statement descriptor that displays on your customer’s statements

Customer authorisation

The payment method attached to the subscription is only authorised to be charged by Managed Payments. To use it for non-Managed-Payments transactions, you must obtain customer authorisation.

Preview the receipt

  1. Under Checkout summary, click Invoice.
  2. Click Send receipt to preview the receipt email sent to your customer. You can also download the receipt.

Note

In sandbox you will not receive receipt emails automatically after purchase but can manually send them using the instructions above.

Link

Link acts as the merchant of record at checkout and provides subscription management and transaction support at Link.com.

To test Link:

  1. Open your checkout page

  2. Click the checkout button.

  3. Enter the same email address you used to test your checkout page.

  4. In the pop-up modal, use the test passcode 000000 to authenticate.

    If you selected the Save my information for faster checkout tickbox during the first checkout, you also see the 4242 test card saved to your Link account.

OptionalConfigure the tax behaviour of your prices

The 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 behaviour specified on your price. If you don’t specify the price’s tax behaviour, by default, Managed Payments adds tax on top of the price you set.

To change the default, go to the Dashboard > Tax settings and update the Include tax in prices setting.