Stripe Onboarding Guide

​

What You’ll Accomplish

• A Stripe account connected to Helium, with products synced and ready to add to paywalls.
• Paywalls that offer Stripe products.
• A hosted web checkout flow that lets users purchase in their browser and deep-links them back into your app.
• Entitlement tracking across Stripe, the Helium SDK, and (optionally) RevenueCat.

​

Prerequisites

• The Helium SDK already integrated in your app.
• A deep link scheme or universal link configured in your app — users need a way back into your app after purchase.
• Admin access to your Helium dashboard.

​

Implementation Steps

​

1. Connect Stripe to Helium

​

2. Adjust Stripe Products

​

3. Build your paywalls

1. The original paywall, shown in-app, containing your Stripe products (we recommend adding iOS products too as a backup if user decides to not use Stripe).
2. A hosted web paywall, which runs the actual Stripe checkout in the user’s browser on clickthrough.to.

1. Create the original paywall and add Stripe products to it.
2. Create a hosted web paywall (the editor will prompt you).
3. Link the two. The original paywall can’t be published without a linked hosted web paywall.

​

4. SDK integration

Helium.config.enableExternalWebCheckout(
  redirectURL: "yourapp://openapp",
  paymentProcessors: .stripe
)

if await Helium.entitlements.hasActiveStripeEntitlement() {
    // show the manage subscription button
}

// when the button is tapped:
do {
    let url = try await Helium.shared.createStripePortalSession()
    UIApplication.shared.open(url)
} catch {
    print("Failed to open customer portal: \\(error)")
}

enableExternalWebCheckout({
  redirectURL: "yourapp://openapp",
  paymentProcessors: ["stripe"],
});

useEffect(() => {
  const sub = Linking.addEventListener('url', (event) => heliumHandleURL(event.url));
  void Linking.getInitialURL().then(heliumHandleURL);
  return () => sub.remove();
}, []);

if (await hasActiveStripeEntitlement()) {
    // show the manage subscription button
}

// when the button is tapped:
const url = await createStripePortalSession();
if (url) {
  await Linking.openURL(url);
}

await HeliumFlutter().enableExternalWebCheckout(
  redirectURL: "yourapp://openapp",
  paymentProcessors: {HeliumWebCheckoutProcessor.stripe},
);

_linkSubscription = AppLinks().uriLinkStream.listen((uri) {
  HeliumFlutter().handleURL(uri.toString());
});

final hasStripe = await HeliumFlutter().hasActiveStripeEntitlement();
if (hasStripe) {
    // show the manage subscription button
}

// when the button is tapped — returnUrl is where Stripe sends the user
// back after they're done managing their subscription:
final urlString = await HeliumFlutter().createStripePortalSession(
  returnUrl: "yourapp://openapp",
);
if (urlString != null) {
  await launchUrl(Uri.parse(urlString));
}

​

5. (Optional) Connect RevenueCat

1

Visit your RevenueCat Account Settings and find the Connect Stripe button

2

Install the Revenue Cat app to your Stripe account

3

Open RevenueCat Dashboard

• Open the dashboard: https://app.revenuecat.com/
• Select your Project > Apps & Providers > Add Web Config
• Find your Stripe account and complete the flow

4

Select the Stripe web configuration you just added and configure Stripe webhooks to send to RevenueCat

• Open the dashboard: https://www.revenuecat.com/docs/platform-resources/server-notifications/stripe-server-notifications
• Make sure to include these events:
  1. customer.subscription.updated
  2. customer.subscription.deleted
  3. charge.refunded
  4. invoice.updated
  5. customer.subscription.created
  6. checkout.session.completed

5

Enable Track new purchases from server-to-server notifications

Make sure to enter rc_user_id as the Metadata field key:

6

Configure your Stripe products with RevenueCat

1. Visit Product catalog for your desired project in RevenueCat dashboard.
2. In the Products tab, find the Stripe section and add Stripe products
3. Go to Entitlements tab, select desired entitlement/s, click Attach and add the Stripe products you just created
4. If you rely on Offerings in your RevenueCat integration, you can also add the Stripe products there

​

Testing

• Stripe eligible users
• sandbox or debug environment

1. Happy path purchase. Open an App2Web paywall in-app, tap a web product, and confirm the app correctly opens the browser. Complete the standard purchase flow, then confirm you’re deep-linked back with an active entitlement. Dismiss the paywall before purchasing as well, and confirm the app returns to the expected screen.
2. Entitlement sync. After purchase, confirm hasActiveStripeEntitlement() returns true immediately, and that RevenueCat (if connected) updates within a few seconds.
3. Cancel flow. Open the customer portal from your app, cancel a subscription, and confirm the entitlement expires at period end.
4. Canceled checkout. Back out of the checkout page without paying and confirm you’re deep-linked back to the app with no entitlement granted and no success state shown.
5. Pre-login purchase (if applicable). If your App2Web paywall can be shown before you set a durable user_id, make a purchase before setting it. Set the durable user ID afterwards and confirm the entitlement attaches correctly.

​

Appendix

​

How entitlements work

​

Why two paywalls?

​

Apple Pay readiness

Helium.config.enableWebApplePayReadiness = false
Helium.initialize(...)

setEnableWebApplePayReadiness(false);

setEnableWebApplePayReadiness(false);

await HeliumFlutter().setEnableWebApplePayReadiness(false);

​

Known limitations and gotchas

• Availability: Stripe App2Web is currently supported for US storefronts only.
• Publish states: both the original paywall and its linked hosted web paywall must be published before the flow works end-to-end.
• Localizations: hosted web paywalls currently support one language.
• Testing: App2Web previews and SDK requirements cover simulated purchases and real purchases on eligible US devices. Also test through a real trigger to verify targeting and your post-purchase handlers.

​

Before you go live