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 iOS SDK 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.
• Intro pricing (e.g., $1.99 for the first 3 months, then $9.99/mo) is not yet supported.

​

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(
  successURL: "yourapp://openapp",
  cancelURL: "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)")
}

enableExternalWebCheckout(
  successURL: "yourapp://openapp",
  cancelURL: "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);
}

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

_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 url = await HeliumFlutter().createPaddlePortalSession();
if (url != null) {
  final Uri url = Uri.parse(url);
  await launchUrl(url);
}

​

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

1. Happy path purchase. Open a Paddle paywall in-app, tap a product, complete checkout in the browser, and confirm you’re deep-linked back with an active entitlement.
2. Entitlement sync. After purchase, confirm hasActivePaddleEntitlement() returns true immediately, and that RevenueCat (if connected) updates within a few seconds.
3. Free trial. Purchase a trial product, cancel it, and confirm the trial is no longer offered on re-purchase.
4. Cancel flow. Open the customer portal from your app, cancel a subscription, and confirm the entitlement expires at period end.
5. Pre-login purchase. Make a purchase before setting a user ID. After you set the user ID, confirm the entitlement attaches correctly.
6. Abandoned checkout. Close the browser mid-checkout and confirm the app handles the cancel URL gracefully.
7. Webhook delivery. In the Paddle dashboard, confirm webhooks are reaching Helium with 2xx responses.

​

Appendix

​

How entitlements work

​

Why two paywalls?

​

Why are success/cancel URLs set in the SDK?

​

Known limitations and gotchas

• Intro pricing ($X for first N months, then $Y/mo) is not yet supported.
• 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: if you support multiple languages in-app, confirm your hosted web paywall’s localizations match.
• Prepaid card failures / declined payments: the user is returned via the cancelURL. Your app should treat this as “no purchase made.”