Paddle Billing For WHMCS

1. Installation

1. Download the module .zip file you received upon purchase.
2. Extract the contents of the ZIP file.
3. Upload the extracted modules folder directly to the root directory of your WHMCS installation. (This will merge the files into your-whmcs/modules/gateways/... and your-whmcs/modules/addons/... without overwriting anything else).

2. Activate the Gateway & Enter Your License

Before configuring Paddle, you must activate the module and validate your software license.

1. Log in to your WHMCS Admin Area.
2. Navigate to ???? System Settings (the gear icon) > Payment Gateways.
3. Click on the All Payment Gateways tab.
4. Click on Paddle Billing to activate it.
5. In the configuration screen that appears, enter your License Key in the designated field.
6. Check the box for Show on Order Form.
7. Click Save Changes.

⚙️ 3. Obtaining Your Paddle API Keys

You need three credentials from your Paddle Dashboard to connect WHMCS.

1. Log in to your Paddle Vendor Dashboard.
2. Navigate to Developer Tools > Authentication.
3. API Key: Click Generate API Key. Name it "WHMCS Integration" and copy the key.
4. Client-Side Token: Scroll down to Client-side tokens and click Generate Token. Name it "WHMCS Checkout" and copy it.
5. Paste these two keys into their respective fields in the WHMCS Payment Gateways configuration screen.

4. Setting up Webhooks (Automated Payments)

Webhooks are critical. They allow Paddle to securely tell WHMCS when a customer has successfully paid so WHMCS can mark the invoice as "Paid" automatically.

1. In your Paddle Dashboard, navigate to Developer Tools > Webhooks.
2. Click New Webhook.
3. URL: Enter your WHMCS callback URL. It will look exactly like this:
   https://yourdomain.com/modules/gateways/callback/paddlebilling.php (replace yourdomain.com with your actual WHMCS domain).
4. Events: Check the boxes for the following events:
   • transaction.paid
   • subscription.created
   • subscription.canceled
5. Click Save.
6. Once saved, click on the webhook you just created to view its details. Locate the Webhook Secret Key and copy it.
7. Go back to your WHMCS Payment Gateways configuration screen and paste this into the Webhook Secret field.
8. Click Save Changes in WHMCS.

5. Configuring Gateway Features

Our module includes several powerful features that you can configure directly from the WHMCS Payment Gateways screen:

Checkout Theme

Choose whether the Paddle payment overlay appears in Light mode or Dark mode to best match your brand's website.

Sales Tax Settings

Choose how Paddle calculates tax for the prices sent from WHMCS. This synchronizes WHMCS with Paddle's native tax engine:

• Sync with Paddle Dashboard (Default): Uses whatever setting you have configured globally in your Paddle dashboard.
• Automatic based on location: Paddle dynamically calculates whether the price includes or excludes tax based on the buyer's country laws.
• Price includes tax: Tells Paddle that the WHMCS invoice total already has tax baked in.
• Price excludes tax: Tells Paddle to calculate and add tax on top of the WHMCS invoice total. (Note: Do not use this if WHMCS is also adding tax, or your customer will be double-taxed!)

How It Works (Features)

This module goes far beyond a basic checkout. Here is what happens behind the scenes:

Intelligent Subscription Split
If a customer checks out with a mixed cart (e.g., a monthly hosting plan and a one-time setup fee or promo code discount), the module automatically splits the payload. It applies Dynamic Inline Discounts to ensure the customer pays the exact discounted price today, but securely locks in the true recurring price so their subscription renews at the correct amount next month!

Native WHMCS Refunds
You never have to leave WHMCS to issue a refund. Simply view an invoice in WHMCS, click the Refund tab, enter the amount, and submit. The module uses Paddle's v3 Adjustments API to instantly process both Full and Partial refunds.

Automated Subscription Cancellations
When a client requests a cancellation, or WHMCS automatically terminates an overdue service, the module instantly sends a termination signal to Paddle. This immediately cancels the underlying billing agreement, ensuring your customer is never accidentally charged after their service ends.

Admin Webhook Logs
To help you troubleshoot, you can navigate to Addons > Paddle Billing v3 Addon in your WHMCS admin area. Here, you can view the raw data of every webhook Paddle has sent to your server.

Having trouble? Ensure your License Key is active and your Webhook Secret exactly matches the one in your Paddle Dashboard.