Paddle Billing Gateway v2.x

Install and Configure Guide

In this article, we will learn how to install and configure the new Paddle Billing module.

About Module Package

This module consists of an addon and gateway module which will work together to do the following:

Clients are able to:

• Pay customised invoices
• Pay for billing items
• Pay for domains
• Pay/subscribe products
• Pay/subscribe addons
• Cancel their subscriptions

Admins are able to:

• Issue partial/full refunds

How to Install

1. Download the module from your iBeeHost account
2. Extract the downloaded zip file in WHMCS root directory

How to Activate Addon Module

You must activate the addon module first:

1. Go to System Settings > Addon Modules
2. Look for Paddle Billing > Activate
3. After activation, click Configure
4. Enter your License Key obtained from your iBeeHost account
5. Enter your API Key obtained from your Paddle account
6. If you are working in sandbox/testing mode, enable sandbox mode (no need to check this in live mode)
7. Click Save Changes

How to Activate Paddle Billing Gateway

For WHMCS Versions up to 7.10

1. Go to System Settings > Payment Gateways
2. Find Paddle Billing and click on it to activate

For WHMCS Version 8.0 and Above

1. Go to System Settings > Payment Gateways
2. Click Visit Apps and Integration
3. On the Apps & Integration page, search for Paddle Billing and click on it
4. A popup will appear with a button Activate – click it to activate the gateway

Configure Paddle Billing Gateway

1. Go to System Settings > Payment Gateways
2. Scroll down to Paddle Billing and click To Expand
3. Check Show on Order Form to make it visible for customers
4. Enter your iBeeHost License Key obtained from iBeeHost
5. Enter your Paddle API Key obtained from your Paddle account
6. Enter your Paddle Client-Side Token obtained from your Paddle account
7. If you are working in sandbox/testing mode, enable sandbox mode (no need to check this in live mode)
8. Choose your Checkout Theme based on your website’s outlook
9. In Convert to for Processing, select None (If available)
10. Click Save Changes

How to Setup Webhooks

1. Login to your Paddle Billing account
2. Navigate to Developer Tools > Notifications
3. On the notifications page, click on the New Destination button
4. Add description (it can be anything)
5. Choose Webhook as notification type
6. Enter the following URL in URL:

   https://<YOUR-WHMCS-URL>/modules/gateways/callback/paddleBilling.php

7. Check Select the following in Events
   1. transaction.completed
   2. transaction.updated
   3. subscription.created 
8. Click Save Destination

Special Guidelines for VND, JPY, and KRW

When using Paddle Billing with Vietnamese Dong (VND), Japanese Yen (JPY), and South Korean Won (KRW), the following rules must be followed:

1. No Decimal Pricing Allowed

   • These currencies do not support decimal values.

   • Example:

     • ✅ Correct: ₫20,000 / ¥5,000 / ₩30,000

     • ❌ Incorrect: ₫20,000.45 / ¥5,000.99 / ₩30,000.10

2. Avoid Automatic Decimal Conversion

   • Automatic conversion from USD may create decimal amounts.

   • Do not rely on automatic stripping of decimals, as it can cause over/under invoicing issues.

   • Always set whole-number prices directly for these currencies.

3. Invoice Requirements

   • Invoices must not include decimals (.xx).

   • Ensure the final payable amount is a whole number.

✅ By following this guide, your Paddle Billing integration will be installed, configured, and fully optimized for supported currencies, including VND, JPY, and KRW.