> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Paddle Credentials

> Where to get your Paddle API key and where to paste it in the Qonversion dashboard.

To connect Paddle, Qonversion needs a Paddle **API key**. Qonversion uses this key to register the webhook destination on your Paddle account automatically (you don't need to create the webhook yourself) and to read your products, transactions, subscriptions, refunds, and customers so it can grant entitlements and report revenue.

## Required permissions

Grant the API key the permissions below when you create it. Qonversion validates the key on connect and reports a missing **Notification settings: Write** scope explicitly, but the read scopes are required for ongoing processing — a key without them connects but then fails to sync data or map customers to users.

| Paddle entity         | Access       | Used for                                                                                                                                    |
| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Notification settings | Read & Write | Registering and verifying the webhook destination Qonversion creates for you                                                                |
| Products              | Read         | Validating the key on connect and matching your Paddle products                                                                             |
| Transactions          | Read         | Reading purchase / transaction details for analytics and entitlements                                                                       |
| Subscriptions         | Read         | Tracking renewals, plan changes, and cancellations                                                                                          |
| Adjustments           | Read         | Detecting refunds                                                                                                                           |
| Customers             | Read         | Resolving the buyer to a Qonversion user (the `custom_data` fallback — see [Send Paddle Purchases to Qonversion](initiate-purchase-paddle)) |

## 1. Get your Paddle API key

Paddle keeps **Production** and **Sandbox** in fully separate environments, each with its own API key. Generate the key in the environment you want to connect.

* **Production** — open [Paddle Developer Tools → Authentication](https://vendors.paddle.com/authentication-v2). Production keys start with `pdl_live_`.
* **Sandbox** — sign in to the [Paddle sandbox dashboard](https://sandbox-vendors.paddle.com) and open [Developer Tools → Authentication](https://sandbox-vendors.paddle.com/authentication-v2). Sandbox keys start with `pdl_sdbx_`. If you don't have a sandbox account yet, [sign up here](https://sandbox-login.paddle.com/signup).

Create a new API key (or copy an existing one) with the permissions listed in [Required permissions](#required-permissions) above, and copy its value.

<Warning>
  Treat the API key like a password. Paddle shows it in full only once when created — copy it immediately. After you connect it, Qonversion only ever displays a masked value, never the full key.
</Warning>

## 2. Paste the key into Qonversion

1. Open **Project Settings → Stores** in the [Qonversion dashboard](https://dash.qonversion.io/project-settings/stores) and find the **Paddle** card.
2. Click **Configure Paddle** to open the Paddle drawer. Production and Sandbox are managed side by side.
3. In the matching mode section, paste your API key into the **API Key** field and click **Connect Production** or **Connect Sandbox**.

Once connected, the section shows a **Connected** badge and the masked key. Qonversion registers the webhook destination on your Paddle account at this point — there is no separate webhook secret to paste.

## 3. Verify the connection

After connecting, use the buttons in the Paddle drawer to confirm everything works:

* **Test Connection** — checks that the saved API key is valid.
* **Test Webhook** (Sandbox) — confirms a webhook fired by Paddle reaches Qonversion.

A green result means the credentials are valid and Qonversion is receiving Paddle notifications. If a test fails, double-check that you copied the key for the correct environment and that it has all of the [required permissions](#required-permissions) — in particular **Notification settings: Write**.

<Warning>
  If connecting fails because a Paddle notification destination already exists for this webhook URL but wasn't created by Qonversion, delete (or rename) that destination in Paddle under **Developer Tools → Notifications**, then connect again.
</Warning>

<Warning>
  Make sure to connect your **Production** API key before going live. Sandbox credentials cannot process real charges.
</Warning>

***

[Paddle Integration](paddle-integration)

[Test Purchases — Paddle](test-purchase-paddle)