User Guide: Blesta Paddle Payment Gateway

< 1 min read

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 #

Download the gateway .zip from Downloads & updates in your account.
Extract it into components/gateways/nonmerchant/ in your Blesta installation.
The files should end up in components/gateways/nonmerchant/paddle/, with paddle.php directly in that folder.
In Blesta go to Settings > Payment Gateways > Available and install Paddle.

3. Activate your license or free trial #

Download the free Topeta Helper plugin and upload its plugins/topeta_helper/ folder to your Blesta root directory.
In Blesta go to Settings > Company > Plugins > Available and install Topeta Helper.
Get a key: start the 15-day free trial or buy a license on the product page. Your key is in the email and under Licenses in your account.
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.

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.
Website approval (live only): ask Paddle to approve your Blesta domain under Checkout > Website approval.
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.
Client-side token: on the same page, create a client-side token. It starts with test_ in sandbox and live_ in live.
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 #

Open Settings > Payment Gateways > Installed > Paddle.
Enter the API key, client-side token and webhook secret under Sandbox Keys and, when you are ready, under Live Keys.
Choose the Mode: Sandbox for test payments or Live for real payments. Only the keys for the selected mode are required.
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.