--- title: "User Guide: Blesta Paddle Payment Gateway" description: "Take Blesta invoice payments through Paddle Billing. This guide covers installation, the Paddle setup and the gateway settings. ## Installation and setup ### 1. Requirements - Blesta 5.x. - PHP 7.2 or later with the cURL extension (works with PHP…" url: "https://my.topeta.com/docs/blesta-paddle-payment-gateway/setup-guides/user-guide-blesta-paddle-payment-gateway/" updated: "2026-11-07" category: Setup Guides --- # User Guide: Blesta Paddle Payment Gateway Take Blesta invoice payments through Paddle Billing. This guide covers installation, the Paddle setup and the gateway settings. ## Installation and setup ### 1. Requirements - Blesta 5.x. - PHP 7.2 or later with the cURL extension (works with PHP 8.4). - A **Paddle Billing** account. Your API keys start with `pdl_`. Paddle Classic accounts (Vendor ID and Auth Code) are not supported. - The free **Topeta Helper** plugin (Blesta Topeta Framework), which manages your license or free trial key. ### 2. Upload the files 1. Download the gateway .zip from [Downloads & updates](https://my.topeta.com/my-downloads/) in your account. 2. Extract it into `components/gateways/nonmerchant/` in your Blesta installation. 3. The files should end up in `components/gateways/nonmerchant/paddle/`, with `paddle.php` directly in that folder. 4. In Blesta go to **Settings > Payment Gateways > Available** and install **Paddle**. ### 3. Activate your license or free trial 1. Download the free [Topeta Helper plugin](https://my.topeta.com/downloads/blesta-topeta-framework/) and upload its `plugins/topeta_helper/` folder to your Blesta root directory. 2. In Blesta go to **Settings > Company > Plugins > Available** and install **Topeta Helper**. 3. Get a key: start the 15-day free trial or buy a license on the [product page](https://my.topeta.com/downloads/blesta-paddle-payment-gateway/). Your key is in the email and under [Licenses](https://my.topeta.com/licenses/) in your account. 4. Go to **Tools > Topeta Helper**, enter the key next to **Paddle Payment Gateway** and save. The key is checked with my.topeta.com and activated for your Blesta domain. The gateway settings page shows the license state at the top. Without an active license or trial, clients can't start new Paddle payments. Payments already made, webhooks and refunds always keep working. A lifetime license keeps working after its year of updates and support ends. ### 4. Set up Paddle Do these steps in the sandbox dashboard (sandbox-vendors.paddle.com) for test payments, and in the live dashboard (vendors.paddle.com) for real payments. 1. **Default payment link:** go to **Checkout > Checkout settings** and set it to your Blesta URL, for example `https://billing.example.com/`. Paddle won't create payments without it. 2. **Website approval** (live only): ask Paddle to approve your Blesta domain under **Checkout > Website approval**. 3. **API key:** go to **Developer tools > Authentication** and create a key with these permissions: Transactions write, Customers write, Addresses write, Adjustments write and Subscriptions read. 4. **Client-side token:** on the same page, create a client-side token. It starts with `test_` in sandbox and `live_` in live. 5. **Webhook:** go to **Developer tools > Notifications** and add a destination. Use the webhook URL shown on the gateway settings page in Blesta, and select the events `transaction.paid`, `transaction.completed`, `adjustment.created` and `adjustment.updated`. Copy the destination's secret key (it starts with `pdl_ntfset_`). ### 5. Configure the gateway in Blesta 1. Open **Settings > Payment Gateways > Installed > Paddle**. 2. Enter the API key, client-side token and webhook secret under **Sandbox Keys** and, when you are ready, under **Live Keys**. 3. Choose the **Mode**: Sandbox for test payments or Live for real payments. Only the keys for the selected mode are required. 4. Choose how tax is handled and the tax category, then save. The gateway checks the API key with Paddle when you save and tells you if it is wrong. While Sandbox mode is on, clients see a test mode notice on the pay page, so you can't leave it on by mistake. ## How payments work - The client clicks **Pay Now** on the invoice and pays in Paddle's checkout by card, PayPal, Apple Pay or Google Pay. - The payment is recorded in Blesta when the client returns, and again from Paddle's webhook. Blesta records it only once. - If the client opens the pay page again, the same unpaid Paddle checkout is reused for up to 24 hours. ## Tax handling - **Add tax on top** (default): the client pays the invoice amount plus Paddle's tax. Blesta records the invoice amount. - **Tax included**: the client pays exactly the invoice amount, and Paddle takes the tax out of your earnings. - Paddle handles tax, so turn off Blesta's own tax for clients who pay with Paddle to avoid charging tax twice. Tax categories other than Standard need Paddle's approval. ## Refunds - Refund a payment from the Blesta admin, in full or in part. The refund is sent to Paddle, which reviews it before paying it out. - Full refunds and chargebacks made in Paddle mark the payment as refunded or returned in Blesta. Partial refunds made in Paddle are left for you to match up. - Unpaid Paddle payments can be voided from Blesta. ## Automatic renewals (optional) Turn on **Offer subscriptions** to let clients renew automatically. When the amount due matches the service renewal amount, Paddle creates a subscription. Renewal payments are added to the client's credit and applied to the next open invoice. Subscriptions are cancelled in Paddle. ## Troubleshooting - **Clients see "payments are not available right now":** no license or trial is active. Check the license state at the top of the gateway settings page and under **Tools > Topeta Helper**. - **"The API key was rejected by Paddle" when saving:** check that the key belongs to the selected mode (sandbox keys start with `pdl_sdbx_`, live keys with `pdl_live_`) and has the permissions listed above. - **The checkout does not open:** set the default payment link in Paddle, and for live payments make sure your domain is approved. - **Payments are not recorded:** check the webhook URL, the selected events and the webhook secret. The gateway log in Blesta (**Tools > Logs > Gateway**) shows every call to and from Paddle. - **The gateway is not offered at checkout:** enable Paddle for the currency and order form under **Settings > Payment Gateways**. Paddle supports 33 currencies.