Payments - Paddle setup

Paddle is a Merchant of Record: it issues invoices to your customers, collects VAT and sales tax across supported countries on your behalf, and handles compliance automatically. You get paid without worrying about global tax filings.

web2app connects directly to your own Paddle account. Every payment goes straight to you.

Step 1 - Create a Paddle account

1. Go to paddle.com and sign up.
2. Complete the onboarding: business details, payout method, and account approval. Paddle reviews new accounts before you can charge live customers.

Step 2 - Get your API keys

Paddle needs three values: an API Key (server-side), a Client-side Token (browser-side), and a Webhook Secret (added later).

API Key:

1. In the Paddle Dashboard, go to Developer Tools -> Authentication -> API keys.
2. Click Generate API key, give it a name such as "web2app", and copy the key.
3. Grant only the permissions web2app needs.

Recommended API key permissions

web2app uses the Paddle API key only to create a transaction before opening Paddle Checkout. It does not create products, prices, refunds, discounts, reports, or notification settings.

Leave unrelated permissions off, including adjustment.write, subscription.write, product.write, price.write, report.write, notification_setting.write, and customer_portal_session.write. Refunds and subscription management should be handled in Paddle Dashboard unless you intentionally add those flows later.

Client-side Token:

1. In the same menu, go to Client-side tokens.
2. Click Generate client-side token, give it a name, and copy the token.

The client-side token is safe to use in the browser. web2app uses it only to initialize Paddle.js and load the inline checkout frame.

Step 3 - Connect Paddle in Settings

1. In the dashboard sidebar, open Settings.
2. In the Active payment processor toggle, select Paddle.
3. Paste your API Key and Client-side Token -> click Save.

The page will now show a Webhook endpoint URL unique to your workspace. You'll use it in the next step.

Step 4 - Create a webhook notification

Paddle sends events to web2app when a payment completes, a subscription renews, a subscription is cancelled, or an adjustment/refund is created.

1. In the Paddle Dashboard, go to Developer Tools -> Notifications -> New notification.
2. Set Type to Webhook (URL).
3. Copy your Webhook endpoint URL from Settings and paste it into the URL field.
4. Under Events, select:
   • transaction.completed
   • subscription.activated
   • subscription.updated
   • subscription.canceled
   • adjustment.created
5. Click Save.
6. Open the notification you just created and copy the Secret key (it starts with pdl_ntfset_ or similar).
7. Back in Settings, paste it into Webhook Secret Key -> Save again.

Step 5 - Create a Price in Paddle

For each paid plan in your funnel you need a Paddle Price ID.

1. In the Paddle Dashboard, go to Catalog -> Products -> New product.
2. Fill in the product name and description.
3. Click Add price and configure:
   • Billing period - Monthly, Yearly, Weekly, or One-time
   • Amount and currency
   • Optional trial period
4. Save the product.
5. Click on the price you created and copy the Price ID. It starts with pri_, for example pri_01AbCdEfGhIjKlMn.

Step 6 - Attach the Price ID to a plan

1. Open your funnel in the editor.
2. Click the Paywall step.
3. Open the Pricing section and find the plan you want.
4. Paste the Price ID into the Paddle Price ID field.
5. Set Billing in the editor to match what you chose in Paddle (Weekly / Monthly / Yearly / One-time).
6. Save the step.

Repeat for each plan that should charge through Paddle.

Step 7 - Publish and test

1. Publish the funnel.
2. Use Preview from the editor for a quick checkout check, or use Copy link for a full live-link test.
3. Complete the flow to the Checkout step.
4. The Paddle checkout frame will load directly on the page. Use a Paddle sandbox card to complete a test payment.
5. Check Subscribers in the dashboard. The payment should appear within seconds.

How the Paddle checkout works

When a visitor reaches the Checkout step with Paddle active, web2app embeds the Paddle checkout frame directly on your funnel page. Paddle shows the eligible card, wallet, and local payment methods inside the frame, processes the payment, and sends the visitor to your Success step.

Billing periods reference

What happens after payment

• Subscriptions: Paddle handles renewals automatically. Status updates (renewal, past due, cancelled) sync to Subscribers in real time via webhook.
• One-time / Lifetime: a single charge; no renewal.
• The visitor is sent to your Success step.

Troubleshooting