Paddle Gateway by Blesta.Club - Product Overview

Welcome, and thank you for choosing the Paddle Gateway! We're delighted to have you as a customer and are committed to ensuring you have a seamless experience. This guide aims to walk you through the installation and configuration of your new gateway. If you're new to Blesta or encounter any issues, please don't hesitate to reach out for support.

Gateway Capabilities

The Paddle Gateway is designed to handle payments within Blesta, allowing seamless integration with your billing system. It supports a variety of payment options via Paddle, making it a flexible and convenient choice for your business.

Things to Note

1. Security: Ensure that your Paddle account is secured with two-factor authentication to prevent unauthorized access.
2. Currency Support: Paddle supports multiple currencies. Be sure to configure your currency settings in Blesta to match those in your Paddle account to avoid processing errors.

This gateway uses Paddle Billing, Paddle's current platform. It is not compatible with legacy Paddle Classic accounts, and it does not use a Vendor ID or Authentication Key.

Quick Support

What You Need From Paddle

The gateway settings ask for three things, all from your Paddle Billing dashboard:

1. API Key - Developer Tools > Authentication > API keys. Create a key with read and write access to products, prices, transactions and adjustments, then copy it. Paddle shows the key once, so store it somewhere safe.

2. Client Side Token - Developer Tools > Authentication > Client-side tokens. This is the public token the checkout overlay runs with; it is safe to expose in the browser.

3. Webhook ID - optional. Leave it blank and Blesta creates the notification for you when you save the settings, subscribed to everything it needs. To manage it yourself instead, go to Developer Tools > Notifications, create a notification destination of type URL, paste in the webhook URL shown read-only at the bottom of the Blesta gateway settings page, and subscribe it to all four of transaction.completed, transaction.payment_failed, adjustment.updated and adjustment.created. Save it, then copy the notification's ID (it starts with ntfset_) into the Webhook ID field.

The webhook is what actually records payments in Blesta, so a missing or misconfigured notification means clients can pay while their invoices stay unpaid. transaction.completed records the payment; the other three record failed payment attempts, refunds approved in the Paddle dashboard, and chargebacks.

Sandbox and Approved Domains

Tick Sandbox in the gateway settings to point the gateway at Paddle's sandbox environment. Sandbox uses a completely separate dashboard with its own API key, client-side token and notification settings - sandbox credentials will not work against live, or vice versa.

Paddle only opens its overlay checkout on domains you have approved. Add your Blesta domain under Checkout > Website approval in the Paddle dashboard, or the payment button will open an empty overlay.

Troubleshooting Common Issues

• Transaction Failures:

  • Verify that your Paddle API credentials are correctly configured, and that the Sandbox checkbox matches the dashboard the credentials came from.

• Currency Mismatch:

  • Ensure that the currencies supported in Blesta match those configured in Paddle to avoid any processing errors.

• Invoice totals and Paddle's tax: the Invoice Amounts setting decides whether Paddle's tax is part of your Blesta invoice total (Include tax, the default - use it with Blesta tax rules or tax-inclusive prices) or added on top of it at checkout (Exclude tax - only for invoices that carry no tax). Pick the one that matches how you invoice; with either, the invoice is applied in full when the client pays.

• Taxable Categories error:

  • This gateway bills under the Website hosting taxable category, which Paddle must approve on your account first (only Standard is enabled by default). Request it under Catalog > Taxable categories. Saving the gateway settings will fail until it is approved.
  • Follow the Paddle guide to enable specific categories https://www.paddle.com/help/start/intro-to-paddle/why-do-i-need-to-select-'taxable-categories'-for-my-products

• Payments not recorded:

  • Check Tools > Logs > Gateway in Blesta. The gateway logs every transaction it creates and every webhook it accepts. No webhook entries means Paddle is not reaching your notification URL, or the notification is not subscribed to transaction.completed. A rejected webhook is logged too, as unverified_signature - that means the notification's endpoint secret no longer matches the one stored here, so re-save the gateway settings.

Contact Us

If you encounter any issues or have suggestions for improving the gateway, please get in touch with us. We are committed to providing robust updates and welcome customer feedback.

Paddle Gateway by Blesta.Club - Installation Guide

Welcome, and thank you for purchasing the Paddle Gateway! We're delighted to have you as a customer and are committed to ensuring you have a seamless experience. This README aims to guide you through the installation of your new gateway. If you're new to Blesta or encounter any issues, please don't hesitate to reach out for support.

Installation Guide

For detailed instructions on how to install the Paddle Gateway, please ensure you have the license manager installed for leased extensions and follow these steps:

1. Obtain the Gateway:

   • Download the Paddle Gateway from the download section of my.blesta.club.

2. Upload to Blesta:

   • Upload the Paddle Gateway to your Blesta gateways directory:

     /var/www/html/blesta/components/gateways/nonmerchant/paddle/

3. Install the Gateway:

   • Log in to your Blesta admin account.
   • Navigate to Settings > Payment Gateways.
   • Find the Paddle Gateway under the "Available" tab and click the "Install" button.

Setting Up the Gateway

This gateway uses Paddle Billing, not the legacy Paddle Classic platform.

1. Create the Webhook in Paddle:

   • The quickest route is to skip this step entirely. Leave the Webhook ID field blank in step 2 and Blesta creates the notification for you, subscribed to all four events it needs, when you save the settings. The field then fills in with the ID Paddle assigned.
   • To use your own notification instead, navigate to Settings > Payment Gateways (/admin/settings/company/gateways/installed/), find "Paddle" and click "Manage". Copy the read-only webhook URL shown at the bottom of the settings form.
   • In your Paddle dashboard, go to Developer Tools > Notifications and create a destination of type URL, using that webhook URL.

   • Subscribe it to all four of these events and save:

     • transaction.completed - records the payment against the invoice.
     • transaction.payment_failed - records failed payment attempts so staff can see them.
     • adjustment.updated - syncs refunds approved in the Paddle dashboard.
     • adjustment.created - syncs chargebacks.

     Subscribing to transaction.completed alone still records payments, but refunds, chargebacks and failed attempts will never appear in Blesta.

   • Copy the resulting notification ID (it begins with ntfset_).

2. Configure the Gateway:

   • Back on the Paddle "Manage" page in Blesta, fill in:
     • API Key - from Developer Tools > Authentication > API keys, with read and write access to products, prices, transactions and adjustments. Automatic webhook creation also needs write access to notification settings.
     • Client Side Token - from Developer Tools > Authentication > Client-side tokens.
     • Webhook ID - leave blank to let Blesta create and manage the webhook, or enter the ntfset_ ID from step 1 to use your own.
     • Invoice Amounts - tells Paddle whether your Blesta invoice totals already include tax. Keep Include tax (the default) if you apply tax rules in Blesta or your prices are tax-inclusive: clients pay exactly the invoice total and Paddle takes its tax out of that amount. Choose Exclude tax only if your Blesta invoices carry no tax at all: Paddle then adds its tax on top of the invoice total at checkout. Never combine Exclude tax with Blesta tax rules, or clients are taxed twice.
     • Sandbox - tick this if the credentials came from Paddle's sandbox dashboard.
   • Click Update. Blesta verifies the API key and webhook ID against Paddle before saving, so a successful save means the credentials work.

3. Approve Your Domain in Paddle:

   • Add your Blesta domain under Checkout > Website approval in the Paddle dashboard. Paddle refuses to open its overlay checkout on unapproved domains.

4. Enable Payment Processing:

   • After configuring, ensure the gateway is enabled for payment processing in your Blesta system.

Taxable category: this gateway bills under Paddle's Website hosting taxable category. Paddle enables only Standard by default, so request Website hosting under Catalog > Taxable categories first - saving the settings fails until it is approved.

You're now done with the installation! Proceed to configure the gateway as needed by following the usage guide.

Contact Us

If you encounter any issues or have suggestions for improving the gateway, please get in touch with us. We are committed to providing robust updates and welcome customer feedback.

Paddle Gateway by Blesta.Club - Update Guide

To ensure you are using the latest version of the Paddle Gateway, follow these steps to update the gateway in your Blesta installation.

Steps for Updating the Gateway

1. Download the Latest Version

• Visit the download section of my.blesta.club to obtain the latest version of the Paddle Gateway.

2. Upload the Updated Gateway

• Upload the updated files to your Blesta installation directory, replacing the existing files:

   /var/www/html/blesta/components/gateways/nonmerchant/paddle/

3. Update the Gateway in Blesta

• Log in to your Blesta admin account.
• Navigate to Settings > Payment Gateways.
• Locate the Paddle Gateway in the list and click the "Upgrade" or "Update" button if available.

4. Clear Cache

• Once the files are uploaded and the gateway is updated, clear the Blesta cache by navigating to Settings > System and selecting "Clear Cache."

5. Check Configuration

• After the update, navigate to Settings > Payment Gateways, manage the Paddle Gateway and click Update once to re-save the settings, even if nothing has changed.

Upgrading to 3.0.0 - check the new Invoice Amounts setting: 3.0.0 no longer leaves the tax treatment to your Paddle account's default. New and upgraded installs start on Include tax: the client pays exactly the Blesta invoice total, Paddle takes its tax out of that amount, and the full invoice total is applied in Blesta. Earlier versions applied only the part left after Paddle's tax, which left taxed clients' invoices partly unpaid; that is fixed. If your Paddle account was set to tax-exclusive pricing and your Blesta invoices carry no tax, switch the setting to Exclude tax after upgrading so Paddle keeps adding its tax on top at checkout as before. Do not use Exclude tax together with Blesta tax rules.

Upgrading to 2.0.0 - one manual step: 2.0.0 records refunds, chargebacks and failed payment attempts, but only if your Paddle notification is subscribed to the events that carry them. Existing installs are subscribed to transaction.completed only, and re-saving the settings does not change that, so do one of the following once:

• In your Paddle dashboard, open Developer Tools > Notifications, edit the notification Blesta uses, and add transaction.payment_failed, adjustment.updated and adjustment.created alongside transaction.completed; or
• In Blesta, manage the Paddle gateway, clear the Webhook ID field and click Update. Blesta then creates a fresh notification subscribed to all four events and fills the field back in. Your old notification is left in place on Paddle and can be deleted there.

Until you do, payments still record exactly as before - only the new refund, chargeback and failed-payment syncing stays inactive.

Upgrading to 1.1.0: re-saving the settings is recommended rather than optional. From 1.1.0 the gateway stores your webhook's endpoint secret locally so that incoming webhooks are verified without an extra call to Paddle, and that secret is captured when the settings are saved. Until you re-save, the gateway falls back to fetching it from Paddle on each webhook, exactly as before, so payments keep working either way.

Checkouts that a client had already opened before the update still complete correctly - the gateway understands both the old and new checkout formats.

Contact Us

If you encounter any issues during the update process or have suggestions for improving the gateway, please reach out to us. We are dedicated to providing robust updates and value customer feedback.

Paddle Gateway by Blesta.Club - Usage Guide

Welcome, and thank you for purchasing the Paddle Gateway! This guide aims to walk you through how to use the Paddle Gateway effectively within Blesta. If you're new to Blesta or encounter any issues, please don't hesitate to reach out for support.

Using the Gateway

Once installed and configured, the Paddle Gateway will allow your clients to use the supported payment methods seamlessly.

Client View

• Clients will see Paddle as a payment method at checkout and invoice payments.
• Clicking "Make Payment" opens Paddle's secure checkout overlay on top of your Blesta page.
• Payments are recorded in Blesta by Paddle's transaction.completed webhook, not by the client returning to your site. A client who closes the browser mid-redirect still has their payment applied once Paddle sends the webhook.
• What the client pays depends on the Invoice Amounts setting. With Include tax the checkout shows the invoice total "inc. VAT" and the client pays exactly that; Paddle keeps its tax out of that amount and the full invoice total is applied in Blesta. With Exclude tax the checkout shows the invoice total plus Paddle's tax, the client pays the sum, and the invoice total (without Paddle's tax) is applied in Blesta. Either way the invoice is paid in full. A discount code entered at checkout is different: only the amount actually collected is applied, so the discounted part stays open on the invoice for you to credit or write off.

Refunds

Staff can refund a Paddle transaction from the client's transaction list in Blesta, either in full or for a partial amount. Notes entered with the refund are passed to Paddle as the refund reason. Refund amounts are stated the same way the payment was recorded: with Include tax a refund of 6.05 returns 6.05 to the client; with Exclude tax a refund of 5.00 returns 5.00 plus the tax Paddle had added on that part, so the client always gets back what they paid.

Note that Paddle is the merchant of record: on live accounts, refunds must be approved by Paddle before money moves. Blesta marks the transaction refunded as soon as Paddle accepts the refund request, but the actual return to the customer happens once Paddle approves it. Voids are not supported by Paddle and the void action will report as unsupported.

Admin View

1. Configuring Payment Settings:

   • Navigate to Settings > Payment Gateways in the Blesta admin panel (/admin/settings/company/gateways/installed/).
   • Customize the payment options, currency settings, and other configurations to match your needs.

2. Enable Paddle for Invoices:

   • Ensure the Paddle Gateway is enabled and accessible on all relevant invoice templates and order forms.

Testing the Gateway

1. Test Mode:

   • Use Paddle's sandbox environment to test transactions before going live. Tick Sandbox in the gateway settings and use credentials from Paddle's sandbox dashboard - sandbox and live credentials are not interchangeable.

2. Mock API Mode:

   • Ticking Mock API makes the gateway serve bundled fixture responses instead of contacting Paddle at all, so you can install it, save settings and walk the payment page end to end with no Paddle account. It is for demos and testing only - never leave it enabled on a production gateway, as no real payment is ever taken.
   • While Mock API is ticked the API Key and Webhook ID are not checked against Paddle - the settings will save successfully whatever you type into them. A gateway that saves cleanly in mock mode has not proven its credentials; untick Mock API and save again to actually validate them.

3. Switch to Live Mode:

   • Once testing is complete, untick Sandbox and Mock API and enter your live credentials.

Troubleshooting Common Issues

1. Transaction Failures:

   • Ensure the Paddle API Key, Client Side Token and Webhook ID are correctly configured in Blesta, and that the Sandbox checkbox matches the dashboard the credentials came from. (This gateway uses Paddle Billing - a Paddle Classic Vendor ID and Authentication Key will not work.)

2. Currency Mismatch:

   • Ensure that the currency settings in Blesta match those supported by Paddle to avoid errors.

3. Taxable Categories error:

   • This gateway bills under the Website hosting taxable category, which must be approved on your Paddle account (only Standard is enabled by default). Request it under Catalog > Taxable categories.
   • Follow the Paddle guide to enable specific categories https://www.paddle.com/help/start/intro-to-paddle/why-do-i-need-to-select-'taxable-categories'-for-my-products

4. Client paid but the invoice is still unpaid:

   • Check Tools > Logs > Gateway. The gateway logs each transaction it creates and each webhook it accepts. If no webhook entries appear, Paddle is not reaching your notification URL - re-check the destination URL and that it is subscribed to transaction.completed, transaction.payment_failed, adjustment.updated and adjustment.created. An entry logged as unverified_signature means Paddle is reaching you but the notification's endpoint secret no longer matches the one stored here - re-save the gateway settings to refresh it.

5. The checkout overlay opens empty:

   • Paddle only opens checkouts on approved domains. Add your Blesta domain under Checkout > Website approval in the Paddle dashboard.

Contact Us

If you encounter any issues or have suggestions for improving the gateway, please get in touch with us. We are committed to providing robust updates and welcome customer feedback.