Latest revision as of 13:58, 26 April 2024

[edit] About Payment Gateway Charges For WHMCS

Payment Gateway Charges For WHMCS allows you to charge additional fees and set up discounts for the usage of a chosen payment gateway.

With this module you can easily set products, addons and TLDs that should require an additional fee, and select clients who will be exempt from fees and discounts.
On top of that, you will also be empowered to define multiple steps of charges as well as discounts which shall be taken depending on the invoice amount.
Finally, the module will enable you to lay down your own conditions for the application of charges and discounts involving client groups, countries and currencies.

Features:

✔ Display Charge Or Discount Rates Depending On Available Gateways

✔ Display Calculated Rates For Chosen Gateways

✔ Create Multiple Billing Rules For Gateways

✔ Copy Existing Rules Between Gateways

✔ Choose Calculation Method For Charge Or Discount Per Rule:

✔ Percentage

✔ Fixed Amount

✔ Toggle Charging After Tax Application

✔ Toggle Tax Application To Charge

✔ Toggle Charging After Promo Code Application

✔ Set Billing Calculation Methods:

✔ Standard

✔ Alternative (e.g. PayPal)

✔ PayPalV2

✔ Create Multiple Steps With Minimum Invoice Value To Apply Fees And Discounts

✔ Create Multiple Rule Activation Conditions For:

✔ All Clients

✔ Chosen Clients

✔ Chosen Client Groups

✔ Clients Or Groups With Specific Currencies

✔ Clients Or Groups With Specific Countries

✔ Perform Bulk Actions To Mark As Chargeable:

✔ Clients

✔ Products

✔ Addons

✔ TLDs (Register/Transfer/Renew)

✔ Other:

✔ Adding Funds To Credit Deposit

✔ Late Fee Invoice Items

✔ Custom Invoice Items

✔ Toggle Visibility Of Charge Rates In Client Area

✔ Define Charge Format Displayed On Invoice

✔ Define Div Tag For Custom Order Template Integration

✔ Toggle Redundant Logs Deletion After Defined Period

✔ Access Module Logs

Supported Order Form Templates:

✔ Cloud Slider

✔ Legacy Boxes

✔ Legacy Modern

✔ Premium Comparison

✔ Pure Comparison

✔ Standard Cart

✔ Supreme Comparison

✔ Universal Slider

✔ Other Custom Templates

General Info:

✔ Integrated With Lagom One Step Order Form For WHMCS - Apply Custom Discounts And Fees Based On Payment Gateway Chosen During Ordering

✔ Supports All Payment Gateways

✔ Supports Mass Payment Functionality

✔ Supports Prorata Billing

✔ Integrated With All Order Form Templates

✔ Multi-Language Support

✔ Supports PHP 8.1 Back To PHP 7.4

✔ Supports WHMCS Themes "Six", "Twenty-One" And "Lagom WHMCS Client Theme"

✔ Supports WHMCS V8.10 Back To WHMCS V8.6

✔ Requires ionCube Loader V12 Or Later

✔ Easy Module Upgrade To Open Source Version

[edit] Installation

This tutorial will show you how to successfully install and configure Payment Gateway Charges For WHMCS.

We will guide you step by step through the whole installation and configuration process.

Note: If you are using Payment Gateway Charges For WHMCS in any version prior to v2.x, read about it here.

1. Log in to our client area and download the module.

2. In the downloaded file you might find one or two packages that support different PHP versions.

In the most recent versions of the module, you will find only one package that supports PHP 7.2 and later.

Previous updates of the module may contain two packages dedicated to various PHP versions.

The first one that supports PHP 5.6 up to PHP 7.1, and the second one addressed to PHP 7.2 up to PHP 7.4.
Note: Keep in mind that PHP versions 5.6 up to 7.1 are no longer officially supported and their security issues are not fixed or released any more. Find more info here.

Note: You can check the current PHP version in your WHMCS. To do so, proceed to 'Utilities' → 'System' → 'PHP Info'.

3. Extract the package and upload its content into the main WHMCS directory.

The content of the package to upload should look like this.

4. When installing Payment Gateway Charges For WHMCS for the first time, you have to rename the 'license_RENAME.php' file.

The file is located in 'your_whmcs/modules/addons/PaymentGatewayCharges/license_RENAME.php'. Rename it from 'license_RENAME.php' to 'license.php'.

5. In order to configure your license key, you have to edit the previously renamed 'license.php' file.

Enter your license key between the quotation marks as presented on the following screen. You can find your license key in our client area → 'My Products'.

6. Now, set up the 'storage' folder as recursively writable.

This folder is available at 'your_whmcs/modules/addons/PaymentGatewayCharges/' .

7. Now you have to activate the module in your WHMCS system.

Log in to your WHMCS admin area. Go to 'Setup' → 'Addon Modules'. Afterwards, find 'Payment Gateway Charges' and press the 'Activate' button.

8. In the next step you need to permit access to this module.

To do so, click on the 'Configure' button, tick 'Full Administrator' and press 'Save Changes'.

9. Congratulations, you have just successfully installed Payment Gateway Charges For WHMCS!

You can now access your module from 'Addons' → 'Payment Gateway Charges'.

[edit] Configuration and Management

Payment Gateway Charges For WHMCS allows your customers to manage additional charges in your WHMCS system.

In this short guide we will present you the possibilities of our module.

[edit] Gateways Settings

Once you access the addon, you will be moved directly to its configuration. Here you can decide for which gateways the additional charges or discounts will be applied, according to their settings and rules.

Start by selecting 'Settings' .

Here you can define the following settings:

Status - toggle to enable or disable charges for a chosen payment gateway
Charge After Taxing - if enabled, the charge will be applied to an already taxed item
Apply Tax To Charge - enable to impose taxes on charges. Note: taxes will not be applied for discount rules
Charge After Applying Promo Code - enable to charge once the final price has been lowered by a promo code
Billing Type - choose between 'Standard' , 'Alternative (e.g. PayPal model)' or 'PayPalV2' - the differences are explained in the further part of documentation
Show In Charges Table - if enabled, the charges and discounts configured in the rules of this gateway will be displayed in the table at the checkout.

'Charge After Taxing' and 'Apply Tax To Charge' explanation:

Charge Type no.1

The 'Charge After Taxing' and 'Apply Tax To Charge' options are disabled.
With this method, the module calculates the additional fee only for the base price:
Base Price = 63£
PP charge (4,4% + 0.2£) = 2,97£
TAX 20% - 12,6 (Tax is only calculated for the base price, not for the charge because the option 'Apply Tax To Charge' is disabled).
Total = Base Price + Tax + Charge = 63£ + 12,6£ + 2,97£ = 78.57£

Charge Type no.2

The charge with enabled option 'Charge After Taxing' and disabled option 'Apply Tax To Charge' .
In this case, the module calculates charge after applying the tax to the base price. The tax is not counted for the charge.
Base Price = 63£
Tax 20 % = 12,6£
PP charge (4,4% + 0.2£) = 3,53£ ( The charge is calculated from the price 75,6£ (63£ + 12,6£))
Total = Base Price + Tax + Charge = 63£ + 12,6£ + 3,53£ = 79,13

Charge Type no.3

The 'Charge After Taxing' and 'Apply Tax To Charge' options are enabled.
Now the tax is enabled for the base price and for the charge, and the charge is calculated for the base price with the tax.
Base Price = 63£
Tax for Base Price 20 % = 12,6£
PP charge (4,4% + 0.2£) = 3,53£ (The charge is calculated from the price 75,6£ (63£ + 12,6£))
Tax for Charge 20 % = 0,71£
Full Tax = 12,6£ + 0,71£ = 13,31£
Total = Base Price + Full Tax + Charge = 63£ + 3,53£ + 13,31£ = 79,84£

Charge Type no.4

The charge with enabled option 'Apply Tax To Charge' and disabled option 'Charge After Taxing' .
In this case, the module applies the tax to the base price and to the charge. The charge is counted from the base price without the tax.
Base Price = 63£
PP charge (4,4% + 0.2£) = 2,97£
Tax for Base Price 20 % = 12,6£
Tax for Charge 20 % = 0,59£
FULL TAX 20% (Base Price + Charge) = 12,6£ + 0,59£ = 13.19£
Total = Base Price + Full Tax + Charge = 63£ + 2,97£ + 13,19£ = 79,16£

Billing types explanation:

Standard - when this type is selected, the total fee will be calculated in a standard manner, taking account of the full amount charged for the products in the cart.
Alternative (e.g. PayPal model) - when this method is selected, the fee will be calculated in such a way so that it matches e.g. the PayPal's method of charge calculation.
This method is based on the following calculation formula:
```
Final Amount = (Initial Amount / ( 1 - (Percentage / 100)) - Initial Amount) + Fixed Amount
```
PayPalV2 model - when this method is selected, the method will be based on the following calculation formula:
```
Final Amount = ( Initial Amount + Fixed Amount ) / ( 1 - ( Percent / 100 ))
```

Note: when one of these PayPal methods is selected, then this billing type will be applied to every activated payment gateway, not only PayPal.

Let's see how the 'Standard' and 'Alternative (e.g. PayPal model)' calculation methods differ in practice.

Please notice at the table below that the final price which a client is obliged to pay and the amount that will be sent e.g. to PayPal slightly vary between the two presented methods.
Note: the following example does not include a comparison with the 'PayPalV2' method which was introduced in the 3.0.1 version of the module.

E.g.:
Product Price: $124.00
Gateway Fee: 5%

Method	Base Fee	Total Amount With Charge
Standard	124 * 0.05 = $6.20	124 + 6,20 = $130.20
Alternative	(124/0.95) - 124 = $6.53	124 + 6,53 = $130.53

So, the total amount to be paid by the client would be $130.20 for the standard method and $130.53 for the alternative, PayPal method.

Now, let us see in reverse how these total fee amounts would look like if both were the result of calculations using an alternative method only.
This will help you better understand why it is advised to choose the alternative method for some payment gateways like PayPal.

Total Calculation Method	5% Fee From Total Amount With Charge
From Standard	130.20 * 0,05 = $6.51
From Alternative	130.53 * 0.05 = $6.53

So, if you are using PayPal and want to receive a full $124.00 amount for a product with a 5% gateway fee, a payment of $130.53 should be sent to PayPal gateway.
$6.53 will cover PayPal fees which is 5% of the total amount to be paid by the client.

In case of the $130.20 amount calculated using the standard method, the 5% PayPal fee would be $6.51, which, after deducting from the total, would result in $123.69 amount for the product itself.

Method	Amount With Charge	5% Fee	Amount Which Would Be Received
Standard	$130.20	$6.51	130.20 - 6.51 = $123.69
Alternative	$130.53	$6.53	130.53 - 6.53 = $124.00

[edit] Gateways Rules

This step is obligatory, the module will not work properly without correctly set up rules.

In the rules section, you can set a percentage or a fixed amount of billed charges or discounts.

To set the rules, first press 'Show Rules' located next to the chosen payment gateway.

Next, press the 'Add Rule' button.

Here you can name the rule and define a charge for the gateway in a percent form, fixed amount or both.

Important: At least one gateway condition must be added to the rule for it to work. You can find a description of adding conditions to rules here.
The following examples assume that gateway conditions have already been created.

The result of the above rule will be a 5% charge of the product price (which in this example is $100.00) with additional $1.00 charge for the selected 2Checkout payment gateway (using 'Standard' billing type method).

You can also set negative amounts. Then, a discount will be applied to a chosen gateway instead of charging an additional fee.

The result of the above rule will be a 5% discount of the product price (which in this example is $100.00) with additional $1.00 reduction for the selected 2Checkout payment gateway (using 'Standard' billing type method).

[edit] Steps Rules

You can also add additional steps to your rules and define above which minimum amount on the invoice the additional fee or set discount will be applied.

To start, press 'Show Steps' next to the created rule.

Now, you need to add your first step. Press the 'Add Step' button.

To create a rule, enter the percentage or fixed amount of the desired charge or discount.

Then, specify the minimum required amount that will trigger the rule.

You can create as many steps as you want. Each of these step rules will be activated only after the minimum invoice amount has been achieved.

Note that only one step rule can be active at a time. Also, if none of the step rules is met, then the main rule created in the previous section will be applied. In this example, it is the rule for orders below $50.00 amount.

[edit] Gateways Conditions

You can also specify multiple conditions that will affect activation of the rule.
Note that at least one condition has to be created to make the rule applicable.

Start by choosing the 'Show Conditions' button next to the selected rule.

There is one default condition that has been created when adding the first gateway. You may modify it, delete and create new conditions here.

Press the 'Add Condition' button to create a new condition within this gateway.

You can select one of several conditions that will determine the activation of the rule.

Choose between the following types:

User:
- Client - activate the rule only for a selected client
Group:
- Clients Group - activate the rule for selected client groups
- Currency - you can also specify which currency should be used by the selected group
- Country - optionally, choose from countries that the selected group of clients should come from
All - by choosing this condition, you will make the rule applicable to all of your customers. Optionally you can also add to this rule:
- Currency - the rule will be triggered for every client with the selected currency
- Country - apply the rule for every client from the selected country

Important: some conditions may be combined with one another to provide more possibilities for triggering the rule, but they should not overlap.

If you encounter a validation error when adding a condition, make sure that there are no conflicts with conditions configured under this or other rules.

Once you have ready rules and conditions prepared per gateway, you may either configure them per every existing gateway or simply copy all the settings to another gateway.
Press the marked button and then select from which gateway you want to copy the rules together with its steps and conditions.

Note: Keep in mind that if there were any rules in the gateway, all of them will be removed and overwritten by the new, copied settings.

[edit] Management of Items

To enable or disable gateway charges and discounts for products, addons or TLDs, go to the 'Items' section.
Then, select the category of items and simply toggle the 'chargeable' status next to the selected item.

Note: For convenience, all new and already existing items are set to 'chargeable' by default.

You can also toggle multiple 'chargeable' statuses at once by selecting items and using bulk action.

[edit] Other Options

Enable or disable gateway charges and discounts for selected options

Adding Funds To Credit Deposit - if set to chargeable, the charge will be calculated when adding funds to the client's credit deposit

Late Fee Invoice Items - if this option is set to chargeable, then the charge will be calculated for late fee items on the invoice as well

Custom Invoice Items - if this option is set to chargeable, the charge will be calculated for all added to a custom invoice items

Note: Again, all available options are set to 'chargeable' by default.

You can also toggle multiple 'chargeable' statuses at once by selecting items and using bulk action.

[edit] Management of Clients

To enable or disable gateway charges and discounts for your customers, go to the 'Clients' section.
Then, simply toggle the 'chargeable' status next to the selected client.

Note: For convenience, all new and already existing clients items are set to 'chargeable' by default.

You can also toggle multiple 'chargeable' statuses at once by selecting clients and using bulk action.

[edit] Settings

In this section you can customize the basics of the module's settings such as:

Show Charge - toggle to show charge on the order for a client. Click here to see the example.
Show Charges Table - if toggled on, the box with gateways details of additional payments on the order form will be visible for a client. Click here to see the example.
Charge Format - here you can define the format of the discount or charges displayed on the invoice. Click here to see the example.
You can use these variables to define it:
- :mainText: - by default displayed as 'Payment Gateway Charge' or 'Payment Gateway Discount' depending on the gateway rule configuration.
  You can change the displayed text in a language file by editing 'InvoiceItemTextCharge' and 'InvoiceItemTextDiscount' records.
- :gatewayName: - the name of the payment gateway to which a charge or discount was applied.
- :discount: - the calculated discount amount
- :price: - the calculated charge amount. Note: if applied, this amount will also include the tax.
- :priceWithoutTax: - the calculated charge amount without any tax applied
- :tax1: - calculated level 1 tax of the charge
- :tax2: - calculated level 2 tax of the charge
- :fullTax: - the sum of calculated level 1 and level 2 tax of the charge
- :percentage: - the percentage of billed charges or discounts
- :fixedAmount: - the fixed amount of billed charges or discounts
Select Template - choose the order templates you use to determine where the charges table is displayed.
If you are using custom template, please select 'Use Charges Table Tag' and set the field below.
Charges Table Tag - if you are using custom template, here you can determine where the charges table will be displayed.
In that case, define the custom tag element from your template, after which the charges table will appear, e. g. div#creditCardInputFields.
Note that the provided tag name should be unique in your template! Otherwise, the integration may be injected into uncontrolled positions. More information you can find here.
Disable Logs - if you disable logs, that are by default enabled, they will no longer be stored in the database.

[edit] Logs

In the logs section you can see which invoices have been calculated with additional discounts or charges resulting from the module's configuration.

Note that you can also delete multiple logs at once.

[edit] Custom Template Integration

To add an integration to your custom template, first you need to choose the place where you want the charges table to be placed.
It is recommended to position it under a unique tag, e.g.:

div#a_unique_element_in_which_the_table_will_be_located

Now, go to the module settings and select 'Use Charges Table Tag' from the 'Select Template' dropdown menu.
Next, put the name of your chosen tag in the 'Charges Table Tag' field, and save settings.

Next, you need to learn the name of your custom orderform template.
Note that you can find all orderforms templates in 'yourWHMCS/templates/orderforms/' location.

For this example we will assume that your custom oderform template is simply named as 'custom_template' .

Now, you need to edit the 'script.tpl' file located in the 'yourWHMCS/modules/addons/PaymentGatewayCharges/templates/client/default/pages/charge/assets/' .
Update the following lines with the name of your 'custom_template' oderform.

1. The code between lines 10-19 to update the charge values:

{/literal}{elseif $template eq 'custom_template'}{literal}
    $('div#where_the_charge_price_value_is_replaced').html(data.data.string);

2. The code between lines 42-75 provides you with a possibility to define table display:

{/literal}{elseif $template eq 'custom_template'}{literal}
    $('input[name=applycredit]').on('change', function(event){ // event to check if the 'Apply Credit' value has been changed
          mgLoadCharge();
    });
    $('input[name=paymentmethod]').on('change', function(event){ // event to check if the 'Payment Method' has been changed
          mgLoadCharge();
    });
    $('select[name=country]').on('change', function(event){ // event to check if the 'Country' value has been changed
          mgLoadCharge();
    });

After completing this procedure and applying the right code, you should have a working layout in your client area.

[edit] Tips

1. For your convenience, payment gateway charges are enabled by default for clients, products, addons and domains.

2. Taxes will not be applied to gateway discount rules even if 'Apply Tax To Charge' option is enabled.

3. You can easily change all names of module elements displayed in the client area, admin area or invoices in a language file.

To do so, go to the 'your_whmcs/modules/addons/PaymentGatewayCharges/langs' directory, open the language file (e.g. english.php) and edit desired records.

4. In case there is more than one rule that matches a single client, the one with the most precise conditions, concerning that client, will be taken into account when calculating the final discount.

5. If you have installed the Lagom WHMCS theme, use the following 'Charges Table Tag' for the custom template integration:

div#paymentGatewaysDetails

6. If you are an experienced administrator, you may take advantage of an extra (hidden) tab 'Debug Logs'. See details of performed calculations with information on used conditions and the 'before' and 'after' prices.

In order to enter the debug logs section, you need to manually add to 'your_whmcs/your_admin_path/' URL:

addonmodules.php?module=PaymentGatewayCharges&mg-page=DebugLogs

7. Note that you may always change the default translations to more friendly names. Just open the english.php file, find lines:

 $_LANG['InvoiceItemTextCharge'] = 'Payment Gateway Charge';
 $_LANG['addonCA']['charge']['chargeCheckout'] = 'Gateway Charge';
 $_LANG['addonCA']['charge']['discountCheckout'] = 'Gateway Discount';
 $_LANG['addonCA']['charge']['paymentGatewayCharges'] = 'Payment Gateway Charges';

and change the content here: ='your_friendly_name' in any of the above if you only wish.
See below how a custom naming may present:

[edit] How To Use Language Overrides

Incorporating language customizations - the module readily accommodates language overrides, allowing you to tailor the language files to your preferences.
The language file english.php remains unencoded and can be modified to suit your needs. However, it's recommended to avoid altering the core file itself, and instead, leverage the capability of using overrides.

Here's how to apply language overrides:

Navigate to the ~/langs/ directory located within the following yourWHMCS/modules/servers/moduleName/langs/ path.
Within this directory, create a new file or duplicate the language file you intend to modify. For instance, if you wish to create an override for the English language, establish the following directory structure:

 ~/langs/overrides/english.php.

Open the newly created override file to edit its contents.
At the beginning of the file, indicate the used code, for instance, you can use: <?php for PHP code.
Adapt the file content according to your requirements. You can either selectively modify specific variables or opt to revise the entire content of the language file.

For example:

Original yourWHMCS/modules/servers/moduleName/langs/english.php:

 $_LANG['Search'] = 'Search';

Override yourWHMCS/modules/servers/moduleName/langs/overrides/english.php:

 $_LANG['Search'] = 'Look for';

By following these steps, you can seamlessly implement language customizations without altering the core language file, ensuring your changes will not be lost after every module update.

Remember that some of the modules have more than one language file, located under /addons and /servers paths. You may create the override files for both of them.
Note that you do not need to paste all the original content of the lang file into the override file. Enter there only the lines that you wish to change, every other line will be fetched from the original module lang file.
Consequently, the override lang file might include only one or just a few lines.

[edit] Update Instructions

An essential guidance through the process of updating the module is offered here.

Ensure successful completion of the module update by carefully following each step, thereby preventing data loss or any unforeseen issues.
Additionally, you will find a current list of supplementary actions necessary for a smooth update process there.

[edit] Migration

Note that while using the 1.X version of our module, no data can be migrated. This is due to the fact that we did not implement the migration from any of the previous versions of Payment Gateway Charges, so the module needs to be configured from scratch.

Note: Remember that if you wish to switch to the latest version, you need to reissue your license first.

[edit] Upgrade Guide

Seeking a solution that offers greater flexibility, customization tailored to your precise needs, and unrestricted availability?
There is an option that not only proves to be cost-effective in the long run but also includes prioritized support services, making it a truly valuable investment.

Opt for the Open Source version of your Payment Gateway Charges For WHMCS module to unlock these benefits.
Simply click on either the Get Source Code or Upgrade To Lifetime button found on the product's page in our client area to complete the one-step upgrade process, with a dedicated discount already applied.

Follow a comprehensive guide covering the transition process, the advantages it brings, and step-by-step instructions on what to do next after the order has been successfully finalized.

[edit] Common Problems

1. When you have problems with connection, check whether your SELinux or firewall does not block ports.

2. In the current version, if a promotional code is used by the client, the amount of charge will not be changed as it will continue to be calculated from the basing item price.
The ability to recalculate the charge after using a promo code will be restored in future versions.

3. In case none of your payment gateways is visible on the list, make sure that collations in the database are correctly configured.
For more information on collations please refer to the WHMCS official documentation, point: 'Database Collations'.

4. We do not recommend using Payment Gateway Charges For WHMCS with the Resellers Center For WHMCS module due to the fact that both of these modules manipulate the invoices, which are the source of serious conflicts.

5. PayPal Payments Limitations

Take a look to learn about any predicted discrepancies connected with PayPal payments for recurring subscriptions and the limited functionality cases:

Tax Support feature - this option ('WHMCS Admin Area' → 'System Settings' → 'Tax Configuration' → 'General Settings') must be ALWAYS ON, otherwise the PayPal subscriptions will be calculated incorrectly.
Charge After Applying Prmo Code - no matter if the option is enabled or disabled ('Payment Gateway Charges' → 'Gateways' → 'Settings'), the module will behave as if it was turned on for recurring payments.
Other inconsistencies might occur due to the fact that the module must rebuild invoices and calculate the charge for the first payment when the gateway is changed. In the case of PayPal recurring payments, a new charge is calculated the moment the button confirming the payment is pressed.
Therefore, there will be discrepancies when you change the settings in the module but do not change the payment gateway to allow the invoice to be rebuilt (for example PayPal → Bank Transfer → PayPal).
Possible scenarios:
- Charge After Taxing: OFF, Apply Tax To Charge: OFF - no discrepancies detected
- Charge After Taxing: ON, Apply Tax To Charge: OFF - discrepancies may appear
- Charge After Taxing: ON, Apply Tax To Charge: ON - discrepancies may appear
- Charge After Taxing: OFF, Apply Tax To Charge: ON - discrepancies may appear

Important: It is advised to change the default payment gateway from PayPal to any other available one, then the invoices will be rebuilt correctly for recurring payments.

Personal tools

Namespaces

Variants

Views

Actions

Search

Payment Gateway Charges For WHMCS