???? Paddle Billing v3.0 – Installation & Configuration Guide
Welcome! This guide will help you install and configure Paddle Billing v3.0 for WHMCS in a simple and friendly way.
Version 3.0 improves reliability, recurring billing handling, refunds, webhook security, conversion accuracy, admin-side tools, and overall system stability.
???? About the Module
Paddle Billing consists of two parts working together:
???? Addon Module
Handles webhooks, refunds, credit notes, internal processing, logging, and admin-side tools.
???? Gateway Module
Handles checkout, payment processing, client-side experience, subscriptions, and one-time payments.
???? What Clients Can Do
- Pay custom invoices
- Pay billable items
- Pay domains
- Pay or subscribe to products
- Pay or subscribe to addons
- Choose between one-time and subscription payment when supported
- Cancel subscriptions
???????? What Admins Can Do
- Issue full and partial refunds
- View Paddle credit notes for refunds
- Track webhook events and logs
- Automatically manage recurring billing behavior more reliably
???? Installation Steps
- Download the latest module package from your iBeeHost account.
- Extract the ZIP file.
- Upload the extracted files into your WHMCS root directory.
⚙️ Activate the Addon Module
You must activate the addon module first.
- Go to System Settings > Addon Modules
- Find Paddle Billing
- Click Activate
- Then click Configure
Enter the following details:
- License Key – from your iBeeHost account
- API Key – from your Paddle account
- Sandbox Mode – enable only if you are testing
Click Save Changes.
???? Activate the Paddle Billing Gateway
For WHMCS 8.0 and Above
- Go to System Settings > Payment Gateways
- Click Visit Apps & Integration
- Search for Paddle Billing
- Click it and then click Activate
For WHMCS Versions up to 7.10
- Go to System Settings > Payment Gateways
- Find Paddle Billing
- Click it to activate
⚙️ Configure the Gateway
Go to:
System Settings > Payment Gateways > Paddle Billing
Configure the following options:
- Show on Order Form – enable this to make the gateway visible to clients
- License Key – from iBeeHost
- Paddle API Key – from your Paddle account
- Paddle Client-Side Token – from your Paddle account
- Sandbox Mode – enable only when testing
- Checkout Theme – choose Light or Dark based on your website style
- Convert To for Processing – optional and fully supported in v3.0
Version 3.0 supports WHMCS Convert To properly and handles conversion more efficiently. This also allows merchants to use WHMCS currencies that Paddle does not directly support by converting them into a supported Paddle currency during processing.
Click Save Changes.
???? Set Up Webhooks
- Login to your Paddle Billing account
- Go to Developer Tools > Notifications
- Click New Destination
- Add any description you like
- Select Webhook as notification type
- Enter the following URL:
Select only the following webhook events:
transaction.paidtransaction.completedtransaction.updatedsubscription.created
Click Save Destination.
???? Webhook Secret (New in v3.0)
v3.0 includes webhook signature verification for better security.
After creating your webhook destination in Paddle, copy the Webhook Secret and place it in your Paddle Billing configuration inside WHMCS.
???? Automatic Webhook Log Deletion (New in v3.0)
To prevent unnecessary growth of webhook logs, v3.0 includes automatic cleanup support.
Use the following setting in gateway configuration:
- Delete Logs After X Days
Example:
- 30 → delete webhook logs older than 30 days
- 0 or empty → disable automatic deletion
???? Refunds & Credit Notes
v3.0 improves refund handling for both one-time and recurring transactions.
- Supports full refunds
- Supports partial refunds
- Uses live Paddle transaction data for better accuracy
- Supports one-time items, recurring items, and related tax lines
- Shows Paddle Credit Note PDF links in the WHMCS admin invoice page when available
???? Currency Conversion
v3.0 introduces smarter conversion handling for WHMCS and Paddle.
- Exchange rate snapshots are stored at checkout time
- Prevents mismatches if currency rates change later
- Improves reliability for callbacks, renewals, and refunds
- Works more safely with WHMCS Convert To settings
???? Special Guidelines for VND, JPY, and KRW
When using Paddle Billing with Vietnamese Dong (VND), Japanese Yen (JPY), and South Korean Won (KRW), please follow these rules:
No Decimal Pricing Allowed
These currencies do not support decimal values.
- ✅ Correct: ₫20,000 / ¥5,000 / ₩30,000
- ❌ Incorrect: ₫20,000.45 / ¥5,000.99 / ₩30,000.10
Avoid Automatic Decimal Conversion
Automatic conversion from USD may create decimal amounts. Do not rely on automatic stripping of decimals, as this may cause over or under billing.
Invoice Requirements
- Invoices must not include decimal values
- The final payable amount should always be a whole number
???? Upgrading from v2.8 to v3.0
If you are upgrading from v2.8, here are the important changes to review:
???? Security
v3.0 supports webhook signature verification. You should configure your Paddle webhook secret in WHMCS.
???? Conversion
v3.0 improves conversion handling and works properly with WHMCS Convert To for more reliable invoice, callback, and refund matching.
???? Refunds
Refund handling has been improved and now works with live Paddle transaction details and admin-side credit note access.
???? Logging & Admin Tools
v3.0 includes webhook event logging and optional automatic deletion of old webhook logs after a set number of days.
???? Sandbox Mode
If you want to test the gateway before going live:
- Enable Sandbox Mode in the Addon Module
- Enable Sandbox Mode in the Gateway Settings
When going live, make sure Sandbox Mode is disabled in both places.
???? Support & Updates
- Premium Support included
- Lifetime Updates included
- Latest improvements, bug fixes, and security optimizations included
- Installation and setup available for an additional charge
✅ Final Checklist
- Addon module activated
- Gateway activated
- License key added
- API key added
- Client-side token added
- Webhook destination created in Paddle
- Correct webhook events selected
- Webhook secret configured
- Delete log days configured if desired
- Sandbox mode configured correctly
- Test payment completed successfully
By following this guide, your Paddle Billing v3.0 integration will be installed, configured, and optimized for supported billing scenarios including subscriptions, one-time payments, refunds, and webhook security.
