Connect Paddle as your recurring payment provider, register a webhook, and link your packages to Paddle prices.

Note Paddle is a Merchant of Record provider. That means Paddle is the legal seller of your subscriptions and handles sales tax and VAT for you. Your site grants and renews access based on verified webhooks that Paddle sends, so getting the webhook step right matters.

Choose Paddle in the Settings tab

Open the Settings tab of Listeo Subscriptions. At the top you will see a row of provider logos. Click the Paddle logo to make Paddle your active provider. Remember, only one provider can be active for the whole site at a time.

Sandbox or Production?

Paddle keeps test and live completely separate. Decide which one you are setting up first.

  • Sandbox is Paddle’s test environment. Use it to try everything without taking real money.
  • Production is live Paddle. Real customers, real charges.

Important A single Paddle API key works for one environment only. Your Environment dropdown, your API key, your Webhook secret, and your Price IDs must all belong to the same environment. Mixing a sandbox key with production price IDs (or the reverse) will not work.

Fill in the Paddle settings fields

These are the fields you will see once Paddle is selected.

Environment

A dropdown with two choices: Sandbox (the default) or Production. This is your test / live switch. Sandbox uses Paddle’s sandbox; Production uses live Paddle.

  1. API key – A password field for your Paddle API key. The key needs permission to create transactions and read subscriptions. Each key belongs to a single environment, so use a sandbox key for Sandbox and a production key for Production.
  2. Checkout domain – A text field, for example checkout.example.com. This must be your approved Paddle default payment link / checkout domain. It is required because Paddle hosts checkout on your own approved domain. Unlike some providers, there is no fixed pay.paddle.com page to fall back on.

    Paddle Approved Checkout URL
  3. Webhook secret – The secret for your Paddle notification destination. You will create the destination in Paddle in the next step, then copy its secret back into this field.
  4. Client side token – Paddle client-side token (Developer Tools → Authentication). Used to open the Paddle checkout overlay in the browser.

    Paddle Client Side Token

Warning: The Checkout domain must be a domain that Paddle has already approved for you. If it is not approved, checkout will not open for your customers.

 

Listeo Subscripion paddle settings

Where to find your API key

Log in to your Paddle dashboard. Make sure you are in the right environment (sandbox or production) first. Then open the developer / authentication area to create or copy an API key with transaction and subscription access.

Register the webhook in Paddle

Paddle tells your site when payments happen and when subscriptions change. Your site listens at this address and you can copy it from the plugin settings:

Webhook address copy
https://YOUR-SITE.com/wp-json/listeo-recurring-packages/v1/paddle/webhook

Replace YOUR-SITE.com with your real domain.

  1. In Paddle, go to Developer Tools > Notifications.
  2. Create a new notification destination and paste the webhook URL above as its destination.
  3. Subscribe the destination to these events:
    • transaction.completed
    • subscription.created
    • subscription.activated
    • subscription.updated
    • subscription.past_due
    • subscription.paused
    • subscription.resumed
    • subscription.canceled
    • subscription.trialing
  4. Save the destination, then copy its secret key.
  5. Paste that secret into the plugin’s Webhook secret field and save the Settings tab.
Go to Notifications then click New destination

Click “new destination” paste webhook URL from plugin settings. Once webhook is added you need to edit it to retrieve webhook secret:

Edit existing webhook to find secret key
Copy webhook secret

 

Note Paddle signs every webhook with a Paddle-Signature header. The plugin uses your Webhook secret to verify that signature, so it only ever acts on real messages from Paddle.

Important Your server clock must be accurate. Webhook signatures are time-checked with a 5 minute tolerance. If your server time drifts, valid webhooks can be rejected and access may not be granted. Most hosts keep time synced automatically; if in doubt, ask your host.

Connect your packages to Paddle prices

The last step links each Listeo package to a price in Paddle.

  1. In Paddle, create a recurring Price for your product.
  2. Copy that Price ID. It starts with pri_ – do not use product id starting with pro_ it has to be price id starting with _pro
  3. In Listeo Subscriptions, open the Products tab and find the package you want to sell as a subscription.
  4. Paste the Price ID into Sandbox Paddle Price ID (for sandbox) or Production Paddle Price ID (for production), per package.
Step 1: Go to Products
Step 2: Add New Product
Step 3: Add price to product and set monthly/yearly billing
Step 4: Add price to product and set monthly/yearly billing
Step 5: Go to product list and click on newly added product to find pro_ identificator of price
Step 6: Copy pri_xxx to Listeo Subscriptions package settings
Step 7: Paste pri_ in plugin settings for each package

Tip The Sandbox and Production Price ID fields are separate so you can test in sandbox and go live without redoing your mapping. Match each Price ID to the same environment you set in the Environment dropdown. Full details are on the Products & packages page.

One thing Paddle does differently

Important Paddle has no self-serve billing-portal link in the plugin. So your customers will not see a “Manage” button for Paddle the way they do for Stripe, Polar, or Dodo. Instead, customers manage their subscription through the emails and links that Paddle itself sends them. This is normal for Paddle and nothing is wrong with your setup.