From cb90442c84c12a46f9f91cae7217d48c31b06df4 Mon Sep 17 00:00:00 2001 From: Jordan Morgan Date: Wed, 29 Apr 2026 12:47:51 -0500 Subject: [PATCH] Clarify App2Web: use external browser for Stripe Clarify App2Web/web-checkout docs to require opening Stripe Checkout in the external browser for U.S. storefront customers (do not present Stripe Checkout inside in-app web views). Updated wording across web-checkout, platform-specific post-checkout redirect guides (Android/Expo/Flutter/shared), and integrations/webhooks to reflect external browser flows and deep-link behavior. Added a warning in the paywall editor docs about using External for purchase links. Removed the deprecated dashboard guide file and meta entry, and updated redirects-map to point old routes to the consolidated App2Web doc. --- .../post-checkout-redirecting.mdx | 2 +- .../paywall-editor-styling-elements.mdx | 4 +++ .../guides/using-stripe-checkout-in-app.mdx | 27 ------------------- content/docs/dashboard/meta.json | 1 - .../post-checkout-redirecting.mdx | 2 +- .../post-checkout-redirecting.mdx | 2 +- content/docs/integrations/index.mdx | 2 +- content/docs/integrations/webhooks/index.mdx | 2 +- content/docs/web-checkout/index.mdx | 2 +- .../web-checkout-direct-stripe-checkout.mdx | 27 +++++++++---------- .../web-checkout/web-checkout-sdk-setup.mdx | 2 +- .../post-checkout-redirecting.mdx | 2 +- redirects-map.ts | 6 +++-- 13 files changed, 29 insertions(+), 52 deletions(-) delete mode 100644 content/docs/dashboard/guides/using-stripe-checkout-in-app.mdx diff --git a/content/docs/android/guides/web-checkout/post-checkout-redirecting.mdx b/content/docs/android/guides/web-checkout/post-checkout-redirecting.mdx index c7c6c0b1..9aa66043 100644 --- a/content/docs/android/guides/web-checkout/post-checkout-redirecting.mdx +++ b/content/docs/android/guides/web-checkout/post-checkout-redirecting.mdx @@ -46,7 +46,7 @@ You'll need to implement your own logic to handle the redirect and deep link use ## Setting Up Deep Links -Whether you're showing a checkout page in a browser or using the In-App Browser, the Superwall SDK relies on deep links to redirect back to your app. +Whether checkout starts from a web link or from a paywall that opens an external browser, the Superwall SDK relies on deep links to redirect back to your app. #### Prerequisites 1. [Configuring Stripe Keys and Settings](/web-checkout/web-checkout-configuring-stripe-keys-and-settings) diff --git a/content/docs/dashboard/dashboard-creating-paywalls/paywall-editor-styling-elements.mdx b/content/docs/dashboard/dashboard-creating-paywalls/paywall-editor-styling-elements.mdx index b333f4c4..fdf27158 100644 --- a/content/docs/dashboard/dashboard-creating-paywalls/paywall-editor-styling-elements.mdx +++ b/content/docs/dashboard/dashboard-creating-paywalls/paywall-editor-styling-elements.mdx @@ -77,6 +77,10 @@ Available tap actions are: 3. **Deep Link:** Similar to the **external** option, but it'll _close_ the paywall before opening the URL. This is useful for internal navigation or when you are attempting to link to something in a web page and you'd like the paywall to close when doing so. - **Scroll To Element:** Scrolls the view to a specific element on the page. + + For Stripe Checkout or other external purchase links on iOS, use the **External** option. Do not use the in-app browser option for purchase flows. + + **State & Variables** - **Update Variable:** Sets or updates an existing variable's value. Options specific to the variable type will also be displayed. For example, a **Number** variable will have an option to choose an **Operation** such as Set, Increment or Decrement. Or, a **Boolean** variable's **Operation** will offer to either **Set** or **Toggle** the boolean value. diff --git a/content/docs/dashboard/guides/using-stripe-checkout-in-app.mdx b/content/docs/dashboard/guides/using-stripe-checkout-in-app.mdx deleted file mode 100644 index 956ecbcc..00000000 --- a/content/docs/dashboard/guides/using-stripe-checkout-in-app.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Using Stripe's New Web Checkout In-App ---- - -For users in the United States, you can offer Stripe checkout inside of your app's experience. For more information on how to configure Stripe checkout, review the documentation [here](/web-checkout/web-checkout-direct-stripe-checkout). This specific guide shows you how to use Stripe's new checkout flow. - -Superwall will prioritize showing Apple Pay when available as the first payment option. - - -**App Store Review Tip:** If you're using an in-app Stripe checkout sheet, we strongly suggest showing your Stripe purchase experience to Apple during an App Review before testing with users. For recommended reviewer note language, see the [App2Web docs](/web-checkout/web-checkout-direct-stripe-checkout). - - - - -![](/images/scbs_1.jpeg) - - -![](/images/scbd_3.jpeg) - - -![](/images/stripe_checkout.png) - - - -This process works by attaching the Stripe product to a purchase tap behavior. -Once the user checks out, the [web redemption -flow](/web-checkout/web-checkout-direct-stripe-checkout) will occur. diff --git a/content/docs/dashboard/meta.json b/content/docs/dashboard/meta.json index ba6a8a83..59f49142 100644 --- a/content/docs/dashboard/meta.json +++ b/content/docs/dashboard/meta.json @@ -27,7 +27,6 @@ "---Guides---", "guides/superwall-skill", "guides/superwall-mcp", - "guides/using-stripe-checkout-in-app", "guides/migrating-from-revenuecat-to-superwall", "guides/pre-launch-checklist", "guides/using-superwall-for-onboarding-flows", diff --git a/content/docs/expo/guides/web-checkout/post-checkout-redirecting.mdx b/content/docs/expo/guides/web-checkout/post-checkout-redirecting.mdx index 7ae86109..19e26f64 100644 --- a/content/docs/expo/guides/web-checkout/post-checkout-redirecting.mdx +++ b/content/docs/expo/guides/web-checkout/post-checkout-redirecting.mdx @@ -62,7 +62,7 @@ You'll need to implement your own logic to handle the redirect and deep link use ## Setting Up Deep Links -Whether you're showing a checkout page in a browser or using the In-App Browser, the Superwall SDK relies on deep links to redirect back to your app. +Whether checkout starts from a web link or from a paywall that opens an external browser, the Superwall SDK relies on deep links to redirect back to your app. #### Prerequisites 1. [Configuring Stripe Keys and Settings](/web-checkout/web-checkout-configuring-stripe-keys-and-settings) diff --git a/content/docs/flutter/guides/web-checkout/post-checkout-redirecting.mdx b/content/docs/flutter/guides/web-checkout/post-checkout-redirecting.mdx index 0e21f066..4f494414 100644 --- a/content/docs/flutter/guides/web-checkout/post-checkout-redirecting.mdx +++ b/content/docs/flutter/guides/web-checkout/post-checkout-redirecting.mdx @@ -46,7 +46,7 @@ You'll need to implement your own logic to handle the redirect and deep link use ## Setting Up Deep Links -Whether you're showing a checkout page in a browser or using the In-App Browser, the Superwall SDK relies on deep links to redirect back to your app. +Whether checkout starts from a web link or from a paywall that opens an external browser, the Superwall SDK relies on deep links to redirect back to your app. #### Prerequisites 1. [Configuring Stripe Keys and Settings](/web-checkout/web-checkout-configuring-stripe-keys-and-settings) diff --git a/content/docs/integrations/index.mdx b/content/docs/integrations/index.mdx index daaff8b5..2d185959 100644 --- a/content/docs/integrations/index.mdx +++ b/content/docs/integrations/index.mdx @@ -107,7 +107,7 @@ The `data` field contains detailed information about the subscription or payment | `expirationReason` | string (optional) | Reason for expiration (see [Cancel Reasons](#cancelexpiration-reasons)) | | `checkoutContext` | object (optional) | Stripe-specific checkout context | -**Note on Store field:** iOS and Android apps can receive events from any payment provider. For example, an iOS app can receive `STRIPE` events when users purchase through Superwall's App2Web features, which allow web-based checkout flows within mobile apps. The `store` field indicates where the payment was processed, not which platform the app runs on. +**Note on Store field:** iOS and Android apps can receive events from any payment provider. For example, an iOS app can receive `STRIPE` events when users purchase through Superwall's App2Web features, which can start from a mobile paywall and complete in an external browser. The `store` field indicates where the payment was processed, not which platform the app runs on. ## Event Names diff --git a/content/docs/integrations/webhooks/index.mdx b/content/docs/integrations/webhooks/index.mdx index 1edcc12a..b9624c08 100644 --- a/content/docs/integrations/webhooks/index.mdx +++ b/content/docs/integrations/webhooks/index.mdx @@ -108,7 +108,7 @@ The `data` field contains detailed information about the subscription or payment | `checkoutContext` | object (optional) | Stripe-specific checkout context | | `userAttributes` | object (optional) | Custom user attributes set via the SDK (see [User Attributes](#user-attributes)) | -**Note on Store field:** iOS and Android apps can receive events from any payment provider. For example, an iOS app can receive `STRIPE` events when users purchase through Superwall's App2Web features, which allow web-based checkout flows within mobile apps. The `store` field indicates where the payment was processed, not which platform the app runs on. +**Note on Store field:** iOS and Android apps can receive events from any payment provider. For example, an iOS app can receive `STRIPE` events when users purchase through Superwall's App2Web features, which can start from a mobile paywall and complete in an external browser. The `store` field indicates where the payment was processed, not which platform the app runs on. ## Event Names diff --git a/content/docs/web-checkout/index.mdx b/content/docs/web-checkout/index.mdx index c3af4c61..827aff08 100644 --- a/content/docs/web-checkout/index.mdx +++ b/content/docs/web-checkout/index.mdx @@ -61,7 +61,7 @@ Before you start, you'll need to have a Superwall account and a Stripe account. ### App to Web -9. **[App to Web Checkout](/web-checkout/web-checkout-direct-stripe-checkout):** For customers in the United States, you can offer Stripe products directly from your iOS paywalls. +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. ## 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` diff --git a/content/docs/web-checkout/web-checkout-direct-stripe-checkout.mdx b/content/docs/web-checkout/web-checkout-direct-stripe-checkout.mdx index 313309fc..358379a7 100644 --- a/content/docs/web-checkout/web-checkout-direct-stripe-checkout.mdx +++ b/content/docs/web-checkout/web-checkout-direct-stripe-checkout.mdx @@ -1,9 +1,15 @@ --- title: "App2Web" -description: "Offer Stripe products directly from your iOS paywalls and perform checkout flows." +description: "Link U.S. customers from iOS paywalls to Safari for Stripe checkout." --- -For customers in the United States, you can offer Stripe products directly from your iOS paywalls. This is a great way to streamline the checkout process and make it easier for users to purchase your products. +For customers on the United States App Store storefront, you can add calls to action in your iOS paywalls that open Stripe checkout outside of your app in Safari or the user's default browser. + +Do not present Stripe Checkout inside your iOS app using an in-app browser, `SFSafariViewController`, `WKWebView`, or another embedded web view. For external purchase links, the checkout flow should leave the app and open in the external browser. + + + Apple's App Review Guidelines allow United States storefront apps to include buttons, external links, or calls to action for purchase methods other than in-app purchase. Review [Guideline 3.1.1(a)](https://developer.apple.com/app-store/review/guidelines/#business) before submitting your app. + ![](/images/web_checkout_direct_to_stripe.jpg) @@ -12,28 +18,21 @@ For customers in the United States, you can offer Stripe products directly from First, follow the [web checkout setup guide](/web-checkout#getting-setup) to create a Stripe app and configure your web checkout settings. Specifically, you'll need to complete the first three steps. This includes installing the [Superwall Stripe app](https://marketplace.stripe.com/apps/superwall) and setting up your app's settings. - Select a paywall and add a Stripe product to it. This will allow users to purchase the product directly from the paywall. Stripe products are prepended with "stripe" in the product selector: + Select a paywall and add a Stripe product to it. This lets users start an external browser checkout flow from the paywall. Stripe products are prepended with "stripe" in the product selector: ![](/images/web-checkout-select-product.png) - - You can control whether or not Stripe checkout opens in your app via Safari, or externally in the Safari app: - - ![](/images/web-checkout-location.png) + + Since the policy applies to customers on the United States storefront, create a campaign filter that matches those customers. Use `storeFrontCountryCode` equals `USA`, like this: - **App Store Review Tip:** If you choose the in-app sheet option, we strongly suggest showing your Stripe purchase experience to Apple during an App Review before testing with users. We recommend adding the following to your App Review notes: - - > US users will be able to purchase subscriptions or one-time products using Stripe. These users are filtered using their registered App Store country. All other countries will only be able to purchase using Apple IAPs. You can test this by switching your device's registered App Store country. + For App Review, explain that U.S. storefront customers can tap a paywall call to action that opens an external browser for Stripe checkout. Non-U.S. storefront customers should continue using Apple in-app purchase unless another regional policy applies. - - - Since the ruling only applies to customers in the United States, you can easily create a campaign filter that will match to those customers. Just create a filter where `storeFrontCountryCode` matches `USA`, like this: ![](/images/web-checkout-app2web-campaign-filter.png) - From there, the flow works the same way as it would for web checkout. Once the payment succeeds, the [Superwall delegate](/sdk/guides/using-superwall-delegate) functions `willRedeemLink()` and `didRedeemLink(result:)` will be called. You can use these functions to handle the deep link in your app if you need to show any specific UI as described in our [Post-Checkout Redirecting](/sdk/guides/web-checkout/post-checkout-redirecting) docs. + From there, the flow works the same way as web checkout. Once the payment succeeds in the external browser, the [Superwall delegate](/sdk/guides/using-superwall-delegate) functions `willRedeemLink()` and `didRedeemLink(result:)` will be called when the user returns through the deep link. You can use these functions to show any specific UI as described in our [Post-Checkout Redirecting](/sdk/guides/web-checkout/post-checkout-redirecting) docs. Additionally, entitlement and subscription status will update automatically. For lifetime one-time products, the linked entitlement becomes active without an expiration. For consumables, inspect `CustomerInfo.nonSubscriptions` and grant the purchased quantity in your own system. If you're using a `PurchaseController`, refer to [the docs here](/sdk/guides/web-checkout/linking-membership-to-iOS-app#using-a-purchasecontroller). diff --git a/content/docs/web-checkout/web-checkout-sdk-setup.mdx b/content/docs/web-checkout/web-checkout-sdk-setup.mdx index 6ba6cd71..cee63c47 100644 --- a/content/docs/web-checkout/web-checkout-sdk-setup.mdx +++ b/content/docs/web-checkout/web-checkout-sdk-setup.mdx @@ -29,4 +29,4 @@ You'll also need the Superwall SDK integrated in your app. ## Further reading - [Web Checkout FAQ](/web-checkout/web-checkout-faq) -- [App to Web Checkout](/web-checkout/web-checkout-direct-stripe-checkout) — Offer Stripe products directly from your iOS paywalls +- [App to Web Checkout](/web-checkout/web-checkout-direct-stripe-checkout) — Link U.S. storefront customers from iOS paywalls to Stripe checkout in Safari diff --git a/content/shared/web-checkout/post-checkout-redirecting.mdx b/content/shared/web-checkout/post-checkout-redirecting.mdx index 03b41370..54cf2b00 100644 --- a/content/shared/web-checkout/post-checkout-redirecting.mdx +++ b/content/shared/web-checkout/post-checkout-redirecting.mdx @@ -46,7 +46,7 @@ You'll need to implement your own logic to handle the redirect and deep link use ## Setting Up Deep Links -Whether you're showing a checkout page in Safari or using the In-App Browser, the Superwall SDK relies on deep links to redirect back to your app. +Whether checkout starts from a web link or from an iOS paywall that opens Safari, the Superwall SDK relies on deep links to redirect back to your app. #### Prerequisites 1. [Configuring Stripe Keys and Settings](/web-checkout/web-checkout-configuring-stripe-keys-and-settings) diff --git a/redirects-map.ts b/redirects-map.ts index 7e645252..537ba68d 100644 --- a/redirects-map.ts +++ b/redirects-map.ts @@ -141,8 +141,10 @@ export const fileRedirectsMap = { "tips-first-touch-paywall": "dashboard/guides/tips-first-touch-paywall", "tips-paywalls-feature-gating": "dashboard/guides/tips-paywalls-feature-gating", "tips-using-custom-actions": "dashboard/guides/tips-using-custom-actions", - "dashboard/guides/using-stripe-bottom-sheet-checkout-in-app": "dashboard/guides/using-stripe-checkout-in-app", - "using-stripe-bottom-sheet-checkout-in-app": "dashboard/guides/using-stripe-checkout-in-app", + "dashboard/guides/using-stripe-checkout-in-app": "web-checkout/web-checkout-direct-stripe-checkout", + "using-stripe-checkout-in-app": "web-checkout/web-checkout-direct-stripe-checkout", + "dashboard/guides/using-stripe-bottom-sheet-checkout-in-app": "web-checkout/web-checkout-direct-stripe-checkout", + "using-stripe-bottom-sheet-checkout-in-app": "web-checkout/web-checkout-direct-stripe-checkout", // Dashboard / Web Checkout "web-checkout-overview": "web-checkout",