Stripe managed payments

content/docs/web-checkout/index.mdx

@@ -128,25 +128,26 @@ Before you start, you'll need to have a Superwall account and a Stripe account.
 
 1. **[Creating an app](/web-checkout/web-checkout-creating-an-app):** First, you'll add a Web Checkout app to an existing project within Superwall.
 2. **[Stripe setup](/web-checkout/web-checkout-configuring-stripe-keys-and-settings):** Install the [Superwall Stripe app](https://marketplace.stripe.com/apps/superwall) for automatic configuration.
-3. **[Managing products](/web-checkout/web-checkout-adding-a-stripe-product):** Create or import products to add to your web paywalls.
-4. **[Stripe one-time purchases](/web-checkout/web-checkout-stripe-one-time-purchases):** Sell lifetime access, credit packs or other one-time products with Stripe.
+3. **[Managed Payments](/web-checkout/web-checkout-managed-payments):** Optionally let Superwall act as merchant of record for eligible Stripe web checkout payments.
+4. **[Managing products](/web-checkout/web-checkout-adding-a-stripe-product):** Create or import products to add to your web paywalls.
+5. **[Stripe one-time purchases](/web-checkout/web-checkout-stripe-one-time-purchases):** Sell lifetime access, credit packs or other one-time products with Stripe.
 
 ### Creating paywalls and campaigns
 
-5. **[Presenting paywalls](/web-checkout/web-checkout-creating-campaigns-to-show-paywalls):** Set up a campaign, create some placements and add paywalls to begin showing them to customers.
+6. **[Presenting paywalls](/web-checkout/web-checkout-creating-campaigns-to-show-paywalls):** Set up a campaign, create some placements and add paywalls to begin showing them to customers.
 
 ### Associating entitlements to your iOS apps
 
-6. **[Linking purchases to your iOS app](/sdk/guides/web-checkout/linking-membership-to-iOS-app):** Once a purchase occurs, the user will be prompted to download your app and click on a redemption link.
-7. **[Managing purchases](/web-checkout/web-checkout-managing-memberships):** Users can restore purchases, manage subscriptions, update payment methods and view billing history.
+7. **[Linking purchases to your iOS app](/sdk/guides/web-checkout/linking-membership-to-iOS-app):** Once a purchase occurs, the user will be prompted to download your app and click on a redemption link.
+8. **[Managing purchases](/web-checkout/web-checkout-managing-memberships):** Users can restore purchases, manage subscriptions, update payment methods and view billing history.
 
 ### Testing purchases
 
-8. **[Testing purchases](/web-checkout/web-checkout-testing-purchases):** Test your web checkout flow with test purchases.
+9. **[Testing purchases](/web-checkout/web-checkout-testing-purchases):** Test your web checkout flow with test purchases.
 
 ### App to Web
 
-9. **[App to Web Checkout](/web-checkout/web-checkout-direct-stripe-checkout):** For U.S. storefront customers, you can link from your iOS paywalls to Stripe checkout in Safari or the user's default browser.
+10. **[App to Web Checkout](/web-checkout/web-checkout-direct-stripe-checkout):** For U.S. storefront customers, you can link from your iOS paywalls to Stripe checkout in Safari or the user's default browser.
 
 ## Troubleshooting
 If a user has issues accessing their purchase in your app after paying via web checkout, direct them to your plan management page to retrieve their redemption link or manage billing. For example: `http://yourapp.superwall.app/manage`

content/docs/web-checkout/meta.json

@@ -8,6 +8,7 @@
         "---Getting Started---",
         "web-checkout-creating-an-app",
         "web-checkout-configuring-stripe-keys-and-settings",
+        "web-checkout-managed-payments",
         "web-checkout-adding-a-stripe-product",
         "web-checkout-adaptive-pricing",
         "web-checkout-stripe-one-time-purchases",

content/docs/web-checkout/web-checkout-adding-a-stripe-product.mdx

@@ -138,6 +138,8 @@ From there, fill in all of the fields presented to you in Stripe:
 6. **Amount:** The price of your product, and what it will renew at if it's recurring.
 7. **Billing period:** The billing period for the product, i.e. "Monthly", "Yearly", etc.
 
+If you plan to use [Managed Payments](/web-checkout/web-checkout-managed-payments), pay close attention to the Stripe **Product tax code**. Superwall asks Stripe for Managed Payments eligibility and shows Stripe's ineligibility reasons when a product needs to be fixed before Managed Payments can be enabled.
+
 <Frame>![](/images/web2app_create_new_product_in_stripe.png)</Frame>
 
 Once you've finished filling out pricing details, product name and all other metadata, **click** on the **Add product** button at the bottom right of the form. You should be redirected to your Stripe products page:

content/docs/web-checkout/web-checkout-configuring-stripe-keys-and-settings.mdx

@@ -230,6 +230,12 @@ This section should say "Configured" at the top right if setup was successful:
 
 If you want web checkout customers to pay in their local currency, enable [Stripe Adaptive Pricing](/web-checkout/web-checkout-adaptive-pricing) in Stripe's payment settings after connecting your Stripe keys. Adaptive Pricing is configured in Stripe separately for live and sandbox mode.
 
+### Managed Payments
+
+After your Stripe keys are configured, you can enable [Managed Payments](/web-checkout/web-checkout-managed-payments) from **Settings**, then **Stripe Configuration**. Managed Payments lets Superwall act as merchant of record for eligible Stripe web checkout payments through Stripe Connect, including tax calculation and compliance.
+
+The **Managed Payments** switch is available only for eligible Superwall accounts and connected Stripe accounts. If the switch is not visible, or if Stripe asks you to accept Connect terms before enabling it, follow the Managed Payments guide before launching.
+
 ### Stripe Sandbox Configuration
 
 <Note>

content/docs/web-checkout/web-checkout-faq.mdx

@@ -166,6 +166,12 @@ Yes. Create a Stripe one-time price, import it into Superwall, and add it to a w
 
 Learn more in [Stripe One-Time Purchases](/web-checkout/web-checkout-stripe-one-time-purchases).
 
+### Why don't I see Managed Payments?
+
+Managed Payments is available only for eligible Web Checkout Stripe apps and connected Stripe accounts. Superwall can enable the app-level Stripe settings control separately from the paywall-level override, so you may see the Managed Payments switch in Stripe settings before you see the paywall dropdown, or vice versa.
+
+If the control is missing, Stripe says the account is not enrolled, product eligibility cannot be checked or the paywall override is not available on an iOS or Android paywall with Stripe products, contact Superwall with the app name, Stripe environment and paywall you are configuring. See [Managed Payments](/web-checkout/web-checkout-managed-payments).
+
 ### When should I use Redirect mode instead of Redeem mode?
 
 Use **Redirect mode** when you need to:

content/docs/web-checkout/web-checkout-managed-payments.mdx

@@ -0,0 +1,99 @@
+---
+title: "Managed Payments"
+description: "Let Superwall act as merchant of record for Stripe web checkout payments."
+---
+
+Managed Payments lets Superwall act as merchant of record for Stripe web checkout purchases. When it is enabled, Superwall processes eligible Stripe checkout sessions through Stripe Connect and handles tax calculation and compliance for those payments.
+
+Use Managed Payments when you want your existing Superwall web checkout flow, products, paywalls, campaigns, redemption links and membership management to stay the same, but you want Superwall to own the merchant-of-record responsibilities for eligible Stripe payments.
+
+<Note>
+  Managed Payments is account and Stripe-account dependent. If you do not see the Managed Payments controls, or if Superwall says eligibility cannot be checked for your account, contact Superwall before launching with this payment mode.
+</Note>
+
+## Before you start
+
+Complete the standard Web Checkout setup first:
+
+- Create a [Web Checkout app](/web-checkout/web-checkout-creating-an-app).
+- Connect Stripe by installing the [Superwall Stripe app](https://marketplace.stripe.com/apps/superwall) and saving your live or sandbox keys in [Stripe Setup](/web-checkout/web-checkout-configuring-stripe-keys-and-settings).
+- Create or import the Stripe products you want to sell in Superwall.
+- Make sure each Stripe product has the correct product tax code in Stripe.
+- Keep access to the connected Stripe account handy. Stripe may ask you to accept required Stripe Connect terms before Managed Payments can be enabled.
+
+Managed Payments applies when Superwall creates a Stripe Checkout session, which is the hosted Stripe checkout flow used by Superwall's external checkout and embedded checkout destinations. This does not refer to visual elements in the Superwall paywall editor. If you use a custom Stripe Elements or Payment Element integration instead of a Stripe Checkout session, Managed Payments will not apply to that payment.
+
+## Enable Managed Payments
+
+<Steps>
+  <Step title="Open Stripe Configuration">
+    In your Web Checkout app, open **Settings** and select **Stripe Configuration**.
+  </Step>
+  <Step title="Confirm your Stripe keys are configured">
+    Managed Payments is disabled until the selected Stripe environment has a valid publishable key and secret key. Configure live keys for production purchases and sandbox keys for test purchases.
+  </Step>
+  <Step title="Turn on Managed Payments">
+    In the Managed Payments card, turn on the **Managed Payments** switch. Superwall checks product eligibility and then checks whether the connected Stripe account can use Managed Payments.
+
+    <Frame>![Managed Payments switch in Stripe Configuration](/images/stripe_mp_turn_on.jpg)</Frame>
+  </Step>
+  <Step title="Accept Stripe terms if prompted">
+    If Stripe requires terms acceptance, Superwall opens the Superwall Stripe app page for the current environment. Accept the required Stripe Connect terms, return to Superwall and turn the switch on again.
+  </Step>
+  <Step title="Review product eligibility">
+    If Superwall lists ineligible products, fix the reasons shown by Stripe before enabling Managed Payments. Product tax code issues are the most common reason a product needs attention.
+  </Step>
+</Steps>
+
+The Managed Payments switch controls the Web Checkout app's default payment mode. The live and sandbox Stripe cards each validate their own Stripe account and products, but the default itself is app-wide. Before launch, verify the live Stripe configuration even if you first tested the switch with sandbox keys.
+
+## Product eligibility
+
+When product eligibility checks are available, Superwall asks Stripe whether active products in the selected environment can use Managed Payments. The Product eligibility list shows each product and Stripe's reason when a product is ineligible.
+
+| Status | What it means | What to do |
+| --- | --- | --- |
+| **Eligible** | Stripe says the product can be used with Managed Payments. | No action is needed. |
+| **Ineligible** | Stripe returned a product-level reason that blocks Managed Payments. | Fix the reason shown in Stripe, then recheck in Superwall. |
+| **No active products found** | The connected Stripe account has no active products for this environment. | Create or import active Stripe products before testing checkout. |
+| **Eligibility checks are not enabled** | Superwall cannot show per-product eligibility for this environment yet. | Continue only after confirming the account is ready with Superwall. |
+| **Account not enrolled or unavailable** | Stripe rejected the eligibility check or Managed Payments availability check for this account. | Follow the message shown in Superwall, accept Stripe terms if prompted or contact Superwall. |
+
+If Superwall can check eligibility and one or more products are ineligible, Managed Payments will not turn on until those products are fixed. If eligibility detail is unavailable, the final enablement gate is the Stripe account availability check.
+
+## Override the default on a paywall
+
+By default, Stripe checkout paywalls follow the Web Checkout app's Managed Payments setting. Some iOS and Android paywalls can override that default when they use Stripe products.
+
+The paywall-level **Managed Payments** setting appears only when all of these are true:
+
+- The paywall belongs to an iOS or Android app.
+- The paywall has at least one Stripe web checkout product.
+- Paywall-level Managed Payments controls are enabled for the account.
+
+| Option | Checkout behavior |
+| --- | --- |
+| **Use Account Setting** | Follow the Web Checkout app's Managed Payments default. |
+| **Use Managed Payments** | Use Managed Payments for this paywall's eligible Stripe checkout sessions, even if the app default is off. |
+| **Use Default Payments** | Use the default Stripe payment flow for this paywall, even if the app default is on. |
+
+Use the override when you want to test Managed Payments on a single paywall, exclude a specific paywall from Managed Payments or migrate traffic gradually.
+
+## What happens at checkout
+
+When a customer starts checkout, Superwall resolves the paywall override first. If the paywall is set to **Use Account Setting**, or if the paywall has no override, Superwall uses the Web Checkout app's Managed Payments default.
+
+If the resolved value is Managed Payments, Superwall creates the Stripe Checkout session with Managed Payments enabled. Superwall also records whether Managed Payments was used, plus the paywall override value, on checkout and transaction analytics events so reporting can distinguish managed and default Stripe payments.
+
+If checkout uses a Stripe Elements or Payment Element path instead of a Stripe Checkout session, Managed Payments is not applied to that payment. Embedded checkout session fallback keeps Managed Payments enabled when the resolved setting is Managed Payments.
+
+## If the controls are missing
+
+Managed Payments has more than one availability gate:
+
+- The app-level Managed Payments card can be enabled or hidden by Superwall for an account.
+- The paywall-level override is enabled separately, so an account can have the Stripe Configuration toggle without seeing the paywall dropdown.
+- Stripe can still block enablement until the connected account accepts the required terms or becomes eligible for the Managed Payments preview.
+- Product eligibility details can be unavailable even when the app-level switch is visible.
+
+If the Stripe Configuration card, product eligibility list or paywall override is missing, contact Superwall with the app name, Stripe environment and the paywall you are trying to configure.