Paddle Onboarding Guide

​

What You’ll Accomplish

• A Paddle account connected to Helium, with products synced and ready to add to paywalls.
• Paywalls that offer Paddle products — either on their own or alongside iOS IAPs.
• A hosted web checkout flow that lets users purchase in their browser and deep-links them back into your app.
• Entitlement tracking across Paddle, the Helium SDK, and (optionally) RevenueCat.
• Free trials with built-in abuse protection (one trial per customer, per lifetime).
• A “Manage Subscription” flow that routes users to Paddle’s customer portal.

​

Prerequisites

• A Paddle account. If you don’t have one, start with Paddle’s setup checklist and onboarding overview.
• The Helium SDK (iOS native, React Native/Expo, or Flutter) already integrated in your app.
• A deep link scheme configured in your app — users need a way back into your app after purchase.
• Admin access to your Helium dashboard.
• (Optional) A RevenueCat account, if you want Paddle purchases to reflect in RevenueCat entitlements.

​

Implementation Steps

​

1. Set up your Paddle account

1. Sign up for Paddle and complete their onboarding checklist (KYC, banking, tax info). Live payments are blocked until this is done.
2. Add your products and prices in the Paddle dashboard. Paddle’s product creation guide is the canonical reference.

​

2. Connect Paddle to Helium

​

3. Default payment link

1. Go to Paddle website approval and add a new domain.
2. Go to Paddle Checkout Settings and find the Default payment link section. Paste in the same domain you just added for Paddle website approval.
3. At the top of the same page, make sure Apple Pay has been selected as a Payment Method

​

4. Sync your Paddle products

​

5. (Optional) Add free trials

• One trial per customer, ever. Paddle doesn’t natively prevent trial abuse (a user could start a trial, cancel, and start another), so Helium enforces this at the entitlement layer. Once a customer has held a trial — even if they cancel — they won’t be offered another.
• A payment method is required up front. Payment is deferred, not skipped.

​

6. Build your paywalls

1. The original paywall, shown in-app, containing your Paddle products (and optionally iOS products).
2. A hosted web paywall, which runs the actual Paddle checkout in the user’s browser on clickthrough.to.

1. Create the original paywall and add Paddle 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.

​

7. SDK integration

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

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

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

let paddleCustomerId = await Helium.shared.getPaddleCustomerId()

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

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

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

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

const paddleCustomerId = await getPaddleCustomerId();

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

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.yourcompany.yourapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

import 'package:app_links/app_links.dart';

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

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

// when the button is tapped:
final urlString = await HeliumFlutter().createPaddlePortalSession();
if (urlString != null) {
  await launchUrl(Uri.parse(urlString));
}

​

8. (Optional) Connect RevenueCat

1. Create a Paddle web configuration in the RevenueCat dashboard.
   1. Select your project > Web > Add web provider > Paddle
   2. Create a new Paddle API Key for RevenueCat. See permissions below
   3. Paste in the new Paddle API key
   4. Purchase tracking should be Automatic
   5. Under App user ID matching select Use a custom field with rc_user_id as the field key
2. Go to Product catalog > Products and Import your Paddle products into RevenueCat.
3. Attach those products to desired entitlement(s).

​

Testing

• Paddle 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 hasActivePaddleEntitlement() 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. Webhook delivery. In the Paddle dashboard, confirm webhooks are reaching Helium with 2xx responses.
6. 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: Paddle App2Web is currently iOS-only and supported for US storefronts only. iOS-only applies across all SDKs — in React Native and Flutter apps, the web-checkout APIs are safe no-ops on Android, so shared code can ship unchanged and Android users keep your regular in-app purchase flow.
• California compliance for subscription cancellation: guidance coming soon.
• 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: Paywall Previews and SDK requirements cover simulated purchases and real purchases on eligible devices. Before launch, also open the flow through a real trigger: previews bypass targeting and do not exercise paywall traits or post-purchase handlers.

​

Before you go live