---
title: Paddle
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕
---
import ngrok from '@assets/ngrok.png';
import { Image } from 'astro:assets';
First, make sure you've defined your payment processor in `src/payment/paymentProcessor.ts` and `src/payment/paymentProcessorClient.ts`, as described in the [important first steps](/guides/payment-integrations/).
Next, you'll need to create a Paddle account in the sandbox mode. You can do that [here](https://sandbox-vendors.paddle.com).
:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!
If you're finding this template and its guides useful, consider giving us [a star on GitHub](https://github.com/wasp-lang/wasp)
:::
### Sandbox and Production Mode
Paddle features two separate environments:
- [Sandbox](https://sandbox-vendors.paddle.com).
- [Production](https://vendors.paddle.com).
They are fully isolated from each other, which means that you need to create separate accounts for each of them. They also feature independent products, prices, API keys, etc.
For local development and testing, you'll want to use Paddle's sandbox mode.
To enable sandbox mode, make sure that `PADDLE_SANDBOX_MODE` is set to `true` in your `.env.server` file, and `REACT_APP_PADDLE_SANDBOX_MODE` is set to `true` in your `.env.client` file:
```ini title=".env.server"
PADDLE_SANDBOX_MODE=true
```
```ini title=".env.client"
REACT_APP_PADDLE_SANDBOX_MODE=true
```
When you're ready to [deploy your app](/guides/deploying/), we'll remind you to set these to `false`.
### Paddle API Key
Once you've created your account, you'll need to get your API key.
You can do that by:
1. Navigating to `My Account > Settings`.
2. Opening the `Developer Tools > Authentication` page.
3. Click on the `New API key` button to create a new key.
4. Give your key a name (e.g., "Open SaaS Development").
5. Select the following permissions:
- `Customer portal sessions`: write
- `Customers`: read and write
- `Metrics`: read
- `Reports`: read
- `Transactions`: read and write
6. Copy the generated key and add it to your `.env.server` file:
```ini title=".env.server"
PADDLE_API_KEY=pdl_sdbx_apikey_...
```
### Paddle Client-side Token
Paddle's checkout runs in the browser with [Paddle.js](https://developer.paddle.com/paddle-js), which needs a client-side token.
You can get one by:
1. Navigating to `My Account > Settings`.
2. Opening the `Developer Tools > Authentication` page.
3. Selecting the `Client-side tokens` tab.
4. Click on the `New client-side token` button to create a new token.
5. Give your token a name (e.g., "Open SaaS Development Client").
6. Copy the generated token and add it to your `.env.client` file:
```ini title=".env.client"
REACT_APP_PADDLE_CLIENT_TOKEN=test_...
```
### Default Payment Link
Paddle requires a [default payment link](https://developer.paddle.com/build/transactions/default-payment-link) before it can open a checkout. Paddle doesn't accept `localhost` URLs, but in sandbox mode the link isn't actually visited, so you can use `https://example.com`.
To set it:
1. Navigate to `Checkout > Checkout configuration`.
2. Set the `Default payment link` to `https://example.com`.
3. Click `Save`.
In production, you'll need to set it to your deployed app's URL. We'll remind you to do that when you [deploy your app](/guides/deploying/#setting-the-default-payment-link).
### Creating Products
To create Paddle products, in your Paddle dashboard:
1. Navigate to the `Catalog > Products` page.
2. Click on the `+ New product` button to create a new product.
3. Fill in the product details and click `Save`.
4. Click on your newly created product in the `Catalog > Products` list to open its product page.
5. On the product page, click on the `New Price +` button.
- Fill in the `Internal description` (e.g. "Monthly"). It's required, but isn't shown to your customers.
- Set the `Base price` (e.g. `9.99`).
- For subscription products, select a `Recurring` billing period (e.g. monthly).
- For one-time payment products, select `One-time`.
- Set the quantity to a minimum of `1` and a maximum of `1`. Open SaaS grants one plan (or one pack of credits) per purchase, so customers shouldn't be able to buy more than one at a time.
6. Click `Save`.
7. Copy the `Price ID` (it starts with `pri_`). Note that Open SaaS uses the price ID, not the product ID.
8. Add the `Price ID` to your `.env.server` file.
Open SaaS by default expects three products, two subscriptions and one one-time purchase plan:
```ini title=".env.server"
PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_ID=
PAYMENTS_PRO_SUBSCRIPTION_PLAN_ID=
PAYMENTS_CREDITS_10_PLAN_ID=
```
:::note[Naming products differently]
Note that if you change names of your products, you'll need to update your app code in `src/payment/plans.ts` and `src/payment/paymentProcessorPlans.ts` to match these names as well.
:::
### Using Paddle Webhook in Local Development
#### Exposing your Webhook Endpoint to the Internet
Paddle notifies your Wasp app about customer and payment events through a webhook. However, to make it available to Paddle during development, you need to expose your locally running Wasp server (started with `wasp start`) to the internet.
You can do that by running `ngrok` on port 3001 (Wasp server runs on port 3001 by default). `ngrok` will then generate a public URL that we can provide to Paddle:
1. First, make sure you have installed [`ngrok`](https://ngrok.com/docs/getting-started/).
2. Once `ngrok` is installed and your Wasp app is running, run:
```sh
ngrok http 3001
```
3. `ngrok` will display a forwarding address. Copy this address and append `/payments-webhook` to it. It should look something like this:
```sh title="Callback URL"
https://89e5-2003-c7-153c-72a5-f837.ngrok-free.app/payments-webhook
```
#### Creating your Paddle Webhook
Next, configure the webhook in your Paddle dashboard:
1. Navigate to the `Events > Notifications` page.
2. Click the `+ New destination` button.
3. Fill in the `Description` (e.g. "Open SaaS Development").
4. Set the `Notification Type` to `Webhook`.
5. In the URL field, paste your `ngrok` forwarding address with `/payments-webhook` appended (for example: `https://abc123.ngrok-free.app/payments-webhook`).
6. Set the `Usage type` to `Both`.
7. Select the following events to listen for:
- `transaction.completed`
- `subscription.updated`
- `subscription.canceled`
8. Click `Save`.
9. Click on your newly created destination in the `Events > Notifications` list to open it.
10. Click copy on the `Secret key` and add it to your `.env.server` file:
```ini title=".env.server"
PADDLE_WEBHOOK_SECRET=pdl_ntfset_...
```
### Testing Payments in Local Development
Before testing payments, make sure that you created and set all the required env variables in `.env.server` (`PADDLE_API_KEY`, `_PLAN_ID` and `PADDLE_WEBHOOK_SECRET`) and `.env.client` (`REACT_APP_PADDLE_CLIENT_TOKEN`), that you set a default payment link, and that your `ngrok` tunnel is running.
You can then test the payment flow:
1. Click a `Buy` button for any product on the homepage.
2. Paddle's checkout should open as an overlay on the page.
3. Fill in the checkout form with [test payment information](https://developer.paddle.com/sdks/sandbox).
4. Complete the payment.
5. You should be redirected to the checkout success page.
To verify everything executed correctly you can:
- Check Paddle webhook event logs:
1. Navigate to the `Events > Notifications` page.
2. Open your previously created destination.
3. Confirm all of the events have been delivered successfully.
- Inspect your database's `User` table:
1. Run Wasp DB studio:
```sh
wasp db studio
```
2. Navigate to `localhost:5555` and check the `User` table.
3. Confirm the `subscriptionStatus` is `active` for the user who made the purchase.