WHMCS Documentation - User contributions [en]

Migration Guide

2024-05-24T07:31:35Z

John: /* ImportAssist */

We understand that the majority of companies already have a billing system in place to manage their hosting clients and worry about the difficulties of switching to a new billing system. With that in mind, we provide the following guides and automation scripts in order to make importing easy.

<html><a href="https://www.whmcs.com/services#installation?utm_medium=docs" class="docs-video-tutorial"><em><small><b>Migration Services:</b> Contact our team to discuss our migration services.</small></em><span class="button">Services</span></a></html>

==ImportAssist==

[[File:import_assist_banner_2.png|link=https://marketplace.whmcs.com/product/46]]

When performing a migration from another billing system or WHMCS installation, we recommend using our ImportAssist addon, which supports importing data from multiple billing systems. At this time, this supports the following systems:

* WHMCS Version 6.2.x, 6.3.x, 7.0.x, 7.1.x, 7.2.x, 7.3.x, 7.4.x, 7.5.x, 7.6.x, 7.7.x
* Blesta Version 2.x, 3.x, 4.1, 5.x
* ClientExec Version 5.3+
* HostBill 2016 Version

For detailed information on obtaining and using ImportAssist, see [[ImportAssist]].

==Server Sync Tool==

In WHMCS 7.8 and later, you can compare and sync details from cPanel, Plesk and DirectAdmin servers using the '''[[Server Sync Tool]]''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.

This is particularly useful for performing an initial import when first starting with WHMCS, but you can also use it for other purposes, such as identifying and importing missing domains, syncing usernames and package information, and terminating inactive domains.

==cPanel & WHM Import Script==

In WHMCS 7.7 or older, you can import all of the domains on your existing cPanel & WHM servers using the tools at '''Utilities > [[CPanel/WHM_Import|WHM Import Tool]]'''.

==Manual Entry==

We understand that the ImportAssist addon and Server Sync Tool may not always meet your needs for adding clients and their items (for example, when you need to add a client manually and there is no associated hosting account or domain registrar for their items). In these circumstances, it is possible to add clients and their items manually via the admin area using the instructions below.

===Adding Clients===

To manually import your clients, use the following steps for each client:

#Go to '''Clients > Add New Client'''.
#Fill out the client details. You must provide, at least, the first and last names, email address, and password.
#Optionally, deselect the checkbox to send a '''New Account Information Message'''.
#Click '''Add Client'''.

You have now finished adding your client. However, the system will not automatically notify your client that you added them. You can now add the applicable items to their account in the section below.

===Adding Services===

Once you have added the clients, you can proceed to add their services (such as hosting accounts). Perform the following steps for each client:

# In the '''[[Clients:Summary Tab|Summary]]''' tab in the client profile, click '''Add New Order'''. The system will preselect the client.
# Fill out the rest of the form, beginning with choosing the payment gateway you want their future invoices to use.
# Choose the applicable product or service and the billing cycle.
# If the service has an associated domain name, enter it in the textbox.
# If you also control the domain name registration, select ''Register'' on the domain section below and choose any addons the user has for their domain.
# Deselect the boxes for '''Order Confirmation''' and '''Generate Invoice'''. This will ensure that the system doesn't email the client about the order you are adding.
# Select '''Active''' from the '''Order Status''' menu.
# Click '''Submit'''.

The system will display the order details page, which will summarise the details of the order you added.

As the final step, go into the service details and set the correct next due date. To do this from the order details page, click on the link in the '''Item''' column of the items ordered. This will take you to the service details page. From there, you can edit the next due payment date. For hosting accounts, select the correct server and enter the username for the account to allow WHMCS to perform suspensions and terminations.

===Adding Domains===

To add a domain without a product:

# In the '''[[Clients:Summary Tab|Summary]]''' tab in the client profile, click the '''Add New Order''' link in the '''Actions''' panel. The system will preselect the client.
# Fill out the rest of the form, beginning with choosing the payment gateway for future invoices to use by default.
# Select '''Active''' from the '''Order Status''' menu.
# Deselect the checkboxes for sending an order confirmation and generating an invoice. This will ensure that the client is not emailed about the order you are adding and no invoice is raised.
# Select '''Registration''' for the domain registration type. The domain fields will then be shown.
# Enter the domain in the '''Domain''' field.
# Choose the number of years you want to invoice the client for at the time of renewal.
# Select any addons that the user has for their domain such as DNS Management.
# Click '''Submit''' to add the order to WHMCS. The system will display the order details page, which will summarise the details of the order you added.
# Click '''Domain''' in the '''Item''' column to check whether the next due date, expiry date, and registrar settings are correct. Make any necessary updates and then click '''Save Changes'''.

Migration Guide

2024-05-24T07:31:12Z

John: /* ImportAssist */

We understand that the majority of companies already have a billing system in place to manage their hosting clients and worry about the difficulties of switching to a new billing system. With that in mind, we provide the following guides and automation scripts in order to make importing easy.

<html><a href="https://www.whmcs.com/services#installation?utm_medium=docs" class="docs-video-tutorial"><em><small><b>Migration Services:</b> Contact our team to discuss our migration services.</small></em><span class="button">Services</span></a></html>

==ImportAssist==

[[File:import_assist_banner_2.png|link=https://marketplace.whmcs.com/product/46]]

When performing a migration from another billing system or WHMCS installation, we recommend using our ImportAssist addon, which supports importing data from multiple billing systems. At this time, this supports the following systems:

* WHMCS Version 6.2.x, 6.3.x, 7.0.x, 7.1.x, 7.2.x, 7.3.x, 7.4.x, 7.5.x, 7.6.x, 7.7.x
* Blesta Version 2.x, 3.x, 5.x
* ClientExec Version 5.3+
* HostBill 2016 Version

For detailed information on obtaining and using ImportAssist, see [[ImportAssist]].

==Server Sync Tool==

In WHMCS 7.8 and later, you can compare and sync details from cPanel, Plesk and DirectAdmin servers using the '''[[Server Sync Tool]]''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.

This is particularly useful for performing an initial import when first starting with WHMCS, but you can also use it for other purposes, such as identifying and importing missing domains, syncing usernames and package information, and terminating inactive domains.

==cPanel & WHM Import Script==

In WHMCS 7.7 or older, you can import all of the domains on your existing cPanel & WHM servers using the tools at '''Utilities > [[CPanel/WHM_Import|WHM Import Tool]]'''.

==Manual Entry==

We understand that the ImportAssist addon and Server Sync Tool may not always meet your needs for adding clients and their items (for example, when you need to add a client manually and there is no associated hosting account or domain registrar for their items). In these circumstances, it is possible to add clients and their items manually via the admin area using the instructions below.

===Adding Clients===

To manually import your clients, use the following steps for each client:

#Go to '''Clients > Add New Client'''.
#Fill out the client details. You must provide, at least, the first and last names, email address, and password.
#Optionally, deselect the checkbox to send a '''New Account Information Message'''.
#Click '''Add Client'''.

You have now finished adding your client. However, the system will not automatically notify your client that you added them. You can now add the applicable items to their account in the section below.

===Adding Services===

Once you have added the clients, you can proceed to add their services (such as hosting accounts). Perform the following steps for each client:

# In the '''[[Clients:Summary Tab|Summary]]''' tab in the client profile, click '''Add New Order'''. The system will preselect the client.
# Fill out the rest of the form, beginning with choosing the payment gateway you want their future invoices to use.
# Choose the applicable product or service and the billing cycle.
# If the service has an associated domain name, enter it in the textbox.
# If you also control the domain name registration, select ''Register'' on the domain section below and choose any addons the user has for their domain.
# Deselect the boxes for '''Order Confirmation''' and '''Generate Invoice'''. This will ensure that the system doesn't email the client about the order you are adding.
# Select '''Active''' from the '''Order Status''' menu.
# Click '''Submit'''.

The system will display the order details page, which will summarise the details of the order you added.

As the final step, go into the service details and set the correct next due date. To do this from the order details page, click on the link in the '''Item''' column of the items ordered. This will take you to the service details page. From there, you can edit the next due payment date. For hosting accounts, select the correct server and enter the username for the account to allow WHMCS to perform suspensions and terminations.

===Adding Domains===

To add a domain without a product:

# In the '''[[Clients:Summary Tab|Summary]]''' tab in the client profile, click the '''Add New Order''' link in the '''Actions''' panel. The system will preselect the client.
# Fill out the rest of the form, beginning with choosing the payment gateway for future invoices to use by default.
# Select '''Active''' from the '''Order Status''' menu.
# Deselect the checkboxes for sending an order confirmation and generating an invoice. This will ensure that the client is not emailed about the order you are adding and no invoice is raised.
# Select '''Registration''' for the domain registration type. The domain fields will then be shown.
# Enter the domain in the '''Domain''' field.
# Choose the number of years you want to invoice the client for at the time of renewal.
# Select any addons that the user has for their domain such as DNS Management.
# Click '''Submit''' to add the order to WHMCS. The system will display the order details page, which will summarise the details of the order you added.
# Click '''Domain''' in the '''Item''' column to check whether the next due date, expiry date, and registrar settings are correct. Make any necessary updates and then click '''Save Changes'''.

Version 8.9 Release Notes

2024-03-14T15:03:28Z

John: /* Duo® Universal Prompt */

<div class="docs-alert-info" style="max-width:370px;">
<span class="title">Release Information</span>
<br />
Version: 8.9.0<br />
Release Type: General Availability<br />
Latest Update: 6th March 2024<br />
Distribution Types: Full and Via Automatic Updater
</div>

<div class="docs-alert-success">
For more information on WHMCS 8.9's important changes and exciting features, see [[New and Improved in WHMCS 8.9]].
</div>

==Version History==

<onlyinclude>
<table class="table table-striped">
<tr><td>8.9.0</td><td>Beta</td><td>6th December 2023</td></tr>
<tr><td>8.9.0</td><td>Release Candidate</td><td>7th February 2024</td></tr>
<tr><td>8.9.0</td><td>General Availability</td><td>6th March 2024</td></tr>
</table>
</onlyinclude>

==Download==

Download the latest version of WHMCS from https://download.whmcs.com/

==Upgrade Process==

WHMCS 8.0 and above requires PHP 7.2 or later. WHMCS 8.0 introduced support for PHP 7.4, and WHMCS 8.6 introduced support for PHP 8.1.

<div class="docs-alert-warning">
Make certain that you update to a WHMCS version that supports your desired PHP version or higher '''before''' updating PHP.
* The [[Automatic Updater]] only displays updates if you are running a PHP version that is compatible with that WHMCS version.
* For example, if you are running PHP 7.1 or earlier, you must update to PHP 7.2 or later before updating to WHMCS 8.0 or higher.
</div>

[[Upgrading|Upgrade Instructions]]

===Automatic Updating===

If you are running WHMCS 7.0 or later, you can use the built-in [[Automatic Updater]].

Go to '''Utilities > Update WHMCS''' to begin the process.

<div class="docs-alert-info">
If the update was released recently, you may need to click '''Check for Updates''' before the update will be available.
</div>

== Release Notes ==

=== New PayPal® Payment Gateways ===

The new '''PayPal Payments''' payment gateway module allows merchants to process and store payment methods using PayPal's latest secure tokenization system, including the advanced security of merchant-level vaulting with PayPal Vault for supported merchants.

<div class="docs-alert-info">
Currently, PayPal supports vaulting for merchants in:
* The United States
* Canada
* The United Kingdom
* Australia
* The following EU countries: Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia.
</div>

When you use '''PayPal Payments''', clients can make one-click payments using PayPal during checkout and on invoices.

When you activate '''PayPal Payments''', it also activates the '''[[PayPal Card Payments]]''' module. This module augments '''PayPal Payments''', allowing you to display a separate unbranded option to accept credit and debit cards during checkout. Both modules use the '''PayPal Payments''' configured PayPal account information for a seamless experience.

You can enable the new '''PayPal Payments''' module at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''. For more information, see [https://help.whmcs.com/m/payments/l/1782848-start-using-paypal-payments Start Using PayPal Payments].

<div class="docs-alert-warning">If you enabled these modules while using the Beta release of WHMCS 8.9, you '''must''' reactivate them before using them with WHMCS 8.9 Release Candidate or later. If you do not do this, you may experience problems with some payment methods.</div>

[[PayPal|Learn More]]

=== Transactions List ===

We have updated the displayed transaction details at '''Billing > [[Transactions|Transactions List]]''' to include additional information and currency codes for some amounts.

=== On-Demand Renewals ===

On-Demand Renewals now allow early renewals for product addons. When you enable on-demand renewals, clients can renew services in the Client Area before WHMCS generates their next invoice, with no manual action from your staff.

* You can configure on-demand renewals globally in the '''[[Ordering_Tab|Ordering]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings'''.
* You can configure on-demand renewals for individual product addons in the '''Pricing''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Product Addons]]'''.

[[On-Demand Renewals|Learn More]]

==== On-Demand Renewal Product Settings ====

We have moved the product-specific '''On-Demand Renewals''' settings at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' from the '''Other''' tab to the '''Pricing''' tab.

[https://help.whmcs.com/m/payments/l/1706772-configuring-on-demand-renewals Learn More]

=== Separated Invoice Viewing and Management ===

Invoices in the WHMCS Admin Area now default to a view-only mode. This prevents accidental editing while viewing an invoice and gives admins more fine-grained control over staff permissions.

* This change affects invoices at '''Billing > [[Invoices]]''' and in a client's profile's '''[[Clients:Invoices_Tab|Invoices]]''' tab.
* Admins can still add payments, resend emails, and perform certain other tasks in view-only mode if they have the related permissions for those tasks.

A new ''View Invoice'' permission at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]''' grants admins the ability to view, but not alter, existing invoices. Admins who already had the ''Manage Invoices'' permission will continue to be able to edit invoices by clicking '''Manage Invoice''' while viewing an invoice.

[[Invoices|Learn More]]

=== Duo® Universal Prompt ===

We have updated our integration with Duo Security to use the new [https://guide.duo.com/universal-prompt|Universal Prompt] login process. This change replaces the previous iframe-based experience and implements a simplified interface that continues to support Duo's wide range of Two-Factor Authentication options.

<div class="docs-alert-info">
Duo has announced that support for the previous iframe-based Duo Prompt will [https://duo.com/docs/universal-prompt-update-guide end on March 30, 2024].

* Duo's support teams will no longer be able to troubleshoot issues with the previous Duo Prompt after this date.
* After you upgrade to WHMCS 8.9 or later, we '''strongly''' recommend activating [https://guide.duo.com/universal-prompt Duo Universal Prompt] in your Duo customer portal to ensure continued functionality. If you do not do this, your customers may experience problems.
</div>

[[Duo Security|Learn More]]

=== Show on Order Form State ===

Payment gateway modules now support a <tt>VisibleDefault</tt> metadata parameter that defines the default '''Show on Order Form''' setting. This parameter defaults to <tt>true</tt> for all payment gateway modules.

[https://developers.whmcs.com/payment-gateways/meta-data-params/ Learn More]

=== Improved Invoice ID Incrementation ===

To improve how WHMCS handles incrementing invoice ID numbers, we have updated the following settings in the '''[[Invoice_Tab|Invoices]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''':

* '''Invoice # Incrementation''' now has a maximum value of <tt>999</tt>.
* '''Invoice Starting #''' now has a maximum value of <tt>499,999,999</tt>.
* The maximum invoice ID number that the system can generate has increased from <tt>2,147,483,647</tt> to <tt>4,294,967,295</tt>.

=== Improved Apps & Integrations Experience ===

We have optimized page performance at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps_and_Integrations|Apps & Integrations]]''', allowing you to search for modules faster.

=== Stripe™ Module API Updates ===

We have updated the [[Stripe]], [[Stripe ACH]], and [[Stripe SEPA]] modules. We have updated the Stripe PHP Library and implemented other module improvements.

Additionally, '''Stripe ACH''' and '''Stripe SEPA''' now use Stripe's <tt>PaymentIntents</tt> API instead of the now-deprecated Stripe API. Patches will be available soon for installations that run WHMCS 8.5, 8.6, 8.7, or 8.8.

[[Stripe|Learn More]]

=== Enhanced Domain Pricing Validation ===

The system now validates your PHP configuration's <tt>max_input_vars</tt> setting before saving changes at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]'''. This helps to prevent MySQL® errors and other issues that low <tt>max_input_vars</tt> values may cause.

[https://go.whmcs.com/1809/PHP-max-input-vars-Setting-Errors Learn More]

=== Blesta 5 Support in ImportAssist ===

The [[ImportAssist]] addon module now supports importing data from Blesta 5. This is a direct change to the '''ImportAssist''' module and is not specific to WHMCS 8.9.

[[ImportAssist|Learn More]]

== Deprecation and Removal Notices ==

=== Plaid Settings in Stripe ACH Module ===

We have removed support for Plaid from the [[Stripe ACH]] payment gateway module. This includes removing the '''Plaid Client Id''', '''Plaid Secret''', and '''Plaid Environment''' settings from the module's configuration.

== Templates ==

For a list of changed files and a graphical view of the exact changes, see the GitHub™ repositories below.

===Twenty-One Theme===

The following link provides a comparison of changes between 8.8.0 and 8.9.0:

https://github.com/WHMCS/templates-twenty-one/compare/v8.8.0-release.1...v8.9.0-release.1

=== Six Theme ===

The following link provides a comparison of changes between 8.8.0 and 8.9.0:

https://github.com/WHMCS/templates-six/compare/v8.8.0-release.1...v8.9.0-release.1

=== Standard Cart Order Form ===

The following link provides a comparison of changes between 8.8.0 and 8.9.0:

https://github.com/WHMCS/orderforms-standard_cart/compare/v8.8.0-release.1...v8.9.0-release.1

== Changelog ==

* [[Changelog:WHMCS_V8.9.0_Beta_1|Version 8.9.0 Beta 1]]
* [[Changelog:WHMCS_V8.9.0_RC_1|Version 8.9.0 RC 1]]
* [[Changelog:WHMCS_V8.9.0_GA|Version 8.9.0 GA 1]]

DuoSecurity

2024-03-14T15:02:35Z

John: Updated Alert box

[http://docs.whmcs.com/Two-Factor_Authentication < Back to Two-Factor Authentication]

Duo® Security increases security with [[Two Factor Authentication]] (2FA). 2FA using Duo Security combines traditional account credentials (like a username and password) with a code or other verification from a device like a smart phone. Requiring both to log in decreases the threat of a leaked password.

Use of Duo Security is free for up to 10 accounts, and the Duo® Mobile app is available on all major smartphone platforms.

<div class="docs-alert-info">
In WHMCS 8.9 and later, our Duo Security integration uses [https://guide.duo.com/universal-prompt Duo Universal Prompt], which uses Duo Push by default. This pushes login or transaction details to your phone, allowing for immediate one-tap approval. If you already used Duo Security with the previous integration, you '''must''' log in to the Duo portal and upgrade your API credentials to use Duo Universal Prompt.

* Duo has announced that support for the previous iframe-based Duo Prompt will [https://duo.com/docs/universal-prompt-update-guide end on March 30, 2024]. Duo's support teams will no longer be able to troubleshoot issues with the previous Duo Prompt after this date.
* After you upgrade to WHMCS 8.9 or later, we '''strongly''' recommend activating [https://guide.duo.com/universal-prompt Duo Universal Prompt] in your Duo customer portal to ensure continued functionality. If you do not do this, your customers may experience problems.
* You will require a Duo Security account with an account level of '''Duo MFA''' or higher in order to access the Duo API. [https://go.whmcs.com/918/duo-security-signup Click here to sign up].
</div>

== Configuring Duo Security ==

Before you can configure Duo Security globally in WHMCS, you must perform additional steps to retrieve your Duo credentials.

To configure Duo Security in WHMCS:

# Log in to [https://admin.duosecurity.com/ your Duo Security account].
# Click '''Applications''' in the left sidebar.
# Click '''Protect an Application'''.
#* For WHMCS 8.9 and later, under '''Web SDK''', click '''Protect this Application'''.
#* For WHMCS 8.8 and earlier, under '''Auth API''', click '''Protect this Application'''.<div class="docs-alert-info">If you don't see this option, contact Duo support.</div>
# Retrieve the following values: [[File:duo-configuration.png|thumb|Duo Universal Prompt credentials (WHMCS 8.9 and later)]]
#* For WHMCS 8.9 and later, retrieve the '''Client ID''', '''Client Secret''', and '''API hostname''' values.
#* For WHMCS 8.8 and earlier, retrieve the '''Integration Key''', '''Secret Key''', and '''API hostname''' values.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Two Factor Authentication]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Two-Factor Authentication'''.
# Click '''Activate''' for '''Duo Security'''.
# To enable Duo Security as a two-factor option for staff, check '''Enable for Staff'''.
# To enable Duo Security for customers, check '''Enable for Clients'''.
# Enter the credentials and hostname that you retrieved from your Duo Security account.
# Click '''Save Changes'''.

== Enabling Duo Security as an Admin User ==

To enable Duo Security for an admin:

# Perform the steps above to configure Duo Security.
# Navigate to the '''My Account''' page within the WHMCS Admin Area.
# Click '''Enable Two-Factor Authentication'''.
# Follow the instructions to complete the setup process.

== Enabling Duo Security as a Client ==

To enable Duo Security as a client:

# Log in to the WHMCS Client Area.
# Go to '''Account > My Account > Security Settings''' or, prior to WHMCS 8.0, '''My Account > Security Settings'''.
# Click '''Enable Two-Factor Authentication'''.
# Follow the instructions to complete the setup process.

On all future login attempts, the client will be asked to complete the Two-Factor Authentication process.

==Using Existing Duo Accounts With WHMCS==

The WHMCS Duo integration uses the following format for admins that it transmits to Duo:

<div class="source-cli">
adminemailaddress:adminemailaddress:whmcslicensekey
</div>

You can use existing Duo accounts or users to complete two-factor authentication into the Admin Area. To do this, use the alias function in Duo to create an alias for the admin. For more information, see Duo's [https://help.duo.com/s/article/aliases-guide?language=en_US Aliases Guide ] documentation.

== Reactivating a user ==

When a user replaces or loses a two-factor device, they will need to reauthenticate DuoSecurity in order to enable the prompt. To achieve this, an admin will need to delete and restore the users from within the Duo dashboard.

For more information, see [https://duo.com/docs/administration-users#activating-duo-mobile Duo's documentation].

== Troubleshooting ==

=== The second factor you supplied was incorrect. Please try again ===

Seeing this error when activating the DuoSecurity method for the first time indicates that the code does not match what DuoSecurity expects. This is caused by the time on your server not matching DuoSecurity's clocks.

You can see the time in the top-right corner of your WHMCS Admin Area. WHMCS retrieves this directly from your server's PHP configuration and you must ensure that the server time is synced exactly with UTC. For example, if the server time is 00:01 and the time at DuoSecurity is 00:00, you will see this error. Syncing the server with [http://en.wikipedia.org/wiki/Network_Time_Protocol NTP] to verify the time will resolve this.

Different timezones are taken into account, ensuring that these differences won't cause a problem.

=== Invalid Integration ===
An Invalid Integration error is displayed on the Duo authentication screen when the keys/hostname used in Duo module configuration are incorrect. Please reconfigure the module settings by [[#Configuring_Duo_Security|following the steps above]].

DuoSecurity

2024-03-13T22:17:15Z

John: /* Configuring Duo Security */

[http://docs.whmcs.com/Two-Factor_Authentication < Back to Two-Factor Authentication]

Duo® Security increases security with [[Two Factor Authentication]] (2FA). 2FA using Duo Security combines traditional account credentials (like a username and password) with a code or other verification from a device like a smart phone. Requiring both to log in decreases the threat of a leaked password.

Use of Duo Security is free for up to 10 accounts, and the Duo® Mobile app is available on all major smartphone platforms.

<div class="docs-alert-info">
In WHMCS 8.9 and later, our Duo Security integration uses [https://guide.duo.com/universal-prompt Duo Universal Prompt], which uses Duo Push by default. This pushes login or transaction details to your phone, allowing for immediate one-tap approval. If you already used Duo Security with the previous integration, you '''must''' log in to the Duo portal and upgrade your API credentials to use Duo Universal Prompt.

* Duo has announced that support for the previous iframe-based Duo Prompt will [https://duo.com/docs/universal-prompt-update-guide end on March 30, 2024]. Duo Security will '''not''' function in WHMCS 8.8 and earlier after this date.
* After you upgrade to WHMCS 8.9 or later, we '''strongly''' recommend activating [https://guide.duo.com/universal-prompt Duo Universal Prompt] in your Duo customer portal to ensure continued functionality. If you do not do this, your customers may experience problems.
* You will require a Duo Security account with an account level of '''Duo MFA''' or higher in order to access the Duo API. [https://go.whmcs.com/918/duo-security-signup Click here to sign up].
</div>

== Configuring Duo Security ==

Before you can configure Duo Security globally in WHMCS, you must perform additional steps to retrieve your Duo credentials.

To configure Duo Security in WHMCS:

# Log in to [https://admin.duosecurity.com/ your Duo Security account].
# Click '''Applications''' in the left sidebar.
# Click '''Protect an Application'''.
#* For WHMCS 8.9 and later, under '''Web SDK''', click '''Protect this Application'''.
#* For WHMCS 8.8 and earlier, under '''Auth API''', click '''Protect this Application'''.<div class="docs-alert-info">If you don't see this option, contact Duo support.</div>
# Retrieve the following values: [[File:duo-configuration.png|thumb|Duo Universal Prompt credentials (WHMCS 8.9 and later)]]
#* For WHMCS 8.9 and later, retrieve the '''Client ID''', '''Client Secret''', and '''API hostname''' values.
#* For WHMCS 8.8 and earlier, retrieve the '''Integration Key''', '''Secret Key''', and '''API hostname''' values.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Two Factor Authentication]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Two-Factor Authentication'''.
# Click '''Activate''' for '''Duo Security'''.
# To enable Duo Security as a two-factor option for staff, check '''Enable for Staff'''.
# To enable Duo Security for customers, check '''Enable for Clients'''.
# Enter the credentials and hostname that you retrieved from your Duo Security account.
# Click '''Save Changes'''.

== Enabling Duo Security as an Admin User ==

To enable Duo Security for an admin:

# Perform the steps above to configure Duo Security.
# Navigate to the '''My Account''' page within the WHMCS Admin Area.
# Click '''Enable Two-Factor Authentication'''.
# Follow the instructions to complete the setup process.

== Enabling Duo Security as a Client ==

To enable Duo Security as a client:

# Log in to the WHMCS Client Area.
# Go to '''Account > My Account > Security Settings''' or, prior to WHMCS 8.0, '''My Account > Security Settings'''.
# Click '''Enable Two-Factor Authentication'''.
# Follow the instructions to complete the setup process.

On all future login attempts, the client will be asked to complete the Two-Factor Authentication process.

==Using Existing Duo Accounts With WHMCS==

The WHMCS Duo integration uses the following format for admins that it transmits to Duo:

<div class="source-cli">
adminemailaddress:adminemailaddress:whmcslicensekey
</div>

You can use existing Duo accounts or users to complete two-factor authentication into the Admin Area. To do this, use the alias function in Duo to create an alias for the admin. For more information, see Duo's [https://help.duo.com/s/article/aliases-guide?language=en_US Aliases Guide ] documentation.

== Reactivating a user ==

When a user replaces or loses a two-factor device, they will need to reauthenticate DuoSecurity in order to enable the prompt. To achieve this, an admin will need to delete and restore the users from within the Duo dashboard.

For more information, see [https://duo.com/docs/administration-users#activating-duo-mobile Duo's documentation].

== Troubleshooting ==

=== The second factor you supplied was incorrect. Please try again ===

Seeing this error when activating the DuoSecurity method for the first time indicates that the code does not match what DuoSecurity expects. This is caused by the time on your server not matching DuoSecurity's clocks.

You can see the time in the top-right corner of your WHMCS Admin Area. WHMCS retrieves this directly from your server's PHP configuration and you must ensure that the server time is synced exactly with UTC. For example, if the server time is 00:01 and the time at DuoSecurity is 00:00, you will see this error. Syncing the server with [http://en.wikipedia.org/wiki/Network_Time_Protocol NTP] to verify the time will resolve this.

Different timezones are taken into account, ensuring that these differences won't cause a problem.

=== Invalid Integration ===
An Invalid Integration error is displayed on the Duo authentication screen when the keys/hostname used in Duo module configuration are incorrect. Please reconfigure the module settings by [[#Configuring_Duo_Security|following the steps above]].

Version 8.9 Release Notes

2024-03-12T16:25:47Z

John: Added th to date

<div class="docs-alert-info" style="max-width:370px;">
<span class="title">Release Information</span>
<br />
Version: 8.9.0<br />
Release Type: General Availability<br />
Latest Update: 6th March 2024<br />
Distribution Types: Full and Via Automatic Updater
</div>

<div class="docs-alert-success">
For more information on WHMCS 8.9's important changes and exciting features, see [[New and Improved in WHMCS 8.9]].
</div>

==Version History==

<onlyinclude>
<table class="table table-striped">
<tr><td>8.9.0</td><td>Beta</td><td>6th December 2023</td></tr>
<tr><td>8.9.0</td><td>Release Candidate</td><td>7th February 2024</td></tr>
<tr><td>8.9.0</td><td>General Availability</td><td>6th March 2024</td></tr>
</table>
</onlyinclude>

==Download==

Download the latest version of WHMCS from https://download.whmcs.com/

==Upgrade Process==

WHMCS 8.0 and above requires PHP 7.2 or later. WHMCS 8.0 introduced support for PHP 7.4, and WHMCS 8.6 introduced support for PHP 8.1.

<div class="docs-alert-warning">
Make certain that you update to a WHMCS version that supports your desired PHP version or higher '''before''' updating PHP.
* The [[Automatic Updater]] only displays updates if you are running a PHP version that is compatible with that WHMCS version.
* For example, if you are running PHP 7.1 or earlier, you must update to PHP 7.2 or later before updating to WHMCS 8.0 or higher.
</div>

[[Upgrading|Upgrade Instructions]]

===Automatic Updating===

If you are running WHMCS 7.0 or later, you can use the built-in [[Automatic Updater]].

Go to '''Utilities > Update WHMCS''' to begin the process.

<div class="docs-alert-info">
If the update was released recently, you may need to click '''Check for Updates''' before the update will be available.
</div>

== Release Notes ==

=== New PayPal® Payment Gateways ===

The new '''PayPal Payments''' payment gateway module allows merchants to process and store payment methods using PayPal's latest secure tokenization system, including the advanced security of merchant-level vaulting with PayPal Vault for supported merchants.

<div class="docs-alert-info">
Currently, PayPal supports vaulting for merchants in:
* The United States
* Canada
* The United Kingdom
* Australia
* The following EU countries: Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia.
</div>

When you use '''PayPal Payments''', clients can make one-click payments using PayPal during checkout and on invoices.

When you activate '''PayPal Payments''', it also activates the '''[[PayPal Card Payments]]''' module. This module augments '''PayPal Payments''', allowing you to display a separate unbranded option to accept credit and debit cards during checkout. Both modules use the '''PayPal Payments''' configured PayPal account information for a seamless experience.

You can enable the new '''PayPal Payments''' module at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''. For more information, see [https://help.whmcs.com/m/payments/l/1782848-start-using-paypal-payments Start Using PayPal Payments].

<div class="docs-alert-warning">If you enabled these modules while using the Beta release of WHMCS 8.9, you '''must''' reactivate them before using them with WHMCS 8.9 Release Candidate or later. If you do not do this, you may experience problems with some payment methods.</div>

[[PayPal|Learn More]]

=== Transactions List ===

We have updated the displayed transaction details at '''Billing > [[Transactions|Transactions List]]''' to include additional information and currency codes for some amounts.

=== On-Demand Renewals ===

On-Demand Renewals now allow early renewals for product addons. When you enable on-demand renewals, clients can renew services in the Client Area before WHMCS generates their next invoice, with no manual action from your staff.

* You can configure on-demand renewals globally in the '''[[Ordering_Tab|Ordering]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings'''.
* You can configure on-demand renewals for individual product addons in the '''Pricing''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Product Addons]]'''.

[[On-Demand Renewals|Learn More]]

==== On-Demand Renewal Product Settings ====

We have moved the product-specific '''On-Demand Renewals''' settings at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' from the '''Other''' tab to the '''Pricing''' tab.

[https://help.whmcs.com/m/payments/l/1706772-configuring-on-demand-renewals Learn More]

=== Separated Invoice Viewing and Management ===

Invoices in the WHMCS Admin Area now default to a view-only mode. This prevents accidental editing while viewing an invoice and gives admins more fine-grained control over staff permissions.

* This change affects invoices at '''Billing > [[Invoices]]''' and in a client's profile's '''[[Clients:Invoices_Tab|Invoices]]''' tab.
* Admins can still add payments, resend emails, and perform certain other tasks in view-only mode if they have the related permissions for those tasks.

A new ''View Invoice'' permission at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]''' grants admins the ability to view, but not alter, existing invoices. Admins who already had the ''Manage Invoices'' permission will continue to be able to edit invoices by clicking '''Manage Invoice''' while viewing an invoice.

[[Invoices|Learn More]]

=== Duo® Universal Prompt ===

We have updated our integration with Duo Security to use the new [https://guide.duo.com/universal-prompt|Universal Prompt] login process. This change replaces the previous iframe-based experience and implements a simplified interface that continues to support Duo's wide range of Two-Factor Authentication options.

<div class="docs-alert-info">
Duo has announced that support for the previous iframe-based Duo Prompt will [https://duo.com/docs/universal-prompt-update-guide end on March 30, 2024].

* Duo Security will '''not''' function in WHMCS 8.8 and earlier after this date.
* After you upgrade to WHMCS 8.9 or later, we '''strongly''' recommend activating [https://guide.duo.com/universal-prompt Duo Universal Prompt] in your Duo customer portal to ensure continued functionality. If you do not do this, your customers may experience problems.
</div>

[[Duo Security|Learn More]]

=== Show on Order Form State ===

Payment gateway modules now support a <tt>VisibleDefault</tt> metadata parameter that defines the default '''Show on Order Form''' setting. This parameter defaults to <tt>true</tt> for all payment gateway modules.

[https://developers.whmcs.com/payment-gateways/meta-data-params/ Learn More]

=== Improved Invoice ID Incrementation ===

To improve how WHMCS handles incrementing invoice ID numbers, we have updated the following settings in the '''[[Invoice_Tab|Invoices]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''':

* '''Invoice # Incrementation''' now has a maximum value of <tt>999</tt>.
* '''Invoice Starting #''' now has a maximum value of <tt>499,999,999</tt>.
* The maximum invoice ID number that the system can generate has increased from <tt>2,147,483,647</tt> to <tt>4,294,967,295</tt>.

=== Improved Apps & Integrations Experience ===

We have optimized page performance at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps_and_Integrations|Apps & Integrations]]''', allowing you to search for modules faster.

=== Stripe™ Module API Updates ===

We have updated the [[Stripe]], [[Stripe ACH]], and [[Stripe SEPA]] modules. We have updated the Stripe PHP Library and implemented other module improvements.

Additionally, '''Stripe ACH''' and '''Stripe SEPA''' now use Stripe's <tt>PaymentIntents</tt> API instead of the now-deprecated Stripe API. Patches will be available soon for installations that run WHMCS 8.5, 8.6, 8.7, or 8.8.

[[Stripe|Learn More]]

=== Enhanced Domain Pricing Validation ===

The system now validates your PHP configuration's <tt>max_input_vars</tt> setting before saving changes at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]'''. This helps to prevent MySQL® errors and other issues that low <tt>max_input_vars</tt> values may cause.

[https://go.whmcs.com/1809/PHP-max-input-vars-Setting-Errors Learn More]

=== Blesta 5 Support in ImportAssist ===

The [[ImportAssist]] addon module now supports importing data from Blesta 5. This is a direct change to the '''ImportAssist''' module and is not specific to WHMCS 8.9.

[[ImportAssist|Learn More]]

== Deprecation and Removal Notices ==

=== Plaid Settings in Stripe ACH Module ===

We have removed support for Plaid from the [[Stripe ACH]] payment gateway module. This includes removing the '''Plaid Client Id''', '''Plaid Secret''', and '''Plaid Environment''' settings from the module's configuration.

== Templates ==

For a list of changed files and a graphical view of the exact changes, see the GitHub™ repositories below.

===Twenty-One Theme===

The following link provides a comparison of changes between 8.8.0 and 8.9.0:

https://github.com/WHMCS/templates-twenty-one/compare/v8.8.0-release.1...v8.9.0-release.1

=== Six Theme ===

The following link provides a comparison of changes between 8.8.0 and 8.9.0:

https://github.com/WHMCS/templates-six/compare/v8.8.0-release.1...v8.9.0-release.1

=== Standard Cart Order Form ===

The following link provides a comparison of changes between 8.8.0 and 8.9.0:

https://github.com/WHMCS/orderforms-standard_cart/compare/v8.8.0-release.1...v8.9.0-release.1

== Changelog ==

* [[Changelog:WHMCS_V8.9.0_Beta_1|Version 8.9.0 Beta 1]]
* [[Changelog:WHMCS_V8.9.0_RC_1|Version 8.9.0 RC 1]]
* [[Changelog:WHMCS_V8.9.0_GA|Version 8.9.0 GA 1]]

Billing Logic

2024-02-06T11:36:20Z

John: /* Renewal Invoices */

Billing and invoicing are two of the most important tasks that WHMCS can automate for you. It is important to understand these systems as you configure them so that you can make the best available choices.

==Ordering==

When a new visitor places an order, the system creates several new records, which contain the various pieces of information on the order form:

* A client record, which stores the customer's contact details and payment preferences.
* The service and domain record(s), which contain the details of the service the client selected on the order form.
* An invoice record, which records the amount to pay, when it is due, and how to make payment.
* An order record, which ties all of the above together and records the fraud report details (if you enable them). The order is a static record which reflects the prices and items at the time of ordering. The order won't reflect subsequent changes.

==Invoicing==

===Initial Invoice===

When an initial order creates an invoice, the default behavior is that the invoice is due on the day of ordering. The exception to this is when you use the '''[[Ordering_Tab#Order_Days_Grace|Order Grace Days]]''' setting, in which case the system will set the invoice due date <tt>x</tt> days into the future.

Upon payment of the initial invoice, the system checks the associated products to determine whether to take action automatically, based on the configuration in the '''[[Products_and_Services|Module Settings]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.

The system then increments the service's Next Due Date value forward one billing cycle (for example, 1 month, 3 months, 6 months, 1 year, 2 years, or 3 years).

===Renewal Invoices===

<div class="docs-alert-info">
In WHMCS 8.8 and later, you can enable and configure on-demand renewals to allow customers to renew services early, before invoice generation, from within the Client Area. For more information, see [[On-Demand Renewals]].
</div>

The Next Due Date of the service determines the date at which the next payment is due. When the cron job executes the daily automation tasks, the system:

* Analyzes the '''Next Due Date''' of all ''Active'' and ''Suspended'' services.
* Analyzes the '''Next Due Date''' value for all ''Active'' and ''Pending'' domains for which '''Do Not Renew''' is ''Off''.
* Determines whether the date is equal to or less than the number of days in the future, based on the Invoice Generation setting.
* Ensures no invoice item exists for the service on the next due date.
* Generates a new invoice if the system evaluates the above points as true.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicecreation InvoiceCreation] Action Hook point.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicecreationpreemail InvoiceCreationPreEmail] Action Hook point.
* Sends the Invoice Created email to the client.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicecreated InvoiceCreated] Action Hook point.
* Increments the Next Invoice Date of the service by one billing cycle.

In this way, WHMCS will never generate two invoices for a given product, service, or domain with the same due date, even if you have cancelled or deleted the original invoice.

As the Next Due Date is incremented forward based upon the previous value, this means paying an invoice after the due date will not change the client's renewal date to reflect the date of payment. A service always invoices for a contiguous period without gaps. This prevents a situation in which a customer might hope to avoid paying for a service by intentionally paying late.

===Continuous Invoice Generation===

When you enable the '''[[Invoicing_Setup#Continuous_Invoice_Generation|Continuous Invoice Generation]]''' option in the '''[[Invoice Tab|Invoice]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings''', it alters the invoice generation logic so that the system creates renewal invoices even if the previous one is unpaid.

Checking a hidden field in the service record, Next Invoice Date, enables this. The Next Invoice Date field maintains a separate record of the due date for next invoice to generate. The Next Due Date value determines the next invoice to be paid.

In this mode, when the cron job executes the daily automation tasks, it:
* Analyzes the Next Invoice Date of all Active, Pending and Suspended services.
* Determines whether the date is equal to or less than the number of days in the future, based on the Invoice Generation setting.
* Ensures no invoice item exists for the service on the next invoice date.
* Generates a new invoice if the system evaluates the above points as true.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicecreation InvoiceCreation] Action Hook point.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicecreationpreemail InvoiceCreationPreEmail] Action Hook point.
* Sends the Invoice Created email to the client.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicecreated InvoiceCreated] Action Hook point.
* Increments the Next Invoice Date of the service by one billing cycle.

In this way, WHMCS maintains a separate record of which invoice to generate and which payment is due.

==Payments==

A transaction that fully pays the balance on an invoice, reducing it to <tt>0.00</tt> and marking it paid, triggers automation on payment. This means that editing an invoice and changing the status to ''Paid'' will ''not'' trigger automation.

Upon adding payment to an invoice for a product, service, or domain, the system:

* Enters a transaction into the database.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#addtransaction AddTransaction] Action Hook point.
* Subtracts the transaction amount from the invoice balance.
* Marks the invoice as paid if the invoice balance is now 0.
* Changes the invoice status to Paid.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicepaidpreemail InvoicePaidPreEmail] Action Hook point.
* Sends a payment confirmation email to the client.
* Increments the Next Due Date of the associated service or domain by one billing cycle.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicepaid InvoicePaid] Action Hook point.

===Overpayments===

If a transaction includes an amount greater than the balance of the invoice, the system:

* Records the entire transaction against the invoice, making the balance negative.
* Marks the invoice as paid.
* Credits the difference between the balance and the transaction amount to the client's account.
* Changes the credit description format to ''Invoice # Overpayment''.

Sometimes, fixed payments services (like [[2CheckOut]] and some [[PayPal]]® recurring payments) can send a payment when no payment is due.

In these situations, the system:

* Records the entire transaction against the invoice that originally created the billing agreement, making the balance negative.
* Credits the full transaction amount to the client's account.
* Changes the credit description format to ''Invoice # Overpayment''.

===Refunds===

You can issue refunds on transactions for invoices via the '''Refunds''' tab.

When a you initiate a refund, the system:

* Performs the selected refund action, which could be either of the following actions:
** It sends a refund command to the payment gateway if it supports it.
** It adds a credit to the client's account with the description ''Credit from Refund of Invoice ID #''.
* Records a negative transaction against the invoice.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#addtransaction AddTransaction Action Hook] point.
* Increases the invoice's balance by the refunded amount.
* Changes the invoice's status to Refunded if system refunded the full balance.
* Triggers the [https://developers.whmcs.com/hooks-reference/invoices-and-quotes/#invoicerefunded InvoiceRefunded] Action Hook point.
* Sends the Invoice Refund Confirmation email to the client.

If the refunded transaction resulted in a credit to the client's account, you must choose how to handle the credit:

* Remove the refunded amount from the credit balance.
* Do not change the credit.

===Payment Reversals===

When you issue a [[#Refunds|refund]], you have the option to reverse the payment. This is useful when you want to reverse the automated actions that the payment triggered, typically due to a [[Disputes|dispute]].

The actions that the system takes when reversing a payment are context sensitive and depend on your payment reversal settings. For more information, see [[Payment Reversals]].

===Affiliate Commission Reversals===

When you issue a [[#Refunds|refund]], you can also reverse any affiliate commissions. This helps you ensure that you do not pay commissions to affiliates unless you also received payment for the transaction.

When you refund a transaction, one of the following scenarios will occur:

* If you are giving a full refund, WHMCS will perform the reversal automatically.
* If you are giving a partial refund, you can choose whether to perform the reversal.

For more information on affiliate commission reversals and delays, see [[Affiliates]].

===Billing Cycles===

A billing cycle is a calendar period, so "1 month" is not a consistent period of days. When you agree to bill by the month, you are charging the same amount of money for different amounts of service. WHMCS uses the PHP date function's computation to determine the next due date. It adds a month and returns the date, which becomes the Next Due Date.

The following billing cycles are available for products or services and product addons:

* One Time
* Monthly
* Quarterly
* Semi-Annually
* Annually
* Biennially
* Triennially

====February====

The shorter length of February can cause some unique behaviour that does not happen for the other 11 months of a year:

<table class="table table-striped">
<tr>
<td>'''Order Date'''</td>
<td>'''Renewal Date'''</td>
<td>'''Number of Days'''</td>
</tr>
<tr>
<td>January 29</td>
<td>March 1</td>
<td>31 days</td>
</tr>
<tr>
<td>January 30 </td>
<td>March 2</td>
<td>31 days</td>
</tr>
<tr>
<td>January 31</td>
<td>March 3</td>
<td>31 days</td>
</tr>
<tr>
<td>February 1</td>
<td>March 1</td>
<td>28 days</td>
</tr>
<tr>
<td>February 2</td>
<td>March 2</td>
<td>28 days</td>
</tr>
<tr>
<td>February 3</td>
<td>March 3</td>
<td>28 days</td>
</tr>
</table>

==Suspension==

The Next Due Date for the service controls the date of service suspension. When the cron job executes the daily automation tasks, the system:

* Analyzes the Next Due Date of all Active and Pending services.
* Determines whether the date is equal to or less than the number of days in the future in the Suspension Days setting.
* Determines whether Automated Suspension is enabled in [[Automation Settings]].
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#premodulesuspend PreModuleSuspend] Action Hook point if the above items evaluate to true.
* Suspends the services.
* Applies a suspension reason of "Overdue on Payment" to the service.
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#aftermodulesuspend AfterModuleSuspend] Action Hook point if the module returns a success response.
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#aftermodulesuspendfailed AfterModuleSuspendFailed] Action Hook point If the module returns a failed response.

==Unsuspension==

When payment is made against an invoice for a service with the Suspended status, the system can automatically unsuspend the service.

In addition to the actions in the [[#Payments|Payments]] section, the system:

* Analyzes the invoices associated with a service in Suspended status and a Suspension Reason matching "Overdue on Payment".
* Asserts the Enable Unsuspension option is enabled in [[Automation Settings]].
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#premoduleunsuspend PreModuleUnsuspend] Action Hook point if the points above evaluate to true.
* Unsuspends the service.
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#aftermoduleunsuspend AfterModuleUnsuspend] Action Hook point if the module returns a success response.
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#aftermoduleunsuspendfailed AfterModuleUnsuspendFailed] Action Hook point if the module returns a failed response.

===Continuous Invoice Generation===

When you use it in conjunction with [[Invoicing_Setup#Continuous_Invoice_Generation|continuous invoice generation]], paying a recent invoice while leaving an older invoice unpaid will keep the service suspended. The exception is if the payment were to increment the Next Due Date forward to a date at which the service was no longer within the Suspension date range. In that case, the service would be unsuspended.

==Termination==

The Next Due Date of the service controls the date when the system terminates services. When the cron job executes the daily automation tasks, the system:

* Analyzes the Next Due Date of all Active, Suspended and Pending services.
* Determines whether the date is equal to or less than the number of days in the future for the Termination Days setting.
* Determines whether you enabled Automated Termination in [[Automation Settings]].
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#premoduleterminate PreModuleTerminate] Action Hook point if the above points evaluate to true.
* Terminates the services.
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#aftermoduleterminate AfterModuleTerminate] Action Hook point if the module returns a success response.
* Triggers the [https://developers.whmcs.com/hooks-reference/module/#aftermoduleterminatefailed AfterModuleTerminateFailed] Action Hook point if the module returns a failure response.

Stripe

2024-01-31T12:31:49Z

John: /* You passed an empty string for 'statement_descriptor' */

== About this Module ==

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system to submit credit card information to Stripe, which stores it remotely.

For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]].
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-warning">
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.
</div>
== Adding the Stripe Payment Gateway ==

[[File:stripe.png|thumb|Stripe Module Settings]]

To set up the Stripe payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Stripe'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Configure a display name. We recommend <tt>Credit Card</tt>.
# Go to the [https://dashboard.stripe.com/account/apikeys Stripe portal] and retrieve the publishable and secret API keys.
# Enter your Stripe API Keys. <div class="docs-alert-info"><i class="fa fa-info-circle"></i> To test Stripe, enter your [https://stripe.com/docs/keys#obtain-api-keys Stripe Test Mode API Keys].</div>
# Optionally, customize the '''Statement Descriptor Suffix''' with a maximum of 22 characters.
# In WHMCS 8.0 and later, leave the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' empty. WHMCS auto-generates these. See below for more information.
# Optionally, check '''Allow Payment Request Buttons'''. See below for more information.
# Click '''Save Changes'''.
# If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account's currency with a valid exchange rate at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. Stripe only returns transaction fees in the default currency for the Stripe account.

=== WebHook Endpoints ===

<div class="docs-alert-info">
You can use Stripe Webhooks in WHMCS v8.0 and above.
</div>

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click '''Save Changes''', WHMCS will use the '''Stripe Publishable API Key''' and '''Stripe Secret API Key''' to generate the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

* If you enter live API keys (<tt>sk_live</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret'''.
* If you enter test API keys (<tt>sk_test</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

WHMCS registers the WebHook Endpoints to deliver these events from Stripe:

* <tt>customer.source.updated</tt>
* <tt>payment_method.updated</tt>

To change the WebHook ID, empty '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' and click '''Save Changes'''. WHMCS will auto-generate them again with new values.

=== Payment Request Button ===

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay). For customers who don’t use Apple Pay, '''Payment Request''' supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

==== Apple Pay ====

[[File:apple_pay_checkout.png|thumb|The Apple Pay Button on Checkout]]

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they're using Safari® on their iPhone® or iPad®, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac®, and have an iOS® device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, <tt><nowiki>whmcs.com</nowiki></tt>) and subdomains (for example, <tt><nowiki>shop.whmcs.com</nowiki></tt>).
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> An SSL certificate is '''required''' to use Apple Pay.</div>

To do this:

# Download this [https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association domain association file] and host it at <tt>/.well-known/apple-developer-merchantid-domain-association</tt> on your site. For example, if you're registering <tt><nowiki>https://example.com</nowiki></tt>, make that file available at <tt><nowiki>https://example.com/.well-known/apple-developer-merchantid-domain-association</nowiki></tt>.
# To instruct Stripe to register the domain with Apple, go to the '''[https://dashboard.stripe.com/account/apple_pay Apple Pay]''' tab in '''Account Settings''' in the Stripe Dashboard.

==== Google Pay ====

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

==== Microsoft Pay ====

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

==== Link ====
In WHMCS 8.8 and later, customers can pay using [https://stripe.com/en-ca/payments/link Link] for any Stripe transaction. Link makes payments easier by letting customers complete secure, one-click transactions using saved payment information. Stripe enables Link automatically.

For more information about disabling Link for your Stripe account, see [https://support.stripe.com/questions/how-to-turn-off-link How to Turn Off Link].

=== Test Mode ===

This module does not support test mode.

== Payment Workflow ==

[[File:stripe_checkout.png|thumb|The Stripe module on Checkout]]

The Stripe module supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

* In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorization is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.
* In WHMCS 8.8 and later, Stripe module transactions [https://support.stripe.com/questions/guide-for-indian-government-regulations-on-network-tokenization meet all Reserve Bank of India requirements].

<div class="docs-alert-info">
WHMCS 8.3 and higher includes support for disputes for Stripe and PayPal® Checkout transactions at '''Billing > [[Disputes]]'''.
</div>

===Recurring Payments===

Automated recurring payments use stored tokens. If a client card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

== Payment Gateway Balances ==

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At '''Billing > [[Transactions]]''', you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see [[Payment Gateway Balances and Transactions]].

This requires you to enable '''View Gateway Balances''' for the desired administrator role at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]'''.

<div class="docs-alert-warning">
In the Admin Area [[Admin_Dashboard|Dashboard]], you can view your Stripe balances through the '''Stripe Balance''' widget. However, this widget does not use the <tt>WHMCS\Module\Gateway\Balance</tt> and <tt>WHMCS\Module\Gateway\BalanceCollection</tt> classes to display balances. For more information, see [[Stripe Balance Widget]].
</div>

== Migrating to Stripe ==

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe's tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 8.0 to 8.6, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > Payment Gateways''' and choose '''All Payment Gateways'''.
# Activate the Stripe module.
# Click '''Deactivate''' for your previous merchant gateway provider.
# Select Stripe as the replacement gateway to switch users of the previous gateway module to.
# Click '''OK'''.

=== Migrating from a 3rd Party Stripe Module ===

The WHMCS Stripe module uses the Stripe <tt>cus_</tt> reference to capture payments (for example, <tt>cus_9MvIb7UlgJfJTn</tt>). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the <tt>cus_</tt> reference, navigate to a client that you know has an active Stripe token and click on one of the pay methods in the '''Summary''' tab of the client's profile. Verify that the listed token includes the <tt>cus_</tt> prefix.

To start using the WHMCS Stripe module:

# Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the <tt>tblpaymentgateways</tt> database table.
# Activate our official Stripe module.
# Deactivate the previous Stripe module.
# Check one of the Stripe pay methods on a client. If the token contains <tt>cus{_}</tt>, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing "example" with the name of the previous module: <source lang="sql">UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example'; </source>
# Remove any third-party files and template customisations for the previous Stripe module.

==Troubleshooting==

===Remote Transaction Failure. Please Contact Support===

This issue has multiple causes. This may also display as '''Error'''.

To resolve this issue:

# Go to '''Billing > Gateway Log'''.
# Check the '''Result''' and '''Debug Data''' columns for error messages or codes from the time of the payment attempt.
# Perform the appropriate steps in Stripe's [https://stripe.com/docs/error-codes Error Codes] and [https://stripe.com/docs/declines/codes Declines Codes] documentation.

See below for other common causes of this error:

====Payment Blocked By Stripe====

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

# Log in to your [https://dashboard.stripe.com/ Stripe Dashboard].
# Go to '''Developers > Logs'''.
# Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment was blocked (for example, with a '''The zip code you supplied failed validation''' error).
# Adjust the rules in your Stripe account for the error. For help, contact [https://support.stripe.com/ Stripe support].

====Customisations====

This issue may also present itself as '''"No Stripe Details Found for Update"''' in the '''Gateway Log'''.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, these issues may trigger this error:

* A hook file in <tt>/includes/hooks/stripe.php</tt>. Remove this file when switching to the WHMCS Stripe module.
* Template customisations in your active order form template files.
* The payment method is set to a module other than Stripe. In this case, perform one of the following actions:
** Change the client's '''Payment Method''' setting in the client's '''Profile''' tab to the Stripe module.
** Make Stripe the system default payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

====Out Of Date Template Files====

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The [[Release Notes]] for each version of WHMCS provide links to template changes.

====Network Analyser Tool====

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section '''Another Error Type''' in [https://help.whmcs.com/m/troubleshooting/l/1312423-an-error-occurred-while-communicating-with-the-server-please-try-again this help article]. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

===No Stripe Customer Details Found===
The system logs this error in the debug data section of '''Billing > [[Gateway Log]]'''. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the '''[[Pay Methods]]''' section of the client's '''[[Clients:Summary Tab|Summary]]''' tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe. This will create a payment method to use for future automatic payments.

==="You must provide a value for 'cvc'===

If you see at '''Billing > [[Gateway Log]]''' for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe.

For more information, see [https://stripe.com/docs/api?lang=python#create_card_token Stripe's documentation] (click '''show child parameters''').

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

===Network error [errno 35]: Unsupported SSL protocol version===
This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes. For more information, see [https://stripe.com/docs/security#tls Stripe TLS Documentation].

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

===You passed an empty string for 'statement_descriptor'===
This indicates an empty '''Statement Descriptor''' field in the payment gateway configuration. Make certain that you set your entire [[#Adding_the_Stripe_Payment_Gateway|gateway configuration]].

===Bad Request===
This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe. To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab (which may display a more-informative error to administrators). Then, add the payment method again.

Customised or outdated system themes or order form templates can also cause this error. To troubleshoot this:

# Go to the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Select ''Six'' or ''Twenty-One'' for '''System Theme'''.
# Go to the '''[[Ordering Tab|Ordering]]''' tab.
# Select a '''[[Standard_Order_Form_Templates|Default Order Form Template]]'''.
# Click '''Save Changes'''.
# Return to the Client Area and refresh the page.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

===An unexpected error - No Stripe Payment Method found from token===
This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

This can also be caused by a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.
* If one is, the custom JavaScript will need to be corrected.
* If the JavaScript error is coming from a third-party customisation, contact the developer for assistance.

If the issue persists, contact our [https://www.whmcs.com/submit-a-ticket/ support team].

===Error Updating Remote Pay Method: Remote Storage Failed===
You can find information about this error at '''Billing > [[Gateway Log]]'''.

===Stripe India Accounts===
India-based Stripe accounts require the following additional conditions for a successful payment capture:

* The client's address and billing contact must use a valid Indian postal address.
* The payment card must be from an Indian bank.
* The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies upon payment in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
# Add <tt>INR</tt> as an [[Currencies#Adding.2FEditing_a_Currency|additional currency]].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Set '''Convert To For Processing''' on the Stripe gateway to ''INR''.

For more information about the additional Stripe requirements for Indian Stripe accounts, see [https://support.stripe.com/questions/requirements-for-india-export-charges Stripe's documentation].

{{modules}}

Stripe

2024-01-29T16:36:39Z

John: /* WebHook Endpoints */

== About this Module ==

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system to submit credit card information to Stripe, which stores it remotely.

For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]].
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-warning">
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.
</div>
== Adding the Stripe Payment Gateway ==

[[File:stripe.png|thumb|Stripe Module Settings]]

To set up the Stripe payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Stripe'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Configure a display name. We recommend <tt>Credit Card</tt>.
# Go to the [https://dashboard.stripe.com/account/apikeys Stripe portal] and retrieve the publishable and secret API keys.
# Enter your Stripe API Keys. <div class="docs-alert-info"><i class="fa fa-info-circle"></i> To test Stripe, enter your [https://stripe.com/docs/keys#obtain-api-keys Stripe Test Mode API Keys].</div>
# Optionally, customize the '''Statement Descriptor Suffix''' with a maximum of 22 characters.
# In WHMCS 8.0 and later, leave the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' empty. WHMCS auto-generates these. See below for more information.
# Optionally, check '''Allow Payment Request Buttons'''. See below for more information.
# Click '''Save Changes'''.
# If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account's currency with a valid exchange rate at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. Stripe only returns transaction fees in the default currency for the Stripe account.

=== WebHook Endpoints ===

<div class="docs-alert-info">
You can use Stripe Webhooks in WHMCS v8.0 and above.
</div>

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click '''Save Changes''', WHMCS will use the '''Stripe Publishable API Key''' and '''Stripe Secret API Key''' to generate the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

* If you enter live API keys (<tt>sk_live</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret'''.
* If you enter test API keys (<tt>sk_test</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

WHMCS registers the WebHook Endpoints to deliver these events from Stripe:

* <tt>customer.source.updated</tt>
* <tt>payment_method.updated</tt>

To change the WebHook ID, empty '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' and click '''Save Changes'''. WHMCS will auto-generate them again with new values.

=== Payment Request Button ===

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay). For customers who don’t use Apple Pay, '''Payment Request''' supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

==== Apple Pay ====

[[File:apple_pay_checkout.png|thumb|The Apple Pay Button on Checkout]]

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they're using Safari® on their iPhone® or iPad®, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac®, and have an iOS® device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, <tt><nowiki>whmcs.com</nowiki></tt>) and subdomains (for example, <tt><nowiki>shop.whmcs.com</nowiki></tt>).
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> An SSL certificate is '''required''' to use Apple Pay.</div>

To do this:

# Download this [https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association domain association file] and host it at <tt>/.well-known/apple-developer-merchantid-domain-association</tt> on your site. For example, if you're registering <tt><nowiki>https://example.com</nowiki></tt>, make that file available at <tt><nowiki>https://example.com/.well-known/apple-developer-merchantid-domain-association</nowiki></tt>.
# To instruct Stripe to register the domain with Apple, go to the '''[https://dashboard.stripe.com/account/apple_pay Apple Pay]''' tab in '''Account Settings''' in the Stripe Dashboard.

==== Google Pay ====

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

==== Microsoft Pay ====

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

==== Link ====
In WHMCS 8.8 and later, customers can pay using [https://stripe.com/en-ca/payments/link Link] for any Stripe transaction. Link makes payments easier by letting customers complete secure, one-click transactions using saved payment information. Stripe enables Link automatically.

For more information about disabling Link for your Stripe account, see [https://support.stripe.com/questions/how-to-turn-off-link How to Turn Off Link].

=== Test Mode ===

This module does not support test mode.

== Payment Workflow ==

[[File:stripe_checkout.png|thumb|The Stripe module on Checkout]]

The Stripe module supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

* In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorization is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.
* In WHMCS 8.8 and later, Stripe module transactions [https://support.stripe.com/questions/guide-for-indian-government-regulations-on-network-tokenization meet all Reserve Bank of India requirements].

<div class="docs-alert-info">
WHMCS 8.3 and higher includes support for disputes for Stripe and PayPal® Checkout transactions at '''Billing > [[Disputes]]'''.
</div>

===Recurring Payments===

Automated recurring payments use stored tokens. If a client card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

== Payment Gateway Balances ==

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At '''Billing > [[Transactions]]''', you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see [[Payment Gateway Balances and Transactions]].

This requires you to enable '''View Gateway Balances''' for the desired administrator role at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]'''.

<div class="docs-alert-warning">
In the Admin Area [[Admin_Dashboard|Dashboard]], you can view your Stripe balances through the '''Stripe Balance''' widget. However, this widget does not use the <tt>WHMCS\Module\Gateway\Balance</tt> and <tt>WHMCS\Module\Gateway\BalanceCollection</tt> classes to display balances. For more information, see [[Stripe Balance Widget]].
</div>

== Migrating to Stripe ==

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe's tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 8.0 to 8.6, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > Payment Gateways''' and choose '''All Payment Gateways'''.
# Activate the Stripe module.
# Click '''Deactivate''' for your previous merchant gateway provider.
# Select Stripe as the replacement gateway to switch users of the previous gateway module to.
# Click '''OK'''.

=== Migrating from a 3rd Party Stripe Module ===

The WHMCS Stripe module uses the Stripe <tt>cus_</tt> reference to capture payments (for example, <tt>cus_9MvIb7UlgJfJTn</tt>). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the <tt>cus_</tt> reference, navigate to a client that you know has an active Stripe token and click on one of the pay methods in the '''Summary''' tab of the client's profile. Verify that the listed token includes the <tt>cus_</tt> prefix.

To start using the WHMCS Stripe module:

# Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the <tt>tblpaymentgateways</tt> database table.
# Activate our official Stripe module.
# Deactivate the previous Stripe module.
# Check one of the Stripe pay methods on a client. If the token contains <tt>cus{_}</tt>, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing "example" with the name of the previous module: <source lang="sql">UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example'; </source>
# Remove any third-party files and template customisations for the previous Stripe module.

==Troubleshooting==

===Remote Transaction Failure. Please Contact Support===

This issue has multiple causes. This may also display as '''Error'''.

To resolve this issue:

# Go to '''Billing > Gateway Log'''.
# Check the '''Result''' and '''Debug Data''' columns for error messages or codes from the time of the payment attempt.
# Perform the appropriate steps in Stripe's [https://stripe.com/docs/error-codes Error Codes] and [https://stripe.com/docs/declines/codes Declines Codes] documentation.

See below for other common causes of this error:

====Payment Blocked By Stripe====

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

# Log in to your [https://dashboard.stripe.com/ Stripe Dashboard].
# Go to '''Developers > Logs'''.
# Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment was blocked (for example, with a '''The zip code you supplied failed validation''' error).
# Adjust the rules in your Stripe account for the error. For help, contact [https://support.stripe.com/ Stripe support].

====Customisations====

This issue may also present itself as '''"No Stripe Details Found for Update"''' in the '''Gateway Log'''.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, these issues may trigger this error:

* A hook file in <tt>/includes/hooks/stripe.php</tt>. Remove this file when switching to the WHMCS Stripe module.
* Template customisations in your active order form template files.
* The payment method is set to a module other than Stripe. In this case, perform one of the following actions:
** Change the client's '''Payment Method''' setting in the client's '''Profile''' tab to the Stripe module.
** Make Stripe the system default payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

====Out Of Date Template Files====

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The [[Release Notes]] for each version of WHMCS provide links to template changes.

====Network Analyser Tool====

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section '''Another Error Type''' in [https://help.whmcs.com/m/troubleshooting/l/1312423-an-error-occurred-while-communicating-with-the-server-please-try-again this help article]. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

===No Stripe Customer Details Found===
The system logs this error in the debug data section of '''Billing > [[Gateway Log]]'''. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the '''[[Pay Methods]]''' section of the client's '''[[Clients:Summary Tab|Summary]]''' tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe. This will create a payment method to use for future automatic payments.

==="You must provide a value for 'cvc'===

If you see at '''Billing > [[Gateway Log]]''' for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe.

For more information, see [https://stripe.com/docs/api?lang=python#create_card_token Stripe's documentation] (click '''show child parameters''').

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

===Network error [errno 35]: Unsupported SSL protocol version===
This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes. For more information, see [https://stripe.com/docs/security#tls Stripe TLS Documentation].

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

===You passed an empty string for 'statement_descriptor'===
This indicates an empty '''Statement Descriptor''' field in the payment gateway configuration. Make certain that you set your entire [[#Setup|gateway configuration]].

===Bad Request===
This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe. To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab (which may display a more-informative error to administrators). Then, add the payment method again.

Customised or outdated system themes or order form templates can also cause this error. To troubleshoot this:

# Go to the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Select ''Six'' or ''Twenty-One'' for '''System Theme'''.
# Go to the '''[[Ordering Tab|Ordering]]''' tab.
# Select a '''[[Standard_Order_Form_Templates|Default Order Form Template]]'''.
# Click '''Save Changes'''.
# Return to the Client Area and refresh the page.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

===An unexpected error - No Stripe Payment Method found from token===
This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

This can also be caused by a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.
* If one is, the custom JavaScript will need to be corrected.
* If the JavaScript error is coming from a third-party customisation, contact the developer for assistance.

If the issue persists, contact our [https://www.whmcs.com/submit-a-ticket/ support team].

===Error Updating Remote Pay Method: Remote Storage Failed===
You can find information about this error at '''Billing > [[Gateway Log]]'''.

===Stripe India Accounts===
India-based Stripe accounts require the following additional conditions for a successful payment capture:

* The client's address and billing contact must use a valid Indian postal address.
* The payment card must be from an Indian bank.
* The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies upon payment in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
# Add <tt>INR</tt> as an [[Currencies#Adding.2FEditing_a_Currency|additional currency]].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Set '''Convert To For Processing''' on the Stripe gateway to ''INR''.

For more information about the additional Stripe requirements for Indian Stripe accounts, see [https://support.stripe.com/questions/requirements-for-india-export-charges Stripe's documentation].

{{modules}}

GoCardless

2024-01-08T17:41:05Z

John:

== About this Module ==

<div class="docs-alert-success">
We added this payment gateway in WHMCS 7.7.
</div>

[https://gocardless.com GoCardless] is a payment gateway which allows for direct debit payments to be automated electronically.

<div class="docs-alert-info">
<span class="title">Important</span><br />
Due to GoCardless API restrictions, you must contact GoCardless support to enable the feature.
</div>
{{gateways
| onetime = yes
| recurring = yes
| reversals = yes
}}
== Adding the GoCardless Payment Gateway ==

To set up the GoCardless payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''GoCardless'''. A GoCardless login page will appear.
# Either sign up for a new account or log in to your existing account. The system will automatically configure GoCardless for you.
# Optionally, enter a custom name for the gateway for each of your supported currencies.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
#In WHMCS 8.0 and later, enabling '''Charge Date Preference''' will allow the automation system to omit passing a <tt>charge_date</tt> value to GoCardless when the automation system triggers a payment attempt. This results in GoCardless starting the transaction as soon as possible.
# Click '''Save Changes'''.

===Charge Date Preference===

 '''Charge Date Preference''' will determine if WHMCS passes a transaction charge date to GoCardless advising when to initiate the payment.

* Disabling the option will pass through either the '''Next Due Date''' from the service or the <tt>next_possible_charge_date</tt> that GoCardless sets using the <tt>charge_date</tt> function depending on which date is later.

* If you enable the option, the system will not pass a <tt>charge_date</tt> value to GoCardless and this will result in GoCardless beginning the payment process as soon as possible.  In both scenarios, the payment attempt call to GoCardless will not occur until an invoice meets the invoice and payment capture attempt criteria that you set at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]'''.

To process the payment prior to the '''Next Due Date''' date and according to the '''Process Days Before Due''' date at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''', enable this setting. If you do not, the system may attempt the payment on or after the '''Next Due Date''' date.

=== Supported Currencies ===

GoCardless only support the following currencies:

* AUD
* CAD
* DKK
* EUR
* GBP
* NZD
* SEK
* USD <div class="docs-alert-info">We added support for USD in WHMCS 7.9.</div>

Clients who do not use one of these currencies cannot make payments using GoCardless.

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

==Payment Workflow==

When the first payment is made, a mandate is set up with the client's bank. This typically takes a few days, so the invoice will change from '''Unpaid''' to '''Payment Pending''' status. At this point, you can view the mandate details and expected payment completion date by viewing the invoice. As soon as the mandate is set up and the first payment has cleared, the invoice's status will change to '''Paid''' and the service will be provisioned by WHMCS automatically.

When the renewal invoice is generated for a recurring service, a capture attempt will be made against the mandate in accordance with '''Process Days Before Due''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''. As it can take a few days for the payment to complete, we recommend a setting of '''3'''. This way, 3 days before the invoice '''Due Date''', the payment process will be initiated by the cron and the invoice status updated from '''Unpaid''' to '''Payment Pending'''. Payment should then complete on the invoice '''Due Date''' and the invoice will be marked '''Paid''' once the payment has cleared.

After you create a mandate, WHMCS can process renewal payments for any other services associated with the client, as long as they also use the GoCardless gateway.

The system redirects clients to GoCardless to enter their bank details when setting up a mandate. Then, GoCardless returns them to WHMCS after the setup is complete. The system submits personal bank information directly to GoCardless and never stores it in your local WHMCS installation.

==Reversed Payments==

The Direct Debit Guarantee scheme allows the payee to file a claim for any payment taken in error. WHMCS will monitor for ''charged_back'' events from GoCardless and will automatically process these as appropriate.

To learn more, visit [[Payment Reversals]]

==Refunding Payments==

While refunds with GoCardless are not directly supported from within WHMCS, they can still be processed directly with GoCardless on a case-by-case basis through their review and approval process.

Please refer to the [https://support.gocardless.com/hc/en-ca/articles/210536269-Refunding-payments refunding payments] section of the GoCardless documentation.

== Mandates ==

<div class="docs-alert-success">
We added these features in WHMCS 7.8.
</div>

=== Reinstating Mandates ===

<div class="docs-alert-warning">
Reinstating mandates requires specific permission from GoCardless.
</div>

When a mandate has been accidentally cancelled, WHMCS can initiate steps to reinstate the mandate without having the client set it up again.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click the '''Manage Existing Gateways''' tab.
# Click '''Manage Cancelled Mandates'''.
# Follow the instructions in the modal that appears to reinstate a cancelled mandate.

=== Importing Existing Mandates ===

<div class="docs-alert-info">
You must disable any automatically-charged mandates that you import in order to prevent possible duplicate charges.
</div>

You can import mandates that you set up outside of WHMCS and associate them with a client.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click the '''Manage Existing Gateways''' tab.
# Click '''Import Existing Mandates'''.
# Follow the instructions in the modal that appears to import a active mandate to a specific client.

=== Removing Mandates ===

You can remove mandates by deleting the client's GoCardless [[Pay_Methods|pay method]].

To do this:

# Click on the pay method in the '''[[Clients:Summary_Tab|Summary]]''' tab of the client profile.
# Click '''Delete''' to [[Clients:Summary_Tab#Removing_Card_Details|remove the pay method]] and any associated mandates.

== Reconfiguring Callbacks ==

After moving WHMCS, you must perform the following steps:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click '''Configure GoCardless Account Connection'''.
# Log in again using the same details.

This ensures that GoCardless stores and uses the new system URL and gateway callback file URL.

== Troubleshooting ==

===Access token not active===

You can only connect each GoCardless account to a single WHMCS at a time. If you connected the GoCardless Account to multiple WHMCS installations, only the last installation that you connected will function correctly. Previously-connected WHMCS installations will show an <tt>Access token not active</tt> error at '''Billing > [[Gateway Log]]'''.

To resolve this error, you will need to reconnect WHMCS to GoCardless by [[#Reconfiguring_Callbacks|reconfiguring callbacks]].

===Remote Storage "create" action did NOT provide token===
This error indicates that the GoCardless account does not have access to the required API endpoint. Due to GoCardless API restrictions, you must contact GoCardless support to enable the feature for your account.

{{modules}}

System Requirements

2023-09-26T08:47:18Z

John:

Most current web servers* that use PHP and MySQL® can run WHMCS.

The following table shows the minimum and recommended system requirements for running '''WHMCS 8.0''' and later.

<div class="docs-alert-danger">
Looking for the requirements for the earlier WHMCS 7.5 - 7.10 versions? [[Version 7.5-7.10 System Requirements|Click here.]]
</div>

{| class="table table-striped"
! '''Requirement'''
! '''Minimum'''
! '''Recommended'''
|-
| PHP Version
| 7.2
| WHMCS 8.0 through 8.5 — ''Latest'' 7.4 Release <br /> WHMCS 8.6 and later — ''Latest'' 7.4 or 8.1 Release
|-
| PHP Memory Limit
| 64MB
| 128MB**
|-
| PHP Database Extension
| PDO
| PDO
|-
| PHP Extensions
| Curl with SSL***<br/>
GD2 Image Library<br/>
JSON Support<br />
Reflection<br/>
XML<br/>
| BC Math<br/>
Fileinfo<br/>
GMP<br/>
Iconv<br/>
Intl<br/>
MBString<br/>
OpenSSL***<br/>
SOAP<br/>
|-
| MySQL Version
| 5.2.0
| ''Latest'' 8.0
|-
| ionCube Loader®
| 10.4.5 or later for PHP 7.2 through 7.4<br/>
12.0.1 or later for PHP 8.1
| The latest ionCube Loader version for your PHP version
|}

<div class="docs-alert-info">
View all supported '''PHP versions''' for each version of WHMCS in the [[PHP Version Support Matrix]].
</div>

<div class="docs-alert-warning">
While these are the minimum requirements, we '''''strongly recommend using the latest available, stable releases of all software and extensions'''''. Recommendations are correct as at September 2022.
</div>

<div class="docs-alert-success">
For details on the recommended system environment configurations (OS, web server, database engine, PHP, and ionCube Loader), see the [[System Environment Guide]].
</div>

<nowiki>* We validate WHMCS to run in Linux based environments running the Apache web server. Other environments like Windows-based configurations may experience compatibility issues with which Technical Support cannot assist.</nowiki>

<nowiki>** Memory requirements vary depending upon the size and volume of activity in an installation. Your exact requirements may differ.</nowiki>

<nowiki>*** As part of PCI compliance, a SSL library capable of TLS 1.2 may be required. If using OpenSSL, version 1.0.1c or newer is recommended. </nowiki>

Template:MarketConnect

2023-09-19T11:46:25Z

John:

<includeonly><div style="margin-top:15px;padding:10px;background:#F9F9F9;border:1px solid #e8e8e8;text-align:center;">'''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[MarketConnect]]'''<br />{{#ifeq:{{{type|}}}|SSL Certificates|'''SSL Certificates'''|[[SSL_Certificates_via_WHMCS_MarketConnect|SSL Certificates]]}} {{!}} {{#ifeq:{{{type|}}}|SpamExperts|'''SpamExperts'''|[[SpamExperts_via_WHMCS_MarketConnect|SpamExperts]]}} {{!}} {{#ifeq:{{{type|}}}|SiteLock|'''SiteLock'''|[[SiteLock_via_WHMCS_MarketConnect|SiteLock]]}} {{!}} {{#ifeq:{{{type|}}}|SiteLock VPN|'''SiteLock VPN'''|[[SiteLock_VPN_via_MarketConnect|SiteLock VPN]]}} {{!}} {{#ifeq:{{{type|}}}|CodeGuard|''"CodeGuard'''|[[CodeGuard_via_WHMCS_MarketConnect|CodeGuard]]}} {{!}} {{#ifeq:{{{type|}}}|MarketGoo|'''MarketGoo'''|[[Marketgoo_via_WHMCS_MarketConnect|marketgoo]]}}
<br /> {{#ifeq:{{{type|}}}|OX App Suite|'''OX App Suite'''|[[OX_App_Suite_via_WHMCS_MarketConnect|OX App Suite]]}} {{!}} {{#ifeq:{{{type|}}}|Web.com Site Builder|'''Web.com Site Builder'''|[[Web.com_Site_Builder_via_WHMCS_MarketConnect|Web.com Site Builder]]}} {{!}} {{#ifeq:{{{type|}}}|Weebly|'''Weebly'''|[[Weebly_via_WHMCS_MarketConnect|Weebly]]}} {{!}} {{#ifeq:{{{type|}}}|NordVPN|'''NordVPN'''|[[NordVPN_via_WHMCS_MarketConnect|NordVPN]]}} {{!}} {{#ifeq:{{{type|}}}|XOVI NOW|'''XOVI NOW'''|[[XOVI_NOW_via_WHMCS_MarketConnect|XOVI NOW]]}} {{!}} {{#ifeq:{{{type|}}}|360 Monitoring|'''360 Monitoring'''|[[360_Monitoring_via_WHMCS_MarketConnect|360 Monitoring]]}}</div>
</includeonly><noinclude>
Add <nowiki>{{MarketConnect}}</nowiki> for a footer to your pages, produces:
{{MarketConnect}}
</noinclude>

Stripe

2023-08-29T11:57:22Z

John: /* Payment Workflow */

== About this Module ==

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system to submit credit card information to Stripe, which stores it remotely.

For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]].
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-warning">
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.
</div>
== Adding the Stripe Payment Gateway ==

[[File:stripe.png|thumb|Stripe Module Settings]]

To set up the Stripe payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Stripe'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Configure a display name. We recommend <tt>Credit Card</tt>.
# Go to the [https://dashboard.stripe.com/account/apikeys Stripe portal] and retrieve the publishable and secret API keys.
# Enter your Stripe API Keys. <div class="docs-alert-info"><i class="fa fa-info-circle"></i> To test Stripe, enter your [https://stripe.com/docs/keys#obtain-api-keys Stripe Test Mode API Keys].</div>
# Optionally, customize the '''Statement Descriptor Suffix''' with a maximum of 22 characters.
# In WHMCS 8.0 and later, leave the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' empty. WHMCS auto-generates these. See below for more information.
# Optionally, check '''Allow Payment Request Buttons'''. See below for more information.
# Click '''Save Changes'''.
# If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account's currency with a valid exchange rate at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. Stripe only returns transaction fees in the default currency for the Stripe account.

=== WebHook Endpoints ===

<div class="docs-alert-info">
You can use Stripe Webhooks in WHMCS v8.0 and above.
</div>

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click '''Save Changes''', WHMCS will use the '''Stripe Publishable API Key''' and '''Stripe Secret API Key''' to generate the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

* If you enter live API keys (<tt>sk_live</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret'''.
* If you enter test API keys (<tt>sk_test</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

WHMCS registers the WebHook Endpoints to deliver these events from Stripe:

* <tt>customer.source.updated</tt>
* <tt>customer.card.updated</tt>
* <tt>payment_method.updated</tt>

To change the WebHook ID, empty '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' and click '''Save Changes'''. WHMCS will auto-generate them again with new values.

=== Payment Request Button ===

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay). For customers who don’t use Apple Pay, '''Payment Request''' supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

==== Apple Pay ====

[[File:apple_pay_checkout.png|thumb|The Apple Pay Button on Checkout]]

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they're using Safari® on their iPhone® or iPad®, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac®, and have an iOS® device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, <tt><nowiki>whmcs.com</nowiki></tt>) and subdomains (for example, <tt><nowiki>shop.whmcs.com</nowiki></tt>).
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> An SSL certificate is '''required''' to use Apple Pay.</div>

To do this:

# Download this [https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association domain association file] and host it at <tt>/.well-known/apple-developer-merchantid-domain-association</tt> on your site. For example, if you're registering <tt><nowiki>https://example.com</nowiki></tt>, make that file available at <tt><nowiki>https://example.com/.well-known/apple-developer-merchantid-domain-association</nowiki></tt>.
# To instruct Stripe to register the domain with Apple, go to the '''[https://dashboard.stripe.com/account/apple_pay Apple Pay]''' tab in '''Account Settings''' in the Stripe Dashboard.

==== Google Pay ====

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

==== Microsoft Pay ====

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

==== Link ====
In WHMCS 8.8 and later, customers can pay using [https://stripe.com/en-ca/payments/link Link] for any Stripe transaction. Link makes payments easier by letting customers complete secure, one-click transactions using saved payment information. Stripe enables Link automatically.

For more information about disabling Link for your Stripe account, see [https://support.stripe.com/questions/how-to-turn-off-link How to Turn Off Link].

=== Test Mode ===

This module does not support test mode.

== Payment Workflow ==

[[File:stripe_checkout.png|thumb|The Stripe module on Checkout]]

The Stripe module supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

* In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorization is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.
* In WHMCS 8.8 and later, Stripe module transactions [https://support.stripe.com/questions/guide-for-indian-government-regulations-on-network-tokenization meet all Reserve Bank of India requirements].

<div class="docs-alert-info">
WHMCS 8.3 and higher includes support for disputes for Stripe and PayPal® transactions at '''Billing > [[Disputes]]'''.
</div>

===Recurring Payments===

Automated recurring payments use stored tokens. If a client card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

== Payment Gateway Balances ==

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At '''Billing > [[Transactions]]''', you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see [[Payment Gateway Balances and Transactions]].

This requires you to enable '''View Gateway Balances''' for the desired administrator role at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]'''.

<div class="docs-alert-warning">
In the Admin Area [[Admin_Dashboard|Dashboard]], you can view your Stripe balances through the '''Stripe Balance''' widget. However, this widget does not use the <tt>WHMCS\Module\Gateway\Balance</tt> and <tt>WHMCS\Module\Gateway\BalanceCollection</tt> classes to display balances. For more information, see [[Stripe Balance Widget]].
</div>

== Migrating to Stripe ==

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe's tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 8.0 to 8.6, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > Payment Gateways''' and choose '''All Payment Gateways'''.
# Activate the Stripe module.
# Click '''Deactivate''' for your previous merchant gateway provider.
# Select Stripe as the replacement gateway to switch users of the previous gateway module to.
# Click '''OK'''.

=== Migrating from a 3rd Party Stripe Module ===

The WHMCS Stripe module uses the Stripe <tt>cus_</tt> reference to capture payments (for example, <tt>cus_9MvIb7UlgJfJTn</tt>). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the <tt>cus_</tt> reference, navigate to a client that you know has an active Stripe token and click on one of the pay methods in the '''Summary''' tab of the client's profile. Verify that the listed token includes the <tt>cus_</tt> prefix.

To start using the WHMCS Stripe module:

# Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the <tt>tblpaymentgateways</tt> database table.
# Activate our official Stripe module.
# Deactivate the previous Stripe module.
# Check one of the Stripe pay methods on a client. If the token contains <tt>cus{_}</tt>, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing "example" with the name of the previous module: <source lang="sql">UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example'; </source>
# Remove any third-party files and template customisations for the previous Stripe module.

==Troubleshooting==

===Remote Transaction Failure. Please Contact Support===

This issue has multiple causes. This may also display as '''Error'''.

To resolve this issue:

# Go to '''Billing > Gateway Log'''.
# Check the '''Result''' and '''Debug Data''' columns for error messages or codes from the time of the payment attempt.
# Perform the appropriate steps in Stripe's [https://stripe.com/docs/error-codes Error Codes] and [https://stripe.com/docs/declines/codes Declines Codes] documentation.

See below for other common causes of this error:

====Payment Blocked By Stripe====

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

# Log in to your [https://dashboard.stripe.com/ Stripe Dashboard].
# Go to '''Developers > Logs'''.
# Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment was blocked (for example, with a '''The zip code you supplied failed validation''' error).
# Adjust the rules in your Stripe account for the error. For help, contact [https://support.stripe.com/ Stripe support].

====Customisations====

This issue may also present itself as '''"No Stripe Details Found for Update"''' in the '''Gateway Log'''.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, these issues may trigger this error:

* A hook file in <tt>/includes/hooks/stripe.php</tt>. Remove this file when switching to the WHMCS Stripe module.
* Template customisations in your active order form template files.
* The payment method is set to a module other than Stripe. In this case, perform one of the following actions:
** Change the client's '''Payment Method''' setting in the client's '''Profile''' tab to the Stripe module.
** Make Stripe the system default payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

====Out Of Date Template Files====

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The [[Release Notes]] for each version of WHMCS provide links to template changes.

====Network Analyser Tool====

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section '''Another Error Type''' in [https://help.whmcs.com/m/troubleshooting/l/1312423-an-error-occurred-while-communicating-with-the-server-please-try-again this help article]. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

===No Stripe Customer Details Found===
The system logs this error in the debug data section of '''Billing > [[Gateway Log]]'''. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the '''[[Pay Methods]]''' section of the client's '''[[Clients:Summary Tab|Summary]]''' tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe. This will create a payment method to use for future automatic payments.

==="You must provide a value for 'cvc'===

If you see at '''Billing > [[Gateway Log]]''' for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe.

For more information, see [https://stripe.com/docs/api?lang=python#create_card_token Stripe's documentation] (click '''show child parameters''').

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

===Network error [errno 35]: Unsupported SSL protocol version===
This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes. For more information, see [https://stripe.com/docs/security#tls Stripe TLS Documentation].

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

===You passed an empty string for 'statement_descriptor'===
This indicates an empty '''Statement Descriptor''' field in the payment gateway configuration. Make certain that you set your entire [[#Setup|gateway configuration]].

===Bad Request===
This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe. To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab (which may display a more-informative error to administrators). Then, add the payment method again.

Customised or outdated system themes or order form templates can also cause this error. To troubleshoot this:

# Go to the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Select ''Six'' or ''Twenty-One'' for '''System Theme'''.
# Go to the '''[[Ordering Tab|Ordering]]''' tab.
# Select a '''[[Standard_Order_Form_Templates|Default Order Form Template]]'''.
# Click '''Save Changes'''.
# Return to the Client Area and refresh the page.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

===An unexpected error - No Stripe Payment Method found from token===
This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

This can also be caused by a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.
* If one is, the custom JavaScript will need to be corrected.
* If the JavaScript error is coming from a third-party customisation, contact the developer for assistance.

If the issue persists, contact our [https://www.whmcs.com/submit-a-ticket/ support team].

===Error Updating Remote Pay Method: Remote Storage Failed===
You can find information about this error at '''Billing > [[Gateway Log]]'''.

===Stripe India Accounts===
India-based Stripe accounts require the following additional conditions for a successful payment capture:

* The client's address and billing contact must use a valid Indian postal address.
* The payment card must be from an Indian bank.
* The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies upon payment in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
# Add <tt>INR</tt> as an [[Currencies#Adding.2FEditing_a_Currency|additional currency]].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Set '''Convert To For Processing''' on the Stripe gateway to ''INR''.

For more information about the additional Stripe requirements for Indian Stripe accounts, see [https://support.stripe.com/questions/requirements-for-india-export-charges Stripe's documentation].

{{modules}}

Stripe

2023-08-29T11:54:41Z

John: /* Payment Request Button */

== About this Module ==

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system to submit credit card information to Stripe, which stores it remotely.

For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]].
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-warning">
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.
</div>
== Adding the Stripe Payment Gateway ==

[[File:stripe.png|thumb|Stripe Module Settings]]

To set up the Stripe payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Stripe'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Configure a display name. We recommend <tt>Credit Card</tt>.
# Go to the [https://dashboard.stripe.com/account/apikeys Stripe portal] and retrieve the publishable and secret API keys.
# Enter your Stripe API Keys. <div class="docs-alert-info"><i class="fa fa-info-circle"></i> To test Stripe, enter your [https://stripe.com/docs/keys#obtain-api-keys Stripe Test Mode API Keys].</div>
# Optionally, customize the '''Statement Descriptor Suffix''' with a maximum of 22 characters.
# In WHMCS 8.0 and later, leave the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' empty. WHMCS auto-generates these. See below for more information.
# Optionally, check '''Allow Payment Request Buttons'''. See below for more information.
# Click '''Save Changes'''.
# If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account's currency with a valid exchange rate at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. Stripe only returns transaction fees in the default currency for the Stripe account.

=== WebHook Endpoints ===

<div class="docs-alert-info">
You can use Stripe Webhooks in WHMCS v8.0 and above.
</div>

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click '''Save Changes''', WHMCS will use the '''Stripe Publishable API Key''' and '''Stripe Secret API Key''' to generate the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

* If you enter live API keys (<tt>sk_live</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret'''.
* If you enter test API keys (<tt>sk_test</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

WHMCS registers the WebHook Endpoints to deliver these events from Stripe:

* <tt>customer.source.updated</tt>
* <tt>customer.card.updated</tt>
* <tt>payment_method.updated</tt>

To change the WebHook ID, empty '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' and click '''Save Changes'''. WHMCS will auto-generate them again with new values.

=== Payment Request Button ===

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay). For customers who don’t use Apple Pay, '''Payment Request''' supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

==== Apple Pay ====

[[File:apple_pay_checkout.png|thumb|The Apple Pay Button on Checkout]]

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they're using Safari® on their iPhone® or iPad®, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac®, and have an iOS® device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, <tt><nowiki>whmcs.com</nowiki></tt>) and subdomains (for example, <tt><nowiki>shop.whmcs.com</nowiki></tt>).
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> An SSL certificate is '''required''' to use Apple Pay.</div>

To do this:

# Download this [https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association domain association file] and host it at <tt>/.well-known/apple-developer-merchantid-domain-association</tt> on your site. For example, if you're registering <tt><nowiki>https://example.com</nowiki></tt>, make that file available at <tt><nowiki>https://example.com/.well-known/apple-developer-merchantid-domain-association</nowiki></tt>.
# To instruct Stripe to register the domain with Apple, go to the '''[https://dashboard.stripe.com/account/apple_pay Apple Pay]''' tab in '''Account Settings''' in the Stripe Dashboard.

==== Google Pay ====

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

==== Microsoft Pay ====

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

==== Link ====
In WHMCS 8.8 and later, customers can pay using [https://stripe.com/en-ca/payments/link Link] for any Stripe transaction. Link makes payments easier by letting customers complete secure, one-click transactions using saved payment information. Stripe enables Link automatically.

For more information about disabling Link for your Stripe account, see [https://support.stripe.com/questions/how-to-turn-off-link How to Turn Off Link].

=== Test Mode ===

This module does not support test mode.

== Payment Workflow ==

[[File:stripe_checkout.png|thumb|The Stripe module on Checkout]]

The Stripe module supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area. In WHMCS 8.8 and later, customers can also pay using [https://stripe.com/en-ca/payments/link Link] for any Stripe transaction.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

* In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorization is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.
* In WHMCS 8.8 and later, Stripe module transactions [https://support.stripe.com/questions/guide-for-indian-government-regulations-on-network-tokenization meet all Reserve Bank of India requirements].

<div class="docs-alert-info">
WHMCS 8.3 and higher includes support for disputes for Stripe and PayPal® transactions at '''Billing > [[Disputes]]'''.
</div>

===Recurring Payments===

Automated recurring payments use stored tokens. If a client card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

== Payment Gateway Balances ==

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At '''Billing > [[Transactions]]''', you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see [[Payment Gateway Balances and Transactions]].

This requires you to enable '''View Gateway Balances''' for the desired administrator role at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]'''.

<div class="docs-alert-warning">
In the Admin Area [[Admin_Dashboard|Dashboard]], you can view your Stripe balances through the '''Stripe Balance''' widget. However, this widget does not use the <tt>WHMCS\Module\Gateway\Balance</tt> and <tt>WHMCS\Module\Gateway\BalanceCollection</tt> classes to display balances. For more information, see [[Stripe Balance Widget]].
</div>

== Migrating to Stripe ==

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe's tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 8.0 to 8.6, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > Payment Gateways''' and choose '''All Payment Gateways'''.
# Activate the Stripe module.
# Click '''Deactivate''' for your previous merchant gateway provider.
# Select Stripe as the replacement gateway to switch users of the previous gateway module to.
# Click '''OK'''.

=== Migrating from a 3rd Party Stripe Module ===

The WHMCS Stripe module uses the Stripe <tt>cus_</tt> reference to capture payments (for example, <tt>cus_9MvIb7UlgJfJTn</tt>). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the <tt>cus_</tt> reference, navigate to a client that you know has an active Stripe token and click on one of the pay methods in the '''Summary''' tab of the client's profile. Verify that the listed token includes the <tt>cus_</tt> prefix.

To start using the WHMCS Stripe module:

# Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the <tt>tblpaymentgateways</tt> database table.
# Activate our official Stripe module.
# Deactivate the previous Stripe module.
# Check one of the Stripe pay methods on a client. If the token contains <tt>cus{_}</tt>, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing "example" with the name of the previous module: <source lang="sql">UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example'; </source>
# Remove any third-party files and template customisations for the previous Stripe module.

==Troubleshooting==

===Remote Transaction Failure. Please Contact Support===

This issue has multiple causes. This may also display as '''Error'''.

To resolve this issue:

# Go to '''Billing > Gateway Log'''.
# Check the '''Result''' and '''Debug Data''' columns for error messages or codes from the time of the payment attempt.
# Perform the appropriate steps in Stripe's [https://stripe.com/docs/error-codes Error Codes] and [https://stripe.com/docs/declines/codes Declines Codes] documentation.

See below for other common causes of this error:

====Payment Blocked By Stripe====

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

# Log in to your [https://dashboard.stripe.com/ Stripe Dashboard].
# Go to '''Developers > Logs'''.
# Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment was blocked (for example, with a '''The zip code you supplied failed validation''' error).
# Adjust the rules in your Stripe account for the error. For help, contact [https://support.stripe.com/ Stripe support].

====Customisations====

This issue may also present itself as '''"No Stripe Details Found for Update"''' in the '''Gateway Log'''.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, these issues may trigger this error:

* A hook file in <tt>/includes/hooks/stripe.php</tt>. Remove this file when switching to the WHMCS Stripe module.
* Template customisations in your active order form template files.
* The payment method is set to a module other than Stripe. In this case, perform one of the following actions:
** Change the client's '''Payment Method''' setting in the client's '''Profile''' tab to the Stripe module.
** Make Stripe the system default payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

====Out Of Date Template Files====

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The [[Release Notes]] for each version of WHMCS provide links to template changes.

====Network Analyser Tool====

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section '''Another Error Type''' in [https://help.whmcs.com/m/troubleshooting/l/1312423-an-error-occurred-while-communicating-with-the-server-please-try-again this help article]. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

===No Stripe Customer Details Found===
The system logs this error in the debug data section of '''Billing > [[Gateway Log]]'''. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the '''[[Pay Methods]]''' section of the client's '''[[Clients:Summary Tab|Summary]]''' tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe. This will create a payment method to use for future automatic payments.

==="You must provide a value for 'cvc'===

If you see at '''Billing > [[Gateway Log]]''' for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe.

For more information, see [https://stripe.com/docs/api?lang=python#create_card_token Stripe's documentation] (click '''show child parameters''').

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

===Network error [errno 35]: Unsupported SSL protocol version===
This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes. For more information, see [https://stripe.com/docs/security#tls Stripe TLS Documentation].

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

===You passed an empty string for 'statement_descriptor'===
This indicates an empty '''Statement Descriptor''' field in the payment gateway configuration. Make certain that you set your entire [[#Setup|gateway configuration]].

===Bad Request===
This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe. To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab (which may display a more-informative error to administrators). Then, add the payment method again.

Customised or outdated system themes or order form templates can also cause this error. To troubleshoot this:

# Go to the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Select ''Six'' or ''Twenty-One'' for '''System Theme'''.
# Go to the '''[[Ordering Tab|Ordering]]''' tab.
# Select a '''[[Standard_Order_Form_Templates|Default Order Form Template]]'''.
# Click '''Save Changes'''.
# Return to the Client Area and refresh the page.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

===An unexpected error - No Stripe Payment Method found from token===
This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

This can also be caused by a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.
* If one is, the custom JavaScript will need to be corrected.
* If the JavaScript error is coming from a third-party customisation, contact the developer for assistance.

If the issue persists, contact our [https://www.whmcs.com/submit-a-ticket/ support team].

===Error Updating Remote Pay Method: Remote Storage Failed===
You can find information about this error at '''Billing > [[Gateway Log]]'''.

===Stripe India Accounts===
India-based Stripe accounts require the following additional conditions for a successful payment capture:

* The client's address and billing contact must use a valid Indian postal address.
* The payment card must be from an Indian bank.
* The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies upon payment in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
# Add <tt>INR</tt> as an [[Currencies#Adding.2FEditing_a_Currency|additional currency]].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Set '''Convert To For Processing''' on the Stripe gateway to ''INR''.

For more information about the additional Stripe requirements for Indian Stripe accounts, see [https://support.stripe.com/questions/requirements-for-india-export-charges Stripe's documentation].

{{modules}}

Products Management

2023-08-22T13:54:13Z

John: /* Invoicing Early */

WHMCS allows you to offer many different types of products and services, both with or without automation, and to create addons and other additional items to tailor those products and services to your clients' needs.

==Ordering Products and Services==

[[File:Admin-order-form.png|800px]]

To order new products and services for a client:

# Go to '''Orders > Add New Order''' or click '''Add New Order''' in the client profile.
# Begin entering the client details to select the client (if the system didn't already preselect them).
# Choose the payment method to use for the order and any resulting invoice.
# Select a promotion code to apply to the order items (if applicable).
# Choose the order status. Unless this is for adding an existing service that needs no provisioning, leave it as pending so that you can review the order after payment and ensure any provisioning was successful.
# Select one of the following options:
#*Order Confirmation — Keep this selected if you wish to send the Order Confirmation email to the client.
#*Generate Invoice — Keep this selected if you wish to generate an invoice for the items on the order. This is useful if you are placing an order for a new service on the client's behalf or you will to manually enter an existing service but still want to invoice them right away.
#*Send Email — Keep this selected if you wish to send the Invoice Created email whenever the system creates an invoice.
# Enter and select the details for each product you want to add to the order, including a domain name, billing cycle, quantity, and any pricing overrides.
#* Click '''Add New Product''' to add multiple products to the order.
#* If the billing cycle and price override fields have not changed, the system will use the pricing from the shortest configured billing cycle.
#* Use the '''Quantity''' option to order multiples of a single product that doesn't require any specific configuration on the initial order (such as a domain name and configurable options). For example, if you are selling a software license using our Licensing Addon and the customer wishes to receive 10 licenses, you could use 10 for the Quantity and the system will create 10 services on their account after order submission.
# Optionally, select and enter the appropriate details to add one or more domain names to the order.
#* Select ''None'' if this order doesn't require a domain,
#* For registration, the system will prompt you for the domain name, the number of years to register it for, any applicable addons, and finally any pricing overrides for the registration and future renewal amounts. If there isn't a price override, the system uses the regular price for that TLD.
#* For transfers, the system will prompt you for the same details, along with the EPP code (also commonly called the Transfer Authorization code) from the existing registrar for the domain. During the client area ordering process, the client supplies this, and you may need to obtain it from them first if it is applicable to the domain you are trying to transfer.
#* For '''Domain Only''' orders, you would not enter anything into the fields in the '''Product/Service''' section ('''Product/Service''', '''Domain''', '''Billing Cycle''', '''Quantity''', and '''Price Override''') and fill in the '''Domain Registration''' section.

<div class="docs-alert-info">
<span class="title">Premium Domains</span><br />
When ordering domains via the Admin Area, the system does not look up the domain's availability. WHMCS will therefore be unaware of whether it is a premium domain. For premium domains, [[Clients:Summary_Tab#Login_as_Owner|log in as the account owner]] and order them via the Client Area.
</div>

==Managing a Client's Products and Services==

You can manage a client's products and services in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client's profile. This tab allows you to view and modify all of a products settings. After making any changes, click '''Save Changes'''.

[[File:Module-commands.png|800px]]

If the product or service is linked to a module, the '''Module Commands''' actions display when you view that product or service for the client. This allows you to execute any of the commands available in that module.

Modules can have custom functions, but most use the same basic actions by default.

==Addons==

Product addons allow you to bill for additional items related to the main product but on independent billing cycles from the product (unlike Configurable Options, which have to bill on the same cycle).

You can create new addons or work with preconfigured addons at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Product Addons]]''' or, prior to WHMCS 8.0, '''Setup > Product Addons'''. Then, clients can order addons from the Client Area product details page or from your store.

[[File:Managing-addon.png|800px]]

After purchase, you can manage addons for individual purchased products in the client profile.
* To view the list of addons for a product, select the parent product from the menu.
* To edit an addon, click the edit icon for that addon in the '''Addons''' list.

===Adding Addons to Clients===

[[File:New-addon-button.png|800px]]

To add a new addon for a client:

# Click '''[[Clients:Products/Services Tab|Products/Services]]''' in the client profile.
# Click '''Click here to Manage''' for '''Addons'''.
# Click '''Add New Addon'''.
# If you are adding a predefined addon, select it and leave the name, price, and billing cycle empty.
# If you are adding a custom addon that will be specific to this client, set '''Predefined Addon''' to ''None'' and enter a custom name, price, and cycle.
# To delay generation of the invoice, uncheck the generate invoice checkbox.
# Click '''Save Changes''' to complete the process.

===Promotion Codes===

You can apply promotion codes to an existing service using the menu. For more information, see [[Promotions]].

===Auto Recalculate Recurring Price on Save===

Check this option to update the recurring amount field. You can use this after changing the product, configurable options, billing cycle, or promo code to auto calculate the new recurring price. We disable this by default to ensure that the system does not overwrite any discounted rates or custom pricing.

===Overide Auto Suspension===

This option can be used to allow extra time for payment to be made for specific individuals.

You can enable or disable this option from the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client profile.

== Early Renewals and Invoicing ==

In some circumstances, you may want to generate your customer's next invoice early, or they may wish to pay for their services in advance.

=== On-Demand Renewals ===

In WHMCS 8.8 and later, on-demand renewals allow your customers to renew their services early, before WHMCS has generated the next invoice, in the Client Area.

You can configure on-demand renewals globally and on a per-product basis. For more information, see [[On-Demand Renewals]].

=== Invoicing Early ===

Admins can generate invoices for services, domains, or addons with the ''Pending'', ''Active'', or ''Suspended'' statuses in advance from the client's profile's '''[[Clients:Summary_Tab#Invoice_Selected_Items|Summary]]''' tab.

==Upgrades/Downgrades==

===Admin Area===

[[File:Upgrade button.png|thumb|Upgrade/Downgrade Button]]

If you would like to change the product or service a client is assigned to and automatically charge or credit the difference for that change then you need to use the Upgrade/Downgrade process. You'll find the option for this next to the '''Products/Services''' menu in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab within the client profile.

To use it:
# Go to the product that you want to change.
# Perform the correct action for your WHMCS version:
#* For WHMCS 8.0 and later, click '''More''' and choose '''Upgrade/Downgrade'''.
#* For WHMCS 7.10 and earlier, go to the product you want to change, click '''Upgrade/Downgrade'''.
# Make the new product and billing cycle selections. A preview of what the charge will be for the remainder of the current cycle will display.
# Click '''Create Order'''. The system will create an order and invoice for the change.

<html><a href="http://www.youtube.com/watch?v=wXEulukuHdo" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

There will no immediate changes to the product after creating an upgrade order, the actual product or config option changes won't take effect until the invoice is paid. But as soon as the invoice is paid the product will be updated, the new recurring amount will be set, and with most supported control panels the upgrade is fully automated with the new package details/changes being passed over to the server module being used. Finally the upgrade email specified in the product configuration is sent to the user advising them of the new products details.

The same process can also be used for configurable options changes and billing the difference for those if the product contains them.

===Client Side===

Clients can also place orders for upgrades & downgrades themselves if you have permitted it in the product configuration. This allows clients to order upgrades/downgrades and complete them automatically without the need for any staff involvement.

For more information, including how to allow clients upgrades and how the system calculates upgrade charges, see [[Automated Upgrades and Downgrades]].

===Manual Upgrades===
There may be occasion when you wish to make an upgrade without placing an upgrade order (such as a free upgrade) or processing the upgrade before the client has paid for it.

To do this:

#Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab.
#Change the product in the menu.
#Check '''Auto Recalculate on Save'''.
#Click '''Save Changes'''.
#Click '''Change Package''' in the '''Module Commands''' section.

==Bulk Actions==

[[File:Bulk-actions.png|thumb|Bulk Actions Tool]]

The bulk actions option in WHMCS allows you to perform changes to two or more products inside a client's profile at the same time. The changes can consist of adjustments to the status, payment method, override auto-suspend date, first payment amount, recurring amount, next due date, and billing cycle. For example, you can use this option if you want to reduce a client's price on a number of separate products to the same level, execute module commands in bulk, or if you would like to bring multiple services in line to a matching due date.

To use this feature, from the client's '''[[Clients:Summary Tab|Summary]]''' tab, check the checkboxes next to the products, services, addons, or domains you want to update. The bulk actions will display under the item lists. Additional actions can be viewed by clicking '''Show Advanced Options'''. Enter any changes you wish to make (leaving blank any fields you don't want to change) and click '''Apply''' to complete the changes.

<html><a href="http://www.youtube.com/watch?v=WLLsQML6rEU" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

===Create Prorata Invoice===

When you change the Next Due Date of a product, service, addon, or domain, the system creates a pro-rated invoice that covers the period between the current next due date and the new one. This feature includes scenarios in which the various products have different next due dates to start with and will pro-rate each accordingly as separate line items on the invoice.

To use this, specify the new Next Due Date, check '''Create Prorata Invoice''', and then click '''Apply'''.

For example, the client could wish to pay for the following products on the 10th of the month going forward:

Product A - Next Due Date 01/01/2022 @ $30/month
Product B - Next Due Date 05/01/2022 @ $60/month

To do this, set the Next Due Date to 10/01/2022 and check the checkbox, an invoice with the following line items will be generated:

Product A (01/01/2022 - 09/01/2022) $8.00
Product B (05/01/2022 - 09/01/2022) $10.00
Total Due Today $18.00

Only once paid will the Next Due Dates for both products be updated and in future both products would be invoiced on the 10th January.

==Cancelling a Product/Service==

===Auto Terminate/Fixed Term===
You can setup products to automatically terminate after a set number of days from the date of signup. For more information refer to [[Products_and_Services#Pricing_Tab|Configuring Products/Services]].

===Clients Self Service===
[[File:Request-cancellation-form.png|800px]]

WHMCS can completely automate the process of product cancellation or wait for manual confirmation. To do this navigate to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings''', and enable the '''Show Cancellation Link''' option.

Clients can then request cancellation of any of their products & services directly from the client area.

To fully automate cancellation and have the module terminate command run (for example to remove the hosting account from the server) check '''Cancellation Requests''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' option.

Now when the cron runs any services with a cancellation request due today will be removed from the server and the status changed in WHMCS to Cancelled. The process runs as follows:

*Client clicks ''Request Cancellation'' button on the product details page in client area
*They're prompted to provide a cancellation reason and provided 2 choices for the cancellation - either '''Instant''' (on next cron run) or at the '''End of the Current Billing Cycle'''.
*If a matching domain exists under the client's account in active status with ''Auto Renew'' enabled, the customer is given the option to disable auto renew too - thereby leaving the domain to expire.
*Any unpaid invoices for the product will be cancelled ([[Invoice_Tab#Cancellation_Request_Handling|if enabled]])
*A notification email is sent to administrators and you will be able to review the reason provided in '''Clients > Cancellation Requests'''.

====Manual Cancellation====
If the Cancellation Request setting is '''not''' enabled then at this point you must navigate to the cancellation requests page, click through to the service page and click the '''Terminate''' module command button to remove the account from the server. The cancellation request is then moved from the ''Open Requests'' page to ''Completed Requests''.

====Automated Cancellation====
If the Cancellation Request setting '''is''' enabled the cancellation request will be actioned when the daily automation cron runs on the appropriate day. For example if the ''Immediate'' option was selected it will be terminated on the next cron run, if ''End of Billing Period'' was selected it will be terminated when the cron runs on the service's Next Due Date.

====Voiding Cancellation Requests====
If a Cancellation Request has been submitted by your client and they later change their mind, it is quick and easy to void their cancellation request. Simply navigate to '''Clients > Cancellation Requests''', locate the cancellation you wish to remove, and then click the red X next to the request to remove it. This will stop the cancellation from processing automatically. You'll need to make sure to mark any invoices that were cancelled as "Unpaid" to prevent billing errors.

===Admin Scheduled Cancellations===

As an admin user, you can schedule the termination of a product at the end of the currently active period by going to the Products/Services tab, checking the '''Auto-Terminate End of Cycle''' option and optionally entering a reason/note for it. Any unpaid invoices for the product will be cancelled and will suppress any further renewal invoices from generating for this product and terminate it when the next due date is reached.
The "Cancellation Requests" setting in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' must also be enabled.

===Admin Immediate Cancellation===

Finally, if you want to cancel or terminate a product or service immediately then you simply need to locate the item you wish to cancel, and from the Products/Services page, click the '''Terminate''' button if the product is linked to a module or if not, manually change the dropdown status from Active to '''Cancelled'''. Once you've done this, no further invoices will generate for the item.

===Addons===
When a product or service is terminated automatically by the WHMCS System, including through the above Admin Scheduled Cancellation routine, any child addon(s) attached to the product/service will also be cancelled at the same time. Addons do not support independent scheduled cancellations of their own however.

====Termination Date====
When an addon is Cancelled or Terminated, either manually via the admin interface or automatically as part of a product termination, the Termination Date will be assigned the current date automatically.
The termination date can be edited manually at any time via the Product Addon management screens within the admin area.
<div class="docs-alert-info">A termination date can only be set/edited when the addon is in one of either Terminated or Cancelled status.</div>

==Moving a Product/Service to another Client==
[[File:Transfer product.png|thumb|Transfer Product Popup]]
#From the Products/Services details page of the product you want to move, click '''Move Product/Service to Another Client''' located at the top-right of the page
#A popup box will appear (you will need popup blockers disabled to use this)
#In the popup enter the ID of the new owner. If you don't know the client's ID the Search field can be used to search by name, company or email address. Click the client's name and the ID will be filled in.
#After selecting the desired click, click the '''Transfer''' button
#The item will then be transferred, the window will close, and the original window will refresh to show the product under its new owner.

'''N.B.''' Moving a products/service between clients within WHMCS will not have any affect on the account on the server.

===Invoices===
Invoices cannot be moved between clients, therefore when moving a product/service any invoices will remain under the old owner. Therefore it would be advisable to check the old owner's Invoices tab for any unpaid invoices for this service and cancel them. If you wish to invoice the new owner for the service, move the Next Due Date forward/back by one day and a new invoice will be generated when the cron next runs.

==Deleting a Product/Service from a Client==

#From the Products/Services details page of the product you want to delete, click '''More''' and then click '''Delete'''.
#After clicking this link, you will be asked to confirm if you are sure you want to delete the item.
#If you click No you will be returned to the page, if you click Yes, the item will be deleted and you will be taken to the next product/service under that client.

'''Note:''' Deleting a product from WHMCS will not terminate it on the server. If you wanted to remove it from the server aswell, you need to run the Terminate Module Command as explained above before deleting the record from WHMCS.

==Resending Product Welcome Email==
To re-send a product welcome email simply navigate to the client's Products/Services tab and click the "Resend Product Welcome Email" button at the bottom of the page.

Clients:Summary Tab

2023-08-08T13:55:43Z

John: /* Invoices/Billing */ Corrected typo

{{Client Management}}

The '''Summary''' tab contains an overview of the client's details, billing and service statistics, quick links to many common management actions, and a list of all their services, domains, and addons.

You can access this tab when you view a client's profile at '''Clients > [[Client Management|View/Search Clients]]'''.

[[File:82ClientSummary.png|thumb|Client Summary Tab]]

==Summary Actions==

The top-left corner of the page displays the client's unique ID number and name. To the right, summary actions allow you to manage billing-related settings.

Click the click '''Yes''' (green) or '''No''' (red) to instantly toggle the status of these options:

* '''Exempt From Tax''' — Do not charge tax, even if the client has a tax rule.
* '''Auto CC Processing''' — Automatically charge the client's stored credit card on invoice due dates.
* '''Send Overdue Reminders''' — Send overdue reminder emails when the client's invoices become overdue.
* '''Apply Late Fees''' — Charge a late fee when the client's invoices become overdue. <div class="docs-alert-warning"><span class="title">Late Fees</span><br/>You must activate and configure late fees in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' and in the '''[[Invoice Tab|Invoice]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.</div>

==Client's Information==

This section displays the client's contact information and the '''Reset & Send Password''' and '''Login as Owner''' links.

=== Phone Numbers ===

In WHMCS 7.4 and later, you can easily enter and store international phone numbers.

[[File:PhoneNumberInputUx.png|500px]]

This system ensures a consistent and uniform phone number format combining the country prefix and phone number:

+ '''[Country Code]''' . '''[Phone Number]'''

In WHMCS 7.4 and later, this feature is enabled by default. The system will save the client's phone number in the database and automatically prefix it with the international country dialing code.

To disable this, uncheck '''Phone Numbers''' in the '''[[Localisation Tab|Localisation]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. When you disable this feature, the system will not add the prefix in the database but will display it in the Admin Area and Client Area.

====Automatic Number Formatting====

The pre-selected country will default to your WHMCS system default country. The system will update the selected country whenever you change the client's physical address. This change will occur even if the phone number is currently empty.

Users can also begin typing a phone number that begins with a country code in the format <tt>+XX</tt> and the system will update the country.

The update process will automatically convert existing client phone numbers when they display in a phone number field. The phone number value will update in the database the first time that an admin or client saves the phone number.

====Order Forms====

For example:

[[File:PhoneNumberOrderForm.png|500px]]

===Reset & Send Password===

Click to generate a new Client Area password for the client and email it to them.

Clients can also request a password reset by clicking '''Forgotten Password''' on the login form. After entering their email address, if there is a set security question and answer, the system will prompt them to supply the answer. Then, they will receive an email with a confirmation link, to ensure that they are the person who requested the password reset. The link is valid for two hours from the time of request.

* If there is not a set security question and answer, the system sends the email immediately when the client enters their email address.
* When they click the link in the email, clients will go to the password reset validation page, from which they can set a new password. They can then log in immediately using the new password. If the client didn't request the reset, they can ignore the email.

<div class="docs-alert-warning">
<span class="title">WHMCS 8.0 and later</span><br />
To reset the user's password in WHMCS 8.0 and later, use the client profile '''[[Clients:Users_Tab#Password_Reset|Users]]''' tab.
</div>

===Login as Owner===

Click to view the Client Area exactly as the account's owner would see it. Clicking the linked text will open the Client Area in your current tab, or you can click the window icon to open the Client Area in a new tab.

When you access the Client Area in this way, you can also perform actions on the account owner's behalf, like placing orders or opening tickets. When you are finished, click '''Return to Admin Area''' in the top-right corner to return to the Admin Area.

<div class="docs-alert-warning">
Prior to WHMCS 8.0, this was '''Login as Client'''.
</div>

==Contacts/Sub-Accounts==

This section lists the client's contacts or sub-accounts. Click a name to edit that record in the '''[[Clients:Contacts_Tab|Contacts]]''' tab.

===Add Contact===

Click to create a new contact or sub-account for this client.

==Pay Methods==

Displays an overview of the client's current registered payment methods in WHMCS.

The default Pay Method will always be displayed at the top of the list, and be indicated via an icon.

===Adding a Pay Method===

You can add a new payment method by clicking '''Add Credit Card''' or '''Add Bank Account'''. These links are only available when there is an appropriate activated module.

<div class="docs-alert-info">
These options will only display if you have activated an appropriate [[Payment Gateways|payment gateway]]. If you do not have either an active merchant gateway and/or bank account module, then no options to add payment methods will be displayed.
</div>

When multiple payment gateways are active, and include a combination of both local card storage and tokenized payment gateway modules, upon selecting to add a credit card, you will be prompted for the storage method you wish to use. Essentially, you need to tell WHMCS if the card should be tokenized with your desired payment gateway, or stored locally and encrypted in the database. In most cases if you have a tokenization payment gateway in use, you will probably want to use this.

===Managing Pay Methods===

You can manage a pay method by clicking on it in the list.

====View Locally-Stored Credit Card Numbers====

To view the associated locally-stored credit card number (local encryption), click the lock icon and enter your Credit Card Encryption hash (in <tt>configuration.php</tt>).

For tokenisation gateways, viewing the full card number is not possible because WHMCS does not store the details. You can only view the respective token and the last four digits of the card number.

====Removing Card Details====

Click '''Delete''' to remove the card's details from the client and WHMCS.

If an error occurs deleting a remote [[Pay Methods|payment method]], or if the gateway that a remote payment method is associated with has been deactivated, WHMCS will be unable to delete the record. When this happens, a message will be shown displaying the error that occurred and providing an option to ignore and force delete the payment method.
[[File:PayMethodDeleteFail.png]]

Forcibly deleting a payment method will not run anything on the remote gateway system. Manual removal of any records in a gateway account would need to be done manually if required, when force deleting from WHMCS.

==Invoices/Billing==

In this section quick invoice and billing statistics are displayed; the number of invoices in each status along with the total value of each in brackets.

In the Income sub-section, the statistics are calculated as follows:

* Gross Revenue statistic shows the total of all transactions paid by the client
* Client Expenses is the sum of transaction fees and refunded transactions
* Net Income is the Gross Revenue - Client Expenses
* Credit Balance shows the current amount of credit available to the client to spend

===Create Invoice===

Click '''Create Invoice''' to create a custom invoice. This immediately creates an empty invoice that you can add line items to. Clicking will not send an email to the client.

For steps for the remaining process of adding a custom invoice, see [[Invoicing]].

===Create Add Funds Invoice===

You can create invoices in this way to allow a client to deposit funds to their account, or to charge a specific amount from a clients credit card. A popup will appear allowing the amount of credit to be specified. The customer will receive an email for the invoice that the system generated with a link to pay it.

For more information, see [[Add Funds]] and [[Invoicing]].

===Generate Due Invoices===

Click here to generate any invoices due for the client's services, billable items, domains or addons. Useful if one of the aforementioned items has been modified and a new invoices needs to be generated without the need to run the entire automation cron job. A popup will appear asking whether you wish to send the invoice notification email.

===Add Billable Item===

This link will take you directly to the Add Billable Item interface. For more information, see [[Billable Items]].

===Manage Credits===

Displays a popup displaying the client's credit history; how credits were earned and spent. Credit can also be manually added and removed using the appropriate buttons. You also have the option to delete entries if you wish and they will then be deducted from the credit balance.

For more information, see [[Transactions#Managing_Credit|Managing Credit]].

==Create New Quote==

This link will take you directly to the Quote creation interface. For more information, see [[Quotes]].

==Other Information==

In this section, miscellaneous information is displayed; the client's status, their client group, signup date, length of time since signup and the IP address, hostname, and time of their last login.

==Products/Services==

In this section the numbers all the services, domains quotes, support tickets and affiliate signups for this client are displayed. The active service count is displayed first, with the total - including services in suspended, terminated and cancelled statuses - in brackets.

===View Orders===

Click this link to see a list of all orders placed by this client. For more information, see [[Order Management]].

===Add New Order===

This link will take you to the admin order form. This allows orders to be placed on behalf of the client, and for products and promotional codes to be used in combinations not possible on the public order form.

==Files==

The files section in a client's summary allows you to upload files specific to that customer.

* This can be used for documents, agreements or other downloads specific to the individual
* Files can be set as Admin Only to only be viewed by admins, otherwise they show on the Client Area homepage for the client to be able to download
* Files are uploaded to the /attachments directory and can be added and managed from the client profile '''[[Clients:Summary Tab|Summary]]''' tab in the Admin Area.

==Recent Emails==

Displayed here are the last five emails sent to the client by WHMCS. You can view a longer email history in the client profile '''[[Clients:Emails Tab|Emails]]''' tab.

==Other Actions==

Within this section are a number of miscellaneous links which perform a variety of tasks.

===View Account Statement===

This displays a statement of account for this client accounts between a date range. It includes the type (add funds, transaction, invoice), date, description, credits, debits, and a running balance.

===Open New Support Ticket===

This link enables you to open a support ticket under the client's account. This is useful for initiating correspondence with the client and keeping a full record of the conversation.

===View all Support Tickets===

Click here to see see a list of all support tickets assigned to the client in the departments to which your administrator account is assigned. If the client had tickets in departments of which you are not a member, they would not be displayed here.

===Activate as Affiliate===

If enabled clients can join the affiliate program from within the client area. Staff members can also add the client to the affiliate program by clicking this link.

===View Affiliate Details===

Once the client has been activated as an affiliate, the 'View Affiliate Details' link will be displayed in its place. Click it to see the client's referrals, commissions pending and paid, as well as your payments to them. For more information, see [[Affiliates]].

===Merge Client Accounts===

Merging clients combines two separate client accounts in WHMCS into one. This merges everything relating to the two separate entities into one including but not limited to products, invoices, transactions, or tickets.

[[File:Merge clients.png|thumb|Merge Clients Popup]]

To do this:

# Go to the client profile for the first client that you want to merge.
# Click '''Merge Client Accounts'''.
# Enter the other client's client ID. If you don't know the client's ID, enter their name, company or email address in the '''Search''' field. Click the client's name and the system will automatically fill in the ID.
# Choose which profile you want to keep (the client you want to merge the other client's data into).
# Click '''Submit'''.

===Close Clients Account===

Closing a client's account will prevent them from being able to log in to the client area. This link will also change the status of unpaid invoices to cancelled, and all services to cancelled. It will not run any module termination functions.

===Delete Clients Account===

To remove a client, click this link. If you also want to remove any associated users that aren't associated with other client accounts, check the checkbox. Then, confirm the deletion. The client will be removed and you will be returned to the '''Clients''' list.

Deleting a client removes everything related to that client from the WHMCS database, with the exception of transactions. This is because transactions are considered income that isn't being refunded when the client is removed. If you want to also remove the client's transactions, do this in the '''[[Clients:Transactions Tab|Transactions]]''' tab before you delete the client.

===Export Client Data===

Click to go to the '''Client Data Export''' report at '''Reports > More...'''. The system will preselect the current client. From this report, you can download selected client data as a <tt>.json</tt> file.

For more information, see [[Reports#Client|Reports]].

==Send Email==

Use this menu to send email to clients. You can send '''General''' email templates or compose custom messages for the individual client.

To send a client-related email message using an existing email template, select that template from '''Send Email''' and click '''Send'''.

For custom emails:

# Select '''New Message''' from '''Send Email'''.
# Click '''Send'''.
# Compose your message.
# If you want to use the message again in the future, check '''Save Message'''.
# Click '''Send Message'''.

For more information, see [[Messages/Emails]].

==Admin Notes==

Here staff can enter private notes about the client.

Separate notes sections are available under the '''[[Clients:Products/Services Tab|Products/Services]]''', '''[[Clients:Domains Tab|Domains]]''', and '''[[Clients:Notes Tab|Notes]]''' tabs.

==Filtering Products==

[[File:filtering_products.png|thumb|Product Filtering]]

There may be situations in which it's desirable to filter the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab to only display items in certain statuses. For example, if a client has a large number of old cancelled services, you may wish to only display the active, pending, and fraudulent products, hiding the cancelled ones.

To do this, click '''Status Filter''' under the '''Admin Notes''' section. A prompt will appear allowing you to select which statuses to display.

* After the filter is applied, the button will be green.
* This filter will apply across all clients until you close the browser.

==Services, Addon, Domains, Quotes==

The '''Services''', '''Addons''', '''Domains''', and '''Quotes''' lists provide a comprehensive list of all the client's services and include information like the price, signup date, status, and next due date.

The lists are ordered based upon the item's ID number. Click the ID number of the '''Edit icon''' to see the full details of the item from where you can make changes.

The '''Current Quotes''' section displays quotes with a '''Valid Until Date''' up to and including today's date. After this date, you can view them in the '''[[Clients:Quotes_Tab|Quotes]]''' tab.

==Mass Updating Services/Addons/Domains==

[[File:Bulk_actions_panel.png|thumb|Mass Update Panel]]

The mass update options enable you to make changes to more than one of a given clients products, add-ons and domains at a time. This is useful for making bulk changes to a clients products and services.

Supported fields you can change in a mass update include:

* Status
* Payment Method
* Override Auto-Suspend
* Pricing
* Billing Cycle
* Next Due Date

You can also perform all the core module commands:

* '''Create'''
* '''Suspend'''
* '''Unsuspend'''
* '''Terminate'''
* '''Change Package'''
* '''Change Password'''

To use the feature, follow the steps below:

# Check the checkboxes next to the products, services, addons, and domains you want to update.
# Under '''Bulk Actions''', click '''Advanced Options'''.
# Make your changes and selections. Leave any fields that you don't wish to change blank.
# Click '''Apply'''.

===Due Date Changes Prorata Calculation===

When making a change to the '''Next Due Date''' of products and services, you also have the option to bill for the days between the current next due date and the target next due date you set. This is useful for synchronising multiple different products to a single common due date each billing cycle.

To do this, follow the steps below:

# Check the checkboxes next to the products, services, addons, and domains you want to update.
# Under '''Bulk Actions''', click '''Advanced Options'''.
# Enter the desired '''Next Due Date'''.
# Check '''Create Prorata Invoice'''.
# Click '''Apply'''.

The page will reload with confirmation of the changes and that an invoice has been generated.

<div class="docs-alert-info">
An invoice will only be generated if the differences for all products result in an amount being due. If the total differences result in a credit then no invoice will be generated and no credit will be issued.

To add a credit for the difference, see [[Credit/Prefunding#Adding_Credit_to_a_Client|Credit/Prefunding]].
</div>

==Invoice Selected Items==

<div class="docs-alert-info">
In WHMCS 8.8 and later, you can enable and configure on-demand renewals to allow customers to renew services early, before invoice generation, from within the Client Area. For more information, see [[On-Demand Renewals]].
</div>

There may be times where a client asks for you to invoice them for the next renewal date early. To do this, check the checkboxes for the desired products, services, addons, and domains and then click '''Invoice Selected Items'''.

* This may create multiple invoices if the due dates and payment methods differ. This is because this process continues to obey the usual invoicing rules.
* You cannot generate another invoice if an invoice has already been made for the next due date.

If you select multiple items with the same '''Next Due Date''' and '''Separate Invoices''' is enabled in the client's profile or [[Client Groups|client group]], it will not apply and all possible items will be invoiced together. To split them, edit the resulting invoices and use the '''Split Invoice''' function.

==Delete Selected Items==

Check the checkboxes next to the services, domains, addons, or quotes that you wish to remove and click '''Delete Selected Items''' to delete multiple items at the same time.

This will remove the record from WHMCS but will not trigger any module commands (for example, the hosting account for a service will stay on the server).

Long Term Support

2023-06-19T17:59:36Z

John: /* WHMCS Version & LTS Schedule */

== WHMCS Long-Term Support ==

Product enhancements, bug fixes and security fixes for published versions of WHMCS are common; WHMCS is constantly being refined to ensure a safe and robust experience. However, it is impractical for customers to always track the latest product refinements at the same pace as our Development Team. And for that reason, WHMCS has implemented a Long-Term Support Policy for WHMCS.

=== Overview ===
The WHMCS Long-Term Support Policy provides customers with a clear understanding of our commitment to supporting the software they have purchased a license for and installed on their systems.

WHMCS will provide periodic maintenance releases for major and minor versions of WHMCS as part of the normal WHMCS Release Process. This is called [[#Active Development | Active Development]]. Versions of WHMCS that are not under Active Development will not receive maintenance releases, however, they are candidates for Targeted Critical and Security Releases. WHMCS will only provide Targeted Releases for candidates that have not reached their [[#Defining End Of Life | End Of Life]].

Please refer to the [[#WHMCS Version & LTS Schedule|WHMCS Version and LTS Schedule]] to see what versions of WHMCS are currently covered by Long-Term Support or under Active Development.

=== Provisions of Long-Term Support ===
Once a version of WHMCS is no longer being actively developed it will receive Long-Term Support (LTS) from our Development and Security Teams. LTS is a finite period which expires on a specific date known as End Of Life (EOL). Each minor version has it's own EOL date.

Product versions that are in LTS are provided Targeted Critical and Security Releases.

Once a version has moved from Active Development to LTS it will not receive product enhancements or maintenance fixes unless they are deemed critical to the viability of a Targeted Critical or Security Release, and therefore delivered as part of LTS. If you require product enhancements or maintenance fixes, we suggest updating to a product version that is being actively developed.

=== Active Development ===
A product version that is under Active Development is in the process of being refined. Therefore, subsequent revisions are likely to be released until a new minor version is published. Revision releases can include bug fixes, security enhancements, minor optimizations, third-party updates, as well as Important or Critical updates.

At any given moment in time, there will likely be only one actively developed version of WHMCS available; it will be the latest version available for our site. However, to ensure a smooth transition from one major or minor version to the next, WHMCS may extend Active Development of the previously published version. These overlaps between product versions is usually quite small, on the order of a few weeks at most.

Please refer to [[#WHMCS Version & LTS Schedule|WHMCS Version and LTS Schedule]] to know if your version is currently under Active Development.

=== Defining End Of Life ===
A core attribute of the Long-Term Support Policy is defining a given version's End Of Life (EOL) date. The EOL date is established upon the publication of a new minor or major release and typically is set one year into the future.

For example if version 1.0.0 is published January 31, 2012, then it will have an EOL of January 1st 2013 because it is a major release. If 1.1.0 is published on May 1st, 2012, it will have an EOL of May 1st 2013 because it is a minor release. If 1.1.1 is published on May 15th 2012 it will have an EOL of May 1st 2013 because it is a maintenance release to a previous minor release. Likewise, if 1.1.5 is published on July 24th 2012 it will have an EOL of May 1st 2013 because it is a maintenance release to a previous minor release.

=== After End Of Life ===
Once a version's EOL date has passed, no further releases or updates will be provided, regardless of the observed deficiency in that version.

Products that have reached EOL are not available for download from WHMCS.

As noted below in [[#Licensing & Services | Licensing & Services]], the product will continue to function even after the EOL date has passed. The use of the software is not tied to LTS or EOL, but the active/inactive state of your license.

=== Licensing & Services ===
WHMCS has historically offered with two types of licenses: Monthly and Owned. Whilst all new sales are of the Monthly type, this document also describes how the policy applies to [[Renewing Support and Updates|grandfathered Owned licenses]]. Each license type is bundled with [[#Help Desk Support | help desk support]] and access to [[#Software Update Service | software updates]] when initially purchased.

A Monthly license always has access to these two services. An Owned license has access to these two services for one year. After one year, an Owned license holder can purchase an additional year of these two services as an addon.

An Owned license validates use of the software indefinitely, even after the term of help desk support and access to software updates expires. A Monthly license validates use of the software, help desk support, and access to software updates in one month durations. The active status of your license governs the functional state of your WHMCS installation, not the development status (Active Development/LTS/EOL) of the deployed product version.

==== Help Desk Support ====
The help desk support service allows customers to open tickets with our help desk. These tickets are managed by our Technical Analysts. Our Analysts work with customers to resolve a broad range of issues from configuration to identifying deficiency within a given version of WHMCS. With this service, customers have access to Analysts regardless of which version of the product they are using, even if that version has reached its End Of Life.

It's important to remember, however, that support provided by this service, or deficiencies identified by our Analysts, does not imply future refinements for versions. The [[#WHMCS Version & LTS Schedule|LTS schedule]], along with the severity of the identified issue, will determine what versions of WHMCS are candidates for any future refines.

==== Software Update Service ====
The software update service allows customers access to the latest versions of WHMCS. The service does not imply continued development, maintenance, or critical fixes for any given version of WHMCS. The [[#WHMCS Version & LTS Schedule|LTS schedule]] will determine what versions of WHMCS are candidates for any refinements. It is recommended that customers leverage this service and keep their WHMCS installation up to date, and optimally, tracking a version that is currently under [[#Active Development | Active Development]].

=== Grandfathered LTS ===
The WHMCS Long-Term Support policy is effective May 1st, 2013. Particular versions have been grandfathered, namely 4.5, 5.0, and 5.1.

=== WHMCS Version & LTS Schedule ===
This chart is updated upon each major or minor release of WHMCS.

{| class="table table-striped"
! WHMCS Version
! Approximate Publication Date
! Targeted End-Of-Life Date
! Current Status
|-
| 8.7 || December 2022 || February 29th, 2024 || style="background: #81D153; font-weight: bold;" | [[#Active Development | <span style="color:#333">Active Development</span>]]
|-
| 8.6 || September 2022 || October 31st, 2023 || style="background: #FFCCCC; font-weight: bold;" | LTS
|-
| 8.5 || April 2022 || May 31st, 2023 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.4 || December 2021 || January 31st, 2023 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.3 || September 2021 || October 31st, 2022 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.2 || May 2021 || June 30th, 2022 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.1 || November 2020 || December 31st, 2021 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.0 || August 2020 || September 30th, 2021 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 7.10 || April 2020|| April 30th, 2021 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 7.9 || November 2019 || December 31st, 2020 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 7.8 || August 2019 || August 31st, 2020 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.7 || January 2019 || January 31st, 2020 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.6 || June 2018 || July 31st, 2019 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.5 || April 2018 || April 30th, 2019 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.4 || November 2017 || November 30th, 2018 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.3 || October 2017 || October 31st, 2018 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.2 || May 2017 || May 31st, 2018 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.1 || December 2016 || December 31, 2017 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.0 || October 2016 || October 31, 2017 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.3 || March 2016 || March 31, 2017 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.2 || December 2015 || December 31, 2016 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.1 || September 2015 || September 30, 2016 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.0 || July 2015 || July 31, 2016 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.3 || September 2013 || October 31, 2015 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.2 || March 2013 || March 31, 2014 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.1 || July 2012 || November 30, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.0 || December 2011 || July 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.5 || April 2011 || June 30, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.4 || December 2010 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.3 || September 2010 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.2 || March 2010 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.1 || November 2009 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.0 || May 2009 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 1.x-3.x || -- || -- || style="background: #84807F; font-weight: bold; font-style: bold;color: black" | EOL
|}

''Last Updated: {{REVISIONDAY2: Long_Term_Support }}/{{REVISIONMONTH: Long_Term_Support }}/{{REVISIONYEAR: Long_Term_Support }}

Products Management

2023-05-30T21:58:21Z

John: /* Addons */

WHMCS allows you to offer many different types of products and services, both with or without automation, and to create addons and other additional items to tailor those products and services to your clients' needs.

==Ordering Products and Services==

[[File:Admin-order-form.png|800px]]

To order new products and services for a client:

# Go to '''Orders > Add New Order''' or click '''Add New Order''' in the client profile.
# Begin entering the client details to select the client (if the system didn't already preselect them).
# Choose the payment method to use for the order and any resulting invoice.
# Select a promotion code to apply to the order items (if applicable).
# Choose the order status. Unless this is for adding an existing service that needs no provisioning, leave it as pending so that you can review the order after payment and ensure any provisioning was successful.
# Select one of the following options:
#*Order Confirmation — Keep this selected if you wish to send the Order Confirmation email to the client.
#*Generate Invoice — Keep this selected if you wish to generate an invoice for the items on the order. This is useful if you are placing an order for a new service on the client's behalf or you will to manually enter an existing service but still want to invoice them right away.
#*Send Email — Keep this selected if you wish to send the Invoice Created email whenever the system creates an invoice.
# Enter and select the details for each product you want to add to the order, including a domain name, billing cycle, quantity, and any pricing overrides.
#* Click '''Add New Product''' to add multiple products to the order.
#* If the billing cycle and price override fields have not changed, the system will use the pricing from the shortest configured billing cycle.
#* Use the '''Quantity''' option to order multiples of a single product that doesn't require any specific configuration on the initial order (such as a domain name and configurable options). For example, if you are selling a software license using our Licensing Addon and the customer wishes to receive 10 licenses, you could use 10 for the Quantity and the system will create 10 services on their account after order submission.
# Optionally, select and enter the appropriate details to add one or more domain names to the order.
#* Select ''None'' if this order doesn't require a domain,
#* For registration, the system will prompt you for the domain name, the number of years to register it for, any applicable addons, and finally any pricing overrides for the registration and future renewal amounts. If there isn't a price override, the system uses the regular price for that TLD.
#* For transfers, the system will prompt you for the same details, along with the EPP code (also commonly called the Transfer Authorization code) from the existing registrar for the domain. During the client area ordering process, the client supplies this, and you may need to obtain it from them first if it is applicable to the domain you are trying to transfer.
#* For '''Domain Only''' orders, you would not enter anything into the fields in the '''Product/Service''' section ('''Product/Service''', '''Domain''', '''Billing Cycle''', '''Quantity''', and '''Price Override''') and fill in the '''Domain Registration''' section.

<div class="docs-alert-info">
<span class="title">Premium Domains</span><br />
When ordering domains via the Admin Area, the system does not look up the domain's availability. WHMCS will therefore be unaware of whether it is a premium domain. For premium domains, [[Clients:Summary_Tab#Login_as_Owner|log in as the account owner]] and order them via the Client Area.
</div>

==Managing a Client's Products and Services==

You can manage a client's products and services in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client's profile. This tab allows you to view and modify all of a products settings. After making any changes, click '''Save Changes'''.

[[File:Module-commands.png|800px]]

If the product or service is linked to a module, the '''Module Commands''' actions display when you view that product or service for the client. This allows you to execute any of the commands available in that module.

Modules can have custom functions, but most use the same basic actions by default.

==Addons==

Product addons allow you to bill for additional items related to the main product but on independent billing cycles from the product (unlike Configurable Options, which have to bill on the same cycle).

You can create new addons or work with preconfigured addons at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Product Addons]]''' or, prior to WHMCS 8.0, '''Setup > Product Addons'''. Then, clients can order addons from the Client Area product details page or from your store.

[[File:Managing-addon.png|800px]]

After purchase, you can manage addons for individual purchased products in the client profile.
* To view the list of addons for a product, select the parent product from the menu.
* To edit an addon, click the edit icon for that addon in the '''Addons''' list.

===Adding Addons to Clients===

[[File:New-addon-button.png|800px]]

To add a new addon for a client:

# Click '''[[Clients:Products/Services Tab|Products/Services]]''' in the client profile.
# Click '''Click here to Manage''' for '''Addons'''.
# Click '''Add New Addon'''.
# If you are adding a predefined addon, select it and leave the name, price, and billing cycle empty.
# If you are adding a custom addon that will be specific to this client, set '''Predefined Addon''' to ''None'' and enter a custom name, price, and cycle.
# To delay generation of the invoice, uncheck the generate invoice checkbox.
# Click '''Save Changes''' to complete the process.

===Promotion Codes===

You can apply promotion codes to an existing service using the menu. For more information, see [[Promotions]].

===Auto Recalculate Recurring Price on Save===

Check this option to update the recurring amount field. You can use this after changing the product, configurable options, billing cycle, or promo code to auto calculate the new recurring price. We disable this by default to ensure that the system does not overwrite any discounted rates or custom pricing.

===Overide Auto Suspension===

This option can be used to allow extra time for payment to be made for specific individuals.

You can enable or disable this option from the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client profile.

==Invoicing Early==

In some circumstances, you may want to generate an invoice for a customer's next renewal date early.

Admins can generate invoices for services, domains, or addons with the ''Pending'', ''Active'', or ''Suspended'' statuses in advance from the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab.

For more information, see [[Clients:Summary Tab]].

==Upgrades/Downgrades==

===Admin Area===

[[File:Upgrade button.png|thumb|Upgrade/Downgrade Button]]

If you would like to change the product or service a client is assigned to and automatically charge or credit the difference for that change then you need to use the Upgrade/Downgrade process. You'll find the option for this next to the '''Products/Services''' menu in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab within the client profile.

To use it:
# Go to the product that you want to change.
# Perform the correct action for your WHMCS version:
#* For WHMCS 8.0 and later, click '''More''' and choose '''Upgrade/Downgrade'''.
#* For WHMCS 7.10 and earlier, go to the product you want to change, click '''Upgrade/Downgrade'''.
# Make the new product and billing cycle selections. A preview of what the charge will be for the remainder of the current cycle will display.
# Click '''Create Order'''. The system will create an order and invoice for the change.

<html><a href="http://www.youtube.com/watch?v=wXEulukuHdo" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

There will no immediate changes to the product after creating an upgrade order, the actual product or config option changes won't take effect until the invoice is paid. But as soon as the invoice is paid the product will be updated, the new recurring amount will be set, and with most supported control panels the upgrade is fully automated with the new package details/changes being passed over to the server module being used. Finally the upgrade email specified in the product configuration is sent to the user advising them of the new products details.

The same process can also be used for configurable options changes and billing the difference for those if the product contains them.

===Client Side===

Clients can also place orders for upgrades & downgrades themselves if you have permitted it in the product configuration. This allows clients to order upgrades/downgrades and complete them automatically without the need for any staff involvement.

For more information, including how to allow clients upgrades and how the system calculates upgrade charges, see [[Automated Upgrades and Downgrades]].

===Manual Upgrades===
There may be occasion when you wish to make an upgrade without placing an upgrade order (such as a free upgrade) or processing the upgrade before the client has paid for it.

To do this:

#Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab.
#Change the product in the menu.
#Check '''Auto Recalculate on Save'''.
#Click '''Save Changes'''.
#Click '''Change Package''' in the '''Module Commands''' section.

==Bulk Actions==

[[File:Bulk-actions.png|thumb|Bulk Actions Tool]]

The bulk actions option in WHMCS allows you to perform changes to two or more products inside a client's profile at the same time. The changes can consist of adjustments to the status, payment method, override auto-suspend date, first payment amount, recurring amount, next due date, and billing cycle. For example, you can use this option if you want to reduce a client's price on a number of separate products to the same level, execute module commands in bulk, or if you would like to bring multiple services in line to a matching due date.

To use this feature, from the client's '''[[Clients:Summary Tab|Summary]]''' tab, check the checkboxes next to the products, services, addons, or domains you want to update. The bulk actions will display under the item lists. Additional actions can be viewed by clicking '''Show Advanced Options'''. Enter any changes you wish to make (leaving blank any fields you don't want to change) and click '''Apply''' to complete the changes.

<html><a href="http://www.youtube.com/watch?v=WLLsQML6rEU" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

===Create Prorata Invoice===

When you change the Next Due Date of a product, service, addon, or domain, the system creates a pro-rated invoice that covers the period between the current next due date and the new one. This feature includes scenarios in which the various products have different next due dates to start with and will pro-rate each accordingly as separate line items on the invoice.

To use this, specify the new Next Due Date, check '''Create Prorata Invoice''', and then click '''Apply'''.

For example, the client could wish to pay for the following products on the 10th of the month going forward:

Product A - Next Due Date 01/01/2022 @ $30/month
Product B - Next Due Date 05/01/2022 @ $60/month

To do this, set the Next Due Date to 10/01/2022 and check the checkbox, an invoice with the following line items will be generated:

Product A (01/01/2022 - 09/01/2022) $8.00
Product B (05/01/2022 - 09/01/2022) $10.00
Total Due Today $18.00

Only once paid will the Next Due Dates for both products be updated and in future both products would be invoiced on the 10th January.

==Cancelling a Product/Service==

===Auto Terminate/Fixed Term===
You can setup products to automatically terminate after a set number of days from the date of signup. For more information refer to [[Products_and_Services#Pricing_Tab|Configuring Products/Services]].

===Clients Self Service===
[[File:Request-cancellation-form.png|800px]]

WHMCS can completely automate the process of product cancellation or wait for manual confirmation. To do this navigate to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings''', and enable the '''Show Cancellation Link''' option.

Clients can then request cancellation of any of their products & services directly from the client area.

To fully automate cancellation and have the module terminate command run (for example to remove the hosting account from the server) check '''Cancellation Requests''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' option.

Now when the cron runs any services with a cancellation request due today will be removed from the server and the status changed in WHMCS to Cancelled. The process runs as follows:

*Client clicks ''Request Cancellation'' button on the product details page in client area
*They're prompted to provide a cancellation reason and provided 2 choices for the cancellation - either '''Instant''' (on next cron run) or at the '''End of the Current Billing Cycle'''.
*If a matching domain exists under the client's account in active status with ''Auto Renew'' enabled, the customer is given the option to disable auto renew too - thereby leaving the domain to expire.
*Any unpaid invoices for the product will be cancelled ([[Invoice_Tab#Cancellation_Request_Handling|if enabled]])
*A notification email is sent to administrators and you will be able to review the reason provided in '''Clients > Cancellation Requests'''.

====Manual Cancellation====
If the Cancellation Request setting is '''not''' enabled then at this point you must navigate to the cancellation requests page, click through to the service page and click the '''Terminate''' module command button to remove the account from the server. The cancellation request is then moved from the ''Open Requests'' page to ''Completed Requests''.

====Automated Cancellation====
If the Cancellation Request setting '''is''' enabled the cancellation request will be actioned when the daily automation cron runs on the appropriate day. For example if the ''Immediate'' option was selected it will be terminated on the next cron run, if ''End of Billing Period'' was selected it will be terminated when the cron runs on the service's Next Due Date.

====Voiding Cancellation Requests====
If a Cancellation Request has been submitted by your client and they later change their mind, it is quick and easy to void their cancellation request. Simply navigate to '''Clients > Cancellation Requests''', locate the cancellation you wish to remove, and then click the red X next to the request to remove it. This will stop the cancellation from processing automatically. You'll need to make sure to mark any invoices that were cancelled as "Unpaid" to prevent billing errors.

===Admin Scheduled Cancellations===

As an admin user, you can schedule the termination of a product at the end of the currently active period by going to the Products/Services tab, checking the '''Auto-Terminate End of Cycle''' option and optionally entering a reason/note for it. Any unpaid invoices for the product will be cancelled and will suppress any further renewal invoices from generating for this product and terminate it when the next due date is reached.
The "Cancellation Requests" setting in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' must also be enabled.

===Admin Immediate Cancellation===

Finally, if you want to cancel or terminate a product or service immediately then you simply need to locate the item you wish to cancel, and from the Products/Services page, click the '''Terminate''' button if the product is linked to a module or if not, manually change the dropdown status from Active to '''Cancelled'''. Once you've done this, no further invoices will generate for the item.

===Addons===
When a product or service is terminated automatically by the WHMCS System, including through the above Admin Scheduled Cancellation routine, any child addon(s) attached to the product/service will also be cancelled at the same time. Addons do not support independent scheduled cancellations of their own however.

====Termination Date====
When an addon is Cancelled or Terminated, either manually via the admin interface or automatically as part of a product termination, the Termination Date will be assigned the current date automatically.
The termination date can be edited manually at any time via the Product Addon management screens within the admin area.
<div class="docs-alert-info">A termination date can only be set/edited when the addon is in one of either Terminated or Cancelled status.</div>

==Moving a Product/Service to another Client==
[[File:Transfer product.png|thumb|Transfer Product Popup]]
#From the Products/Services details page of the product you want to move, click '''Move Product/Service to Another Client''' located at the top-right of the page
#A popup box will appear (you will need popup blockers disabled to use this)
#In the popup enter the ID of the new owner. If you don't know the client's ID the Search field can be used to search by name, company or email address. Click the client's name and the ID will be filled in.
#After selecting the desired click, click the '''Transfer''' button
#The item will then be transferred, the window will close, and the original window will refresh to show the product under its new owner.

'''N.B.''' Moving a products/service between clients within WHMCS will not have any affect on the account on the server.

===Invoices===
Invoices cannot be moved between clients, therefore when moving a product/service any invoices will remain under the old owner. Therefore it would be advisable to check the old owner's Invoices tab for any unpaid invoices for this service and cancel them. If you wish to invoice the new owner for the service, move the Next Due Date forward/back by one day and a new invoice will be generated when the cron next runs.

==Deleting a Product/Service from a Client==

#From the Products/Services details page of the product you want to delete, click '''More''' and then click '''Delete'''.
#After clicking this link, you will be asked to confirm if you are sure you want to delete the item.
#If you click No you will be returned to the page, if you click Yes, the item will be deleted and you will be taken to the next product/service under that client.

'''Note:''' Deleting a product from WHMCS will not terminate it on the server. If you wanted to remove it from the server aswell, you need to run the Terminate Module Command as explained above before deleting the record from WHMCS.

==Resending Product Welcome Email==
To re-send a product welcome email simply navigate to the client's Products/Services tab and click the "Resend Product Welcome Email" button at the bottom of the page.

Domain Contact Verification

2023-05-04T13:59:09Z

John: /* Supported Registrars */

The current Transfer Policy for domains as enforced by ICANN states that any time a material change is made to a domain's registrant, organization or email address, a new Change of Registrant process should be triggered. This Transfer Policy has been mandated by ICANN to all accredited registrars.

The Transfer Policy can be seen in full at https://www.icann.org/resources/pages/transfer-policy-2016-06-01-en

==Supported Functionality==

WHMCS provides the following functionality to help domain registrars using WHMCS be compliant with the ICANN Transfer Policy:

* Provide informational alerts and messaging within the product when a domain is awaiting verification of the WHOIS Contact following a new registration
* Prior to making a change to the registrant name, organization or email address, a warning will be provided indicating that the change being made will trigger the Change of Registrant process
* Offer end users and admin users the ability to opt-out of the Transfer Lock imposed following the Change of Registrant process
* Provide informational alerts and messaging within the product indicating when a Change of Registrant process is pending for a domain, and the date by which verification must be completed
* Ability to request re-sending of the Verification Emails for the Change of Registrant process

==Supported Registrars==

At the time of writing, ICANN Transfer Policy functionality is supported by the following modules:

* Enom
* ResellerClub
* StarGate/UK2
* ResellerCamp
* NetEarthOne
* CentralNIC

==Important Notes==

* WHOIS Contact Verification is required both when a domain is registered for the first time, and when updating the contact information of an already registered domain. Both the former and the new email address of the domain will receive a verification email requesting them to approve the change.
* All verification emails triggered by WHOIS contact changes are sent directly by the domain registrars and not the WHMCS product.
* Rules and requirements for opting-out of the Transfer Lock vary by registrar. You should check with your chosen registrar what the requirements are for your use case.

==Example Messaging==

Below are examples of the alerts and messaging users will see when managing domains within WHMCS.

'''New Registration Verification'''

WHOIS Contact Verification is required when a domain is registered for the first time. Until that verification is completed, users will see a message as follows.

[[File:Domain-contact-verification-required.png]]

'''IRTP Transfer Lock Enabled'''

When a domain is registered for the first time, or when a change of registrant is made without opting-out of the transfer lock, the domain will be locked for transfer and users will see a message as follows:

[[File:Domain-irtp-transfer-lock.png]]

'''Change of Registrant Opt-Out Confirmation'''

When making a change to the registrant name, organization or email address, the following dialog will be displayed upon submission indicating that the IRTP Transfer Lock will be triggered by this change and providing the option to Opt-Out.

[[File:Domain-transfer-lock-opt-out.png]]

'''Contact Change Successful - Approval Required'''

Following submission of a WHOIS Contact Change that triggers the Verification Process, users will be shown a message indicating that the change requires verification and that an email has been sent to them.

Any requested changes will not be made to the WHOIS Contact Information until the verification has been successfully completed.

[[File:Domain-contact-verification-required2.png]]

'''Pending Contact Change with Transfer Lock'''

When a contact change is pending, the alert will provide the date approval is needed by if it is made available by the chosen domain registrar.

[[File:Domain-contact-change-pending.png]]

Database Errors

2023-04-25T12:48:53Z

John:

You may see the following errors when working with databases:

==Down for Maintenance - An upgrade is currently in progress==

This error indicates that the version of WHMCS's files does not match the version of your database. For example, you may have uploaded files for WHMCS 8.6 but, because the upgrade script has not run, the database is still set up for WHMCS 8.5.

To resolve this, upload the current version's WHMCS files again and perform the upgrade process. After the upgrade, you will be able to access the system again.

For more information, see [[Updating]] and [https://help.whmcs.com/m/updating/l/1431723-troubleshooting-a-down-for-maintenance-error-while-updating-whmcs Troubleshooting a Down for Maintenance Error while Updating WHMCS].

==Critical Error - Unable to connect to the database==

This error indicates that the system cannot connect to your database. Check and update the database connection details in the <tt>configuration.php</tt> file. For example, you may need to make corrections if you recently changed the password or renamed the database itself. This could also be an issue with MySQL® or an empty <tt>configuration.php</tt> file.

If you have confirmed that the database name, username, and password are correct, make certain that the MySQL user is assigned to the desired database and has full access. For help, contact your hosting provider or system administrator.

==Critical Error - Could not connect to the database==

This error indicates that the system cannot connect to your database. Check and update the database connection details in the <tt>configuration.php</tt> file. If you've made changes to your PHP version or configuration, check whether the <tt>[https://www.php.net/manual/en/ref.pdo-mysql.php PDO_MySQL]</tt> PHP extension is installed and your system meets all of our [[System Requirements|system requirements]].

You can find more details about the error by [[Blank_or_Partially_Rendered_Pages#Enabling_From_Your_Configuration_File|enabling error reporting]] and reloading the page. For help, contact your hosting provider or system administrator.

==Critical Error - Could not connect to the $db_name database. PDO extension not found==

The application requires the <tt>[https://www.php.net/manual/en/ref.pdo-mysql.php PDO_MySQL]</tt> PHP extension in order to connect to your MySQL® database but it is not available in your server's PHP configuration.

Check to ensure that your system meets all of our [[System Requirements|system requirements]].

==Error Message "Field xxx doesn't have a default value" during installation==

This error indicates that you attempted to install WHMCS with MySQL Strict Mode enabled. WHMCS requires you to disable this before installation.

For steps to disable this, see [https://help.whmcs.com/m/installation/l/678317-disabling-mysql-strict-mode Disabling MySQL Strict Mode].

==MySQL server has gone away==

This error indicates that the MySQL server is closing the connection WHMCS is using for the current task. You may see this when upgrading WHMCS due to the large number of MySQL queries that upgrading performs. In most cases, this occurs because the timeout value is too low to allow all the upgrade tasks to finish.

To resolve this during generation operations, work with your system administrator or hosting provider to increase the <tt>wait_timeout</tt> and <tt>max_allowed_packet</tt> values in the MySQL configuration. If you were performing an upgrade, make certain to restore your pre-upgrade database backups before running the upgrade script again.

{{troubleshooting}}

Automated Upgrades and Downgrades

2023-04-04T16:00:57Z

John: /* Admin Upgrades */

==How it works==

In WHMCS, your clients can upgrade or downgrade their products and packages directly in the Client Area. When they place an upgrade or downgrade order, they will receive a refund for any value they haven't used of the current cycle on the existing product or service. Then, the system will charge them for the remainder of the cycle at the new product's or service's price. The next due date doesn't change.

<div align="center">
<p>'''Old Product/Service'''<br />
Price Per Day * Number of days until next due date = Amount Credited</p>
<div class="docs-alert-info">
'''Price Per Day''' in the above calculation is the '''Recurring Amount''' of the client's service divided by the number of days in the billing cycle.
</div>
<p>'''New Product/Service'''<br />
Price Per Day * Number of days until next due date = Amount Debited</p>
<div class="docs-alert-info">
'''Price Per Day''' in the above calculation is the cost of the new service divided by the number of days in the billing cycle.
</div>
<p>'''Total Payable Today = Amount Debited - Amount Credited'''</p>
</div>

===Free to Paid Products===

When a client upgrades a free product to a paid product, you must set a '''Next Due Date''' to determine when it will renew. WHMCS sets this automatically to one billing cycle from the date of upgrade.

For example, if a client upgraded from a free product to a monthly paid product on the 1st of January, the '''Next Due Date''' would become the 1st of February.

===Promotion Codes===

====Upgrade Discounts====

You can configure [[Promotions#Upgrades.2FDowngrades|promotion codes]] to apply to upgrades. This is useful for incentivizing clients to upgrade to higher-tier products. When the client places an upgrade order, they will receive the opportunity to enter a promo code. The system calculates the discount based on the total amount due. Clients receive this as a discount on the amount payable.

<div align="center">
'''Total Payable Today (from above) - Discount = Discounted Upgrade Price'''
</div>

====Lifetime Promotions====

You can configure [[Promotions|promotion codes]] to last the lifetime of a client's service, including through upgrades and downgrades. For these, the system calculates the recurring discount using the full product price after the upgrade. The recurring price is reduced accordingly and then updated on the client's service.

===Upgrade Order Handling===

If an upgrade order is not paid before the renewal invoice is generated by the daily cron task, the system cancels the upgrade order automatically and generates the renewal invoice using the current service details. To upgrade, the client must place another upgrade order.

==Clients Self Service==

To place an upgrade or downgrade order, the client must log in to the Client Area, go to '''Services > My Services''', click to view the full details for the product or service they wish to manage, and then select the desired upgrade options.

==Admin Upgrades==

Admins can also create upgrade orders from the Admin Area. The system doesn't restrict admins to the products or options in the product configuration, so admins can upgrade between any two packages. Using the upgrade process will create the prorata invoice for the difference and auto-provision it on payment.

To create an upgrade order from the Admin Area, go to the service to upgrade and click '''More > Upgrade/Downgrade''' in the product details tab.

==Configuration==

===Product Upgrades===

To allow clients to upgrade and downgrade their packages, you need to specify the products that can upgrade to and downgrade to each of your packages.

To do this, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services''' in the '''Upgrades''' tab of the product configuration.

To select multiple products, hold the '''Ctrl''' key while selecting the products in the list.

===Configurable Options Upgrades===

With the configurable options upgrade configuration, this allows your clients to upgrade or downgrade the configurable option selections you offer on the product. You do not need to specify any further configuration for this.

Check the checkbox and the client will see the upgrade options in the Client Area. The system calculates the upgrade price for configurable options the same way as the products above.

Resetting an Admin Password

2023-03-07T15:16:56Z

John: /* There was an error sending the email. Please try again */

If you forget your administrator password for WHMCS, you can request a password reset by clicking "'Forgot your password?''' on the [[Admin Area]] login page. Follow the instructions in the email message you receive.

===Missing Reset Link===

If you do not see the '''Forgot your password?''' link, the option is disabled in the '''[[Security Tab|Security]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.

To reenable it, follow the steps below:

# Log in to your database administration interface. Usually, this is phpMyAdmin in your server's control panel.
# Select the WHMCS database in the left-hand menu.
# Browse to the <tt>tblconfiguration</tt> table.
# Ensure that the <tt>DisableAdminPWReset</tt> setting has a blank value.
# Click '''Go''' to apply the changes.

If you visit the [[Admin Area]] login page again, you will see the '''Forgot your password?''' link.

===There was an error sending the email. Please try again===

If your system is encountering a technical error that prevents the sending of the reset email, you can change the password directly in the database.

To do this:

# Log in to your database administration interface (usually phpMyAdmin via your server control panel).
# Select the WHMCS database in the left-hand menu.
# Browse to the <tt>tbladmins</tt> table.
# Click '''Edit''' next to the administrator account that you want to reset.
# Enter the new password in the '''password''' textbox.
# From the '''Functions''' menu, select ''MD5''.
# Clear the contents of the '''passwordhash''' field.
# Click '''Go''' to apply the changes.

You can now visit the [[Admin Area]] login page and log in using the new password. To troubleshoot the problem with sending email, see [[Email Sending Issues]].

Email Importing

2023-02-09T18:00:18Z

John: Fixed Email Importing Integrations link

Email importing is distinct from email piping and requires a different configuration. We recommend using email importing instead of email piping if you use any control panel other than cPanel or if you want to import email from multiple domains.

Begin by configuring your support ticket departments. You can do this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Support Departments]]''' or, prior to WHMCS 8.0, '''Setup > Support > Support Departments'''. Add each of your departments and the email addresses that you assigned to them.

<div class="docs-alert-info">
<strong>RFC 3834</strong><br />
In WHMCS 8.1 and later, the system sends support emails with RFC 3834-compliant headers by default.
* You can disable this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''[[Mail Tab|Mail]]''' tab.
* Regardless of your settings, WHMCS will not accept email that contains the <tt>Auto-Submitted</tt> header via email piping or email importing.
</div>

==Email Importing Service Providers==

In addition to traditional POP3 or IMAP service providers, WHMCS supports email importing via Gmail in WHMCS 8.1 and higher and via Microsoft® services in WHMCS 8.6 and higher. These integrations provide access to your mail provider via secure protocols. Some mail providers require you to use these capabilities or have announced a requirement for it in the future.

To use these service providers, you will need to both configure your mail service provider and create an app for it via either the Google console or Microsoft Azure®. For more information, see [[Email Importing Integrations]].

==Configuring Email Importing==

[[File:Cron piping.png|thumb|The cron command]]

To configure email importing for a support department:

# Set up your email accounts:
#* For POP3 or IMAP, create a unique email account on your mail server for each support department. This must be a mailbox; an alias is not sufficient.
#* For Google or Microsoft, configure your mail service provider and create an app for it:
#** For steps to enable Google, see [https://help.whmcs.com/m/support_tools/l/1328652-setting-up-pop3-importing-with-oauth-via-google Setting Up POP3 Importing via Google].
#** For steps to enable Microsoft, see [https://help.whmcs.com/m/support_tools/l/1600723-setting-up-importing-via-microsoft Setting Up Importing via Microsoft].
# In WHMCS, navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Support Departments]]''' or, prior to WHMCS 8.0, '''Setup > Support > Support Departments'''.
# Create a new department and enter the top section of information or, for existing departments, click '''Edit'''.
# Enter the email information for the department:
## Select a '''Service Provider'''.
## Enter the appropriate details for your service provider.
## If you selected ''OAuth2'' as your '''Authentication''' type for '''Google''', enter your '''Email Address''' and the '''ClientID''' and '''Client Secret''' that you generated. Then, click '''Connect'''.
# Set up a cron job to run the <tt>pop.php</tt> file using the '''Ticket Importing using Mail Importing (POP3/IMAP)''' command on the '''Support Departments''' page every few minutes. We recommend that you set this to run every five minutes.

<div class="docs-alert-info">
The system will delete email in the source mailboxes upon successful import into WHMCS.
</div>

Client Groups

2023-02-07T13:06:33Z

John: /* Create a Client Group */

Client Groups allow you to group various clients together and quickly identify them at a glance.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Client Groups''' or, prior to WHMCS 8.0, '''Setup > Client Groups'''.

== Create a Client Group ==

To create a group, fill in the details under '''Add Client Groups'''.

*You can assign a color to the group. It will appear in client list, support tickets, and menus (for example, to highlight important customers).
* You can assign a group discount that will apply to all future invoices for those clients. The system applies the discount at the invoice stage, so it will not appear at checkout.
*You can exempt the group from suspensions or terminations. This does not apply to fixed-term or free trial products.
*You can enable '''[[Clients:Profile_Tab#Separate_Invoices|Separate Invoices]]''' for an entire group.

You can add, edit, and remove client groups here. However, you can't remove a group that is in use.

Use the client's profile area to assign or change their groups.

==Domain Pricing Slabs==

Domain Pricing Slabs let you specify different prices for clients within a client group. For example, you may wish to set lower domain pricing for a particular client group without offering the blanket discount of the group discount feature. You could even use this to give a single customer custom pricing.

If a TLD doesn't have a set custom price, the system charges the client the default base slab pricing.

===Creating a Slab===

[[File:Slab pricing.png|thumb|Configure Slab Pricing]]

To create a slab:

#Create a group (see above).
#Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Pricing'''.
#Click ''Open Pricing'' next to the first TLD for which you want to set custom pricing.
#Select the group name from '''Pricing Slab for'''.
#Click '''Activate Pricing Slab'''.
#Click '''OK'''.
#Enter the custom pricing for this domain. The system copies the base slab pricing for your convenience.
#Click '''Save Changes'''.
#Repeat this process for each additional domain.

Now, when a member of this client group orders these domains, they will receive the custom slab pricing instead of the default price.

===Deactivating a Slab===

If you no longer want to offer custom pricing on a particular domain, you can disable the slab at any time. To do this:

#Click '''Open Pricing''' next to the TLD.
#Select the group name from '''Pricing Slab for'''.
#Click '''Deactivate Pricing Slab'''.

Any new orders from clients in this group will now receive the regular price. Any existing domains that clients ordered while the custom pricing was in effect will retain that price. To change them, use the '''[[Bulk Pricing Update Utility]]'''.

===Assigning a Client to a Client Group===

To assign a client to a client group:

# Navigate to '''Clients > View/Search Clients''' and select the client.
# Select the '''[[Clients:Profile Tab|Profile]]''' tab.
# Use the '''Client Group''' menu to set the required client group.
# Click '''Save Changes'''.

EWAY

2023-02-07T13:05:23Z

John: /* Troubleshooting */

<div class="docs-alert-info">We added this module in WHMCS 7.9. It supersedes the [[EWAY Rapid 3.1]] module.</div>

eWAY lets WHMCS users to accept online credit card payments easily and securely so they can grow their business fast. The Secure Fields solution allows merchants to securely and seamlessly process payments from their own website, without exposing the sensitive card data.

<div class="docs-alert-info">[https://my.eway.io/whmcs Create an eWAY Account]</div>

Further, the WHMCS integration takes advantage of Token Payments, allowing customers to securely store the card information within eWAY’s PCI DSS environment, and WHMCS uses the Token (which represent the saved card) to handle all future payments without the customer having to key in their details again.
{{gateways
| type = token
| onetime = yes
| recurring = yes
| refunds = yes
| updatecc = yes
}}

== Adding the EWAY Payment Gateway ==

To set up the EWAY payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''EWAY'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Create and enter your EWAY credentials:
## Create an [https://my.eway.io/whmcs eWay account].
## Log in to the [https://my.eway.io MYeWAY Dashboard].
## Go to '''My Account > API Key'''.
## Copy and paste your API key and password into WHMCS. For information on setting up your API key and password, see the [https://go.eway.io/s/article/How-do-I-setup-my-Live-eWAY-API-Key-and-Password eWAY Knowledge base.].
## Copy and paste your public API key ('''Pay Now Button Public API key''') into WHMCS. For information on obtaining your Public API Key, see [https://go.eway.io/s/article/How-do-I-find-my-Public-API-Key Finding my Public API Key]
# Click '''Save Changes'''.

===Test Mode===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

===Migrating to eWAY from eWAY Rapid 3.1===

The eWAY Rapid 3.1 module included in previous versions of WHMCS can be easily replaced with the eWAY module.
If the WHMCS installation has existing tokens stored from the previous module, a button will be shown on the Payment Gateways configuration page to swiftly migrate the tokens to the new module.

#Obtain the Public API Key from eWAY (see above).
#Log in to the WHMCS Admin Area.
#Navigate to the Setup menu.
#Click on the Payments option, and then again on Payment gateways.
#Enter your administrator password if prompted.
#Click on the '''Manage Existing Gateways''' button and locate the eWAY Rapid Module.
#Click on the '''Migrate to eWAY Module''' button.
#Enter the Public API Key where prompted and press the '''Migrate''' button
#The page will save and reload showing the eWAY module is active and the eWAY Rapid Module disabled
#Update any configuration on the newly activated module as required.

<div class="docs-alert-info"><i class="fa fa-question-circle"></i> The Migrate to eWAY Module will only show if the WHMCS installation has Payment Methods associated with the eWAY Rapid Payments module.</div>

==Troubleshooting==
===Card Fields are Not Displayed===
The '''Card Number''', '''Expiry Date''' and '''CVV Number''' fields may not display on the shopping cart or the Manage Pay Methods page in the shopping cart, at '''Hello, User! > Payment Methods''' in the Client Area, or when you click '''Add Credit Card''' in the '''[[Summary_Tab|Summary]]''' tab in the client profile.

This indicates that eWAY is rejecting the eWAY API key in the configuration at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]. This might occur if you entered the API key incorrectly, it has expired, or eWAY revoked it.

To resolve the error, perform steps 4 and 5 from [[#Adding_the_EWAY_Payment_Gateway|Adding the EWAY Payment Gateway]] above.

{{modules}}

Database Backups

2023-01-27T10:06:18Z

John: /* cPanel Username */

Regular backups help to protect your customer data and WHMCS configuration, and they are vital if you run into certain prolems. WHMCS can automatically back up your database and upload it to a SFTP/FTP location or email it to a designated email address. You can also request a full cPanel backup for a specific user as part of the automatic backup process.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Database Backups'''.

<div class="docs-alert-info">
We added automated backups in WHMCS 7.3.
</div>

==Enable Automatic Backups==

To enable automatic backups for your WHMCS installation:

# Choose a backup option by clicking the correct heading: '''SFTP/FTP Backup''', '''cPanel Backup''', or '''Daily Email Backups'''.<div class="docs-alert-warning"><span class="title">Connection Tests</span><br />The '''SFTP/FTP Backup''' and '''cPanel Backup''' options require a successful connection test before activation. A connection test ensures that the details are valid and the WHMCS installation can connect to the server. Any connection issue allows a resolution before a backup attempt occurs, incurring less chance of a failed connection.</div>
# Enter the necessary informaton for that option. For more information on each option, see the sections below.
# Click '''Test Connection''' or '''Save & Activate'''.

===SFTP/FTP Backup===

The '''SFTP/FTP Backup''' option only supports FTP and SFTP. Other protocols, like FTPS and FTP/TLD, are unsupported.

This backup type stores the WHMCS-generated zipped SQL file on the specified remote server. Check "'Use Secure FTP/SFTP (Recommended)'" to ensure that the backup upload is completed using an SFTP connection.

====FTP Destination====

The '''FTP Destination''' value is relative to the login folder for the FTP/SFTP account you are using. For example, if, when you log in using your FTP details, the folder is <tt>/home/user/</tt> and the backup will be in <tt>/home/user/backups</tt>, enter <tt>backups/</tt> as the '''FTP Destination''' value.

If you intend to upload the backup file to the login folder, leave this field empty.

===cPanel Backup===

The '''cPanel Backup''' option uses the '''Full Backup''' feature of cPanel's '''[https://docs.cpanel.net/cpanel/files/backup-wizard/ Backup Wizard]''' interface.

====cPanel Username====

When you enter your cPanel account information, the '''cPanel Username''' value is the name of the account that hosts your WHMCS installation.

====Backup Destination====

You can select the following '''Backup Destination''' options:

* '''Remote FTP Server''' — Select this option to use FTP to store the backup file on a remote server.
* '''Remote FTP Server (Passive connection)''' — Select this option to use passive FTP to store the backup file on a remote server.
* '''Secure Copy (SCP)''' — Select this option to use SCP to store the backup file on a remote server.
* '''Home Directory''' — Select this option to save the backup file to the server.

<div class="docs-alert-warning"><i class="fa fa-exclamation-triangle"></i>Using '''Home Directory''' will generate the backup file in the cPanel user's home directory. This will count against any disk space limits, and you should manually move it to a better location after completion.</div>

The system cron job will only request the start of a full backup. Completion and relocation of the backup occurs within cPanel, and WHMCS will not notify you about the process.

===Daily Email Backups===

This backup option may fail to complete successfully with large databases due to system memory or time execution limits. We do not recommend this method for larger installations.

==Disable Automatic Backups==

To disable an automatic backup method:

# Click on that option.
# Click '''Deactivate'''.

System Environment Guide

2023-01-25T15:40:19Z

John: /* Extensions */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Grant Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following grant privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database grant privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the grant privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.
<div id="PHP_Version"> </div>
== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===
WHMCS requires most of the default compiled extensions such as PDO, mysqlnd, JSON, libxml, DOM, Fileinfo, etc.. It is assumed that these will not be intentionally disabled in the environment. The following additional extensions will also need to be compiled and enabled:

==== Required ====
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.

==== Recommended ====
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

Namecheap

2023-01-10T13:02:19Z

John: /* Troubleshooting */

== About this Module ==

The Namecheap module allows you to register and manage domains with Namecheap.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
}}
== Activation ==

To activate and begin using the Namecheap registrar module:

# Log in to the WHMCS Admin Area.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Registrars]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Registrars'''.
# Find '''Namecheap''' in the list.
# Click '''Activate'''.
# Enter your Namecheap credentials.
# Click '''Save Changes'''.
# [https://www.namecheap.com/ Open a Namecheap ticket] to request API access to your Namecheap account for your server's IP address. You can find this IP address in WHMCS at '''Help > [[License Information]]'''.

=== Test Mode ===

You can use test mode to simulate domain registration and management function without registering a domain or incurring charges. This can be useful to test WHMCS configurations.

== Automatic Registration ==

WHMCS allows you to set up automatic domain registration on a per-extension basis, enabling you to use different registrars for different TLDs.

To enable automatic registration, see [[Domain Pricing]].

== Automatic Domain Synchronization ==

This module supports automatic domain synchronization for syncing expiry dates and status changes for incoming transfers.

To use this, enable '''Domain Sync Enabled''' in the '''[[Domains_Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. You must also make certain to configure the '''[[Crons#Domain_Sync_Cron|Domain Sync Cron]]'''.

== Troubleshooting ==

=== Registrar Error Invalid Client IP ===

Seeing this error indicates that your Server IP has not been whitelisted for API access (see above).

===Unable to obtain Nameservers for an unregistered domain===

This error occurs when the domain does not exist in your Namecheap account. This message will display when a domain transfer is in progress but will automatically disappear when the transfer is complete.

{{modules}}

CentralNic Reseller

2023-01-05T15:43:15Z

John: /* Troubleshooting */

== About this Module ==

<div class="docs-alert-success">
We added this module in WHMCS 8.7.
</div>

The CentralNic Reseller module allows you to register and manage domains with resellers from the CentralNic group. Currently, this module supports registrations via RRP Proxy.

<div class="docs-alert-warning">
This module replaces the previous '''[[RRPProxy]]''' module. It provides the latest and most feature-complete integration for RRP Proxy (now CentralNic Reseller) services.
</div>
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| getepp = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainrelease = yes
| domainsync = yes
| premium = yes
| transferout = yes
}}

==Activation==

To activate and begin using the CentralNic Reseller registrar module:

# Log in to the WHMCS Admin Area.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Registrars]]'''.
# Find '''CentralNic Reseller''' in the list.
# Click '''Activate'''.
# Enter your CentralNic Reseller credentials and configuration. For more information, see below.
# Click '''Save Changes'''.

===Test Mode===

You can use test mode to simulate domain registration and management function without registering a domain or incurring charges. This can be useful to test WHMCS configurations.

To use Test Mode, you must create a test account and enter that password in '''Test Password'''.

===Proxy Server===

This setting allows you to specify the proxy server for incoming requests via the cURL <tt>[https://curl.se/libcurl/c/CURLOPT_PROXY.html CURLOPT_PROXY]</tt> option. Using a proxy server can improve HTTP communication performance by keeping connections open longer.

This setting is '''optional'''.

===DNSSEC===

This setting allows you to choose whether users can configure [https://www.icann.org/resources/pages/dnssec-what-is-it-why-important-2019-03-05-en Domain Name System Security Extensions (DNSSEC)] in the WHMCS Client Area. If you enable this, '''DNSSEC Management''' will display as an option in the Client Area sidebar menu when managing a domain.

====What is DNSSEC?====

DNSSEC is a set of IETF specifications for securing information within the DNS system. They provide authentication for the origins of DNS data and denial of existence as well as ensuring data integrity. They do not, however, provide authentication of availability or confidentiality.

====Key Data to DS Data Conversion====

If CentralNic requires DS Data but receives Key Data, it will convert the Key Data into DS Data. The conversion uses SHA-256 and DSData digest type 2. This conversion ensures compliance with the relevant industry standards.

The module sends the following parameters:

<table class="table table-striped table-condensed">
<tr><th>Parameter</th><th>Description</th></tr>
<tr><td><tt>Flags</tt></td><td><tt>256</tt> (zone signing key) or <tt>257</tt> (key signing key)</td></tr>
<tr><td><tt>Protocol</tt></td><td><tt>3</tt> (DNSSEC)</td></tr>
<tr><td><tt>Algorithm</tt></td><td><ul><li><tt>8</tt> (<tt>RSA/SHA256</tt>)</li><li><tt>10</tt> (<tt>RSA/SHA512</tt>)</li><li><tt>12</tt> (<tt>GOST R 34.10-2001</tt>)</li><li><tt>13</tt> (<tt>ECDSA/SHA-256</tt>)</li><li><tt>14</tt> (<tt>ECDSA/SHA-384</tt>)</li><li><tt>15</tt> (<tt>Ed25519</tt>)</li><li><tt>16</tt> (<tt>Ed448</tt>)</li></ul><div class="docs-alert-warning">While other [https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml DNSSEC algorithms] exist, CentralNic Reseller cannot support them because it does not support SHA-1. For more information, see [http://tools.ietf.org/html/rfc4034#appendix-A.1 RFC 4034].</div></td></tr>
<tr><td><tt>Pubkey</tt></td><td>The public key.</td></tr>
</table>

For more information about CentralNic's data conversion process, see [https://kb.centralnicreseller.com/dns/dnssec CentralNic Reseller's DNSSEC documentation] and the [https://nic.cam/static/doc/OperationsManual-v3.2.14.pdf CentralNic Registry Registrar Operations Manual].

== Automatic Registration ==

WHMCS allows you to set up automatic domain registration on a per-extension basis, enabling you to use different registrars for different TLDs.

To enable automatic registration, see [[Domain Pricing]].

== Automatic Domain Synchronization ==

This module supports automatic domain synchronization for syncing expiry dates and status changes for incoming transfers.

To use this, enable '''Domain Sync Enabled''' in the '''[[Domains_Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings'''.

You must also make certain to configure the '''[[Crons#Domain_Sync_Cron|Domain Sync Cron]]'''.

== Troubleshooting ==

===Entity reference not found===
This error occurs when the domain does not exist in your CentralNic Reseller account. This message will display when a domain transfer is in progress but will automatically disappear when the transfer is complete.

{{modules}}

Directory Refresh Guide

2022-12-06T22:47:18Z

John:

==Refreshing a Directory==
Refreshing directories can help to troubleshoot and resolve some errors. The example below refreshes the <tt>/modules/servers/</tt> directory.

To do this:
# Download and unzip the WHMCS file set that matches the current version of your WHMCS. You can download current versions of WHMCS including Long Term support versions from [https://download.whmcs.com/ WHMCS Downloads Page].
# Navigate to the directory to refresh <tt>/whmcs/modules/</tt>.
# Rename the unaltered ‘’’servers’’’ directory to contain the original name and the date. For example, <tt>servers_new_MM_DD_YYYY</tt>.
# Upload the unaltered directory to the parent directory within your WHMCS installation (in this example, the <tt>/modules/</tt> directory).
# Rename the previous directory and include the date. For example,<tt>servers_old_MM_DD_YYYY</tt>.
# Revert the new directory name to the original name. For example, <tt>servers</tt>.
<div class="docs-alert-success">
After you finish, check within WHMCS to ensure that refreshing the directory resolved your issue.
</div>

== Restoring Customisations ==

After confirming that refreshing the directory has resolved your issue, you may need to restore any customisations.

To achieve this, you would need to copy the customisation from the ‘<tt>servers_old_MM_DD_YYYY</tt> directory to the now refreshed <tt>servers </tt> directory.

We recommend moving each customisation seperately and checking for errors within WHMCS in between each addition. This allows you to identify any problems by the specific module and allow you to choose whether to remove the customization or contact the third-party developer for help."
=== Cron Directory ===

Refreshing the cron directory may require additional steps, including updating your configuration in the <tt>config.php</tt> file.

To do this, use the instructions within the <tt>config.php</tt> file in the crons directory to uncomment the WHMCS path line and provide the full path to your WHMCS installation.
<div class="source-cli">$whmcspath = /home/username/public_html/whmcs/;</div>
In this example, the server runs cPanel & WHM, the account username is <tt>username</tt>, and <tt>whmcs</tt> is the WHMCS installation directory.

Stripe

2022-11-17T09:40:14Z

John: /* Troubleshooting */

== About this Module ==

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system to submit credit card information to Stripe, which stores it remotely.

For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]].
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-warning">
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.
</div>
== Adding the Stripe Payment Gateway ==

[[File:stripe.png|thumb|Stripe Module Settings]]

To set up the Stripe payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Stripe'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Configure a display name. We recommend <tt>Credit Card</tt>.
# Go to the [https://dashboard.stripe.com/account/apikeys Stripe portal] and retrieve the publishable and secret API keys.
# Enter your Stripe credentials.
# Optionally, customize the '''Statement Descriptor Suffix''' with a maximum of 22 characters.
# In WHMCS 8.0 and later, leave the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' empty. WHMCS auto-generates these. See below for more information.
# Optionally, check '''Allow Payment Request Buttons'''. See below for more information.
# Click '''Save Changes'''.
# If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account's currency with a valid exchange rate at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. Stripe only returns transaction fees in the default currency for the Stripe account.

=== WebHook Endpoints ===

<div class="docs-alert-info">
You can use Stripe Webhooks in WHMCS v8.0 and above.
</div>

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click '''Save Changes''', WHMCS will use the '''Stripe Publishable API Key''' and '''Stripe Secret API Key''' to generate the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

* If you enter live API keys (<tt>sk_live</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret'''.
* If you enter test API keys (<tt>sk_test</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

WHMCS registers the WebHook Endpoints to deliver these events from Stripe:

* <tt>customer.source.updated</tt>
* <tt>customer.card.updated</tt>
* <tt>payment_method.updated</tt>

To change the WebHook ID, empty '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' and click '''Save Changes'''. WHMCS will auto-generate them again with new values.

=== Payment Request Button ===

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay). For customers who don’t use Apple Pay, '''Payment Request''' supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

==== Apple Pay ====

[[File:apple_pay_checkout.png|thumb|The Apple Pay Button on Checkout]]

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they're using Safari® on their iPhone® or iPad®, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac®, and have an iOS® device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, <tt><nowiki>whmcs.com</nowiki></tt>) and subdomains (for example, <tt><nowiki>shop.whmcs.com</nowiki></tt>).
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> An SSL certificate is '''required''' to use Apple Pay.</div>

To do this:

# Download this [https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association domain association file] and host it at <tt>/.well-known/apple-developer-merchantid-domain-association</tt> on your site. For example, if you're registering <tt><nowiki>https://example.com</nowiki></tt>, make that file available at <tt><nowiki>https://example.com/.well-known/apple-developer-merchantid-domain-association</nowiki></tt>.
# To instruct Stripe to register the domain with Apple, go to the '''[https://dashboard.stripe.com/account/apple_pay Apple Pay]''' tab in '''Account Settings''' in the Stripe Dashboard.

==== Google Pay ====

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

==== Microsoft Pay ====

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

=== Test Mode ===

This module does not support test mode.

== Payment Workflow ==

[[File:stripe_checkout.png|thumb|The Stripe module on Checkout]]

The Stripe payment workflow supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorisation is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.

<div class="docs-alert-info">
WHMCS 8.3 and higher includes support for disputes for Stripe and PayPal® transactions at '''Billing > [[Disputes]]'''.
</div>

===Recurring Payments===

Automated recurring payments use stored tokens. If a client card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

== Payment Gateway Balances ==

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At '''Billing > [[Transactions]]''', you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see [[Payment Gateway Balances and Transactions]].

This requires you to enable '''View Gateway Balances''' for the desired administrator role at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]'''.

<div class="docs-alert-warning">
In the Admin Area [[Admin_Dashboard|Dashboard]], you can view your Stripe balances through the '''Stripe Balance''' widget. However, this widget does not use the <tt>WHMCS\Module\Gateway\Balance</tt> and <tt>WHMCS\Module\Gateway\BalanceCollection</tt> classes to display balances. For more information, see [[Stripe Balance Widget]].
</div>

== Migrating to Stripe ==

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe's tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 8.0 to 8.6, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > Payment Gateways''' and choose '''All Payment Gateways'''.
# Activate the Stripe module.
# Click '''Deactivate''' for your previous merchant gateway provider.
# Select Stripe as the replacement gateway to switch users of the previous gateway module to.
# Click '''OK'''.

=== Migrating from a 3rd Party Stripe Module ===

The WHMCS Stripe module uses the Stripe <tt>cus_</tt> reference to capture payments (for example, <tt>cus_9MvIb7UlgJfJTn</tt>). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the <tt>cus_</tt> reference, navigate to a client that you know has an active Stripe token and click on one of the pay methods in the '''Summary''' tab of the client's profile. Verify that the listed token includes the <tt>cus_</tt> prefix.

To start using the WHMCS Stripe module:

# Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the <tt>tblpaymentgateways</tt> database table.
# Activate our official Stripe module.
# Deactivate the previous Stripe module.
# Check one of the Stripe pay methods on a client. If the token contains <tt>cus{_}</tt>, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing "example" with the name of the previous module: <source lang="sql">UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example'; </source>
# Remove any third-party files and template customisations for the previous Stripe module.

==Troubleshooting==

===Remote Transaction Failure. Please Contact Support===

This issue has multiple causes. This may also display as '''Error'''.

To resolve this issue:

# Go to '''Billing > Gateway Log'''.
# Check the '''Result''' and '''Debug Data''' columns for error messages or codes from the time of the payment attempt.
# Perform the appropriate steps in Stripe's [https://stripe.com/docs/error-codes Error Codes] and [https://stripe.com/docs/declines/codes Declines Codes] documentation.

See below for other common causes of this error:

====Payment Blocked By Stripe====

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

# Log in to your [https://dashboard.stripe.com/ Stripe Dashboard].
# Go to '''Developers > Logs'''.
# Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment was blocked (for example, with a '''The zip code you supplied failed validation''' error).
# Adjust the rules in your Stripe account for the error. For help, contact [https://support.stripe.com/ Stripe support].

====Customisations====

This issue may also present itself as '''"No Stripe Details Found for Update"''' in the '''Gateway Log'''.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, these issues may trigger this error:

* A hook file in <tt>/includes/hooks/stripe.php</tt>. Remove this file when switching to the WHMCS Stripe module.
* Template customisations in your active order form template files.
* The payment method is set to a module other than Stripe. In this case, perform one of the following actions:
** Change the client's '''Payment Method''' setting in the client's '''Profile''' tab to the Stripe module.
** Make Stripe the system default payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

====Out Of Date Template Files====

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The [[Release Notes]] for each version of WHMCS provide links to template changes.

====Network Analyser Tool====

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section '''Another Error Type''' in [https://help.whmcs.com/m/troubleshooting/l/1312423-an-error-occurred-while-communicating-with-the-server-please-try-again this help article]. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

===No Stripe Customer Details Found===
The system logs this error in the debug data section of '''Billing > [[Gateway Log]]'''. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the '''[[Pay Methods]]''' section of the client's '''[[Clients:Summary Tab|Summary]]''' tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe. This will create a payment method to use for future automatic payments.

==="You must provide a value for 'cvc'===

If you see at '''Billing > [[Gateway Log]]''' for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe.

For more information, see [https://stripe.com/docs/api?lang=python#create_card_token Stripe's documentation] (click '''show child parameters''').

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

===Network error [errno 35]: Unsupported SSL protocol version===
This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes. For more information, see [https://stripe.com/docs/security#tls Stripe TLS Documentation].

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

===You passed an empty string for 'statement_descriptor'===
This indicates an empty '''Statement Descriptor''' field in the payment gateway configuration. Make certain that you set your entire [[#Setup|gateway configuration]].

===Bad Request===
This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe. To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab (which may display a more-informative error to administrators). Then, add the payment method again.

Customised or outdated system themes or order form templates can also cause this error. To troubleshoot this:

# Go to the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Select ''Six'' or ''Twenty-One'' for '''System Theme'''.
# Go to the '''[[Ordering Tab|Ordering]]''' tab.
# Select a '''[[Standard_Order_Form_Templates|Default Order Form Template]]'''.
# Click '''Save Changes'''.
# Return to the Client Area and refresh the page.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

===An unexpected error - No Stripe Payment Method found from token===
This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

This can also be caused by a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.
* If one is, the custom JavaScript will need to be corrected.
* If the JavaScript error is coming from a third-party customisation, contact the developer for assistance.

If the issue persists, contact our [https://www.whmcs.com/submit-a-ticket/ support team].

===Error Updating Remote Pay Method: Remote Storage Failed===
You can find information about this error at '''Billing > [[Gateway Log]]'''.

===Stripe India Accounts===
India-based Stripe accounts require the following additional conditions for a successful payment capture:

* The client's address and billing contact must use a valid Indian postal address.
* The payment card must be from an Indian bank.
* The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies upon payment in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
# Add <tt>INR</tt> as an [[Currencies#Adding.2FEditing_a_Currency|additional currency]].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Set '''Convert To For Processing''' on the Stripe gateway to ''INR''.

For more information about the additional Stripe requirements for Indian Stripe accounts, see [https://support.stripe.com/questions/requirements-for-india-export-charges Stripe's documentation].

{{modules}}

Plesk

2022-09-28T11:35:16Z

John: /* Adding a Plesk Server */

== About this Module ==

The Plesk module allows you to add and manage Plesk servers in WHMCS.

<div class="docs-alert-info">
* This module is compatible with Plesk versions 11, 11.5, 12, 12.5, Onyx, and Obsidian.
* You can also [[Plesk Single Sign-On|use single sign-on with Plesk]].
</div>
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 8443}}
== Adding a Plesk Server ==

To set up a Plesk server in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.
# Click '''Add New Server'''.
# Select ''Plesk'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Click '''Save Changes'''.
# If this is the only Plesk server that is currently in WHMCS, click on the name and ensure that it results in an asterisk (*) next to it. This indicates that it is the default to use when any other non-specific configuration doesn't apply.

For more information, see [https://help.whmcs.com/m/87388/l/1076210 Creating Your First Plesk Server] and [[Plesk Onyx]].

== Creating a Plesk Product ==

[[File:plesk12_3new.png|thumb|Creating a Plesk Product]]

You can create a product that provisions accounts on your Plesk server at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

=== Configurable Options ===

<div class="docs-alert-info">
* If you set up configurable options, you will also use Plesk's Panel Addons. This Plesk feature is '''not''' part of WHMCS's product addon system.
* A friendly name can be assigned to configurable options in order to display a different name to clients. This is sometimes preferable to displaying the system value as it appears inside Plesk. For more information, see [[Addons_and_Configurable_Options#Friendly_Display_Names|Friendly Display Names]].
</div>

[[File:Plesk_addons.png |thumb|Plesk Panel Addons]]
[[File:Plesk_config_opt_setup_8-2.png |thumb|WHMCS Plesk Configurable Options]]
[[File:WHMCS-plesk-extra-bandwidth-8-2.png |thumb|WHMCS Plesk Bandwidth Configurable Options]]

To create configurable options that attach Plesk's Panel Addons to your Plesk products:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
# Perform one of the following actions:
#* Click the '''Edit''' icon for an existing group.
#* Click '''Create a New Group''', configure the group name, description, and assigned products, and then click '''Save Changes'''.
# Click '''Add New Configurable Option'''.
# Enter an option name using the <tt>Plesk Panel-Addon-Name</tt> name format, replacing <tt>Panel-Addon-Name</tt> with the exact name that displays in Plesk for that Plesk Panel Addon. For example:
#* In the '''Plesk Panel Addons''' image above, one of the configured Panel Addons is '''Extra Bandwidth''', with resources of <tt>5GB</tt> or <tt>10GB</tt>.
#* In WHMCS in the '''WHMCS Plesk Configurable Options''' image above, this is '''Plesk Extra Bandwidth'''.
#* In the '''WHMCS Plesk Bandwidth Configurable Options''' image above, '''10GB Extra Bandwidth''' and '''5GB Extra Bandwidth''' are set to ensure that the bandwidth options in Plesk and WHMCS match.<div class="docs-alert-info">We recommend that you set the first option to '''None''' or a similar value. When you do this, ensure that the '''Panel Addon''' uses a value of <tt>0</tt>. This gives the user the ability to choose not to have any additional values per option.</div>
# Select ''Yes/No'' or ''Dropdown'' as the '''Option Type''' setting.
# Enter the desired options and display order.
# Click '''Save Changes'''.
# Create each desired additional option.
# Click '''Close Window'''.
# Select the desired products in the '''Assigned Products''' list.
# Click '''Save Changes'''.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.
# Edit the desired product or service.
# In the '''Configurable Options''' tab, select the desired options.
# Click '''Save Changes'''.

==== Dedicated IP Address ====

To create configurable options that provision a dedicated IP address, use either or both of these exact names when you create configurable options:

* <tt>Dedicated IPv4</tt>
* <tt>Dedicated IPv6</tt>

Select ''Yes/No'' from the '''Option Type''' menu for these options.

=== Add-On Features ===

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an '''Independent Product'''), you can create an '''Add-On Feature'''. These addons let you sell module-specific features like the WordPress Toolkit offerings available through both cPanel & WHM and Plesk.

For more information and steps to create an addon, see [[Product Addons]].

=== Reseller Packages ===

When creating a reseller package, create the service plan on your Plesk server in the '''Reseller Plans''' tab at '''Hosting Services > Service Plans'''.

When you configure the product in WHMCS, use the following settings:

* In the '''Details''' tab, set the '''Product Type''' setting to ''Reseller Account''.
* In the '''Module Settings''' tab, set the '''Service Plan Name''' ''and'' '''Reseller Plan Name''' settings.

Creating a reseller account will '''not''' create a shared hosting space for the reseller's website. After account creation, the reseller can log in to Plesk and set up their own hosting space.

===Metric Billing===

<div class="docs-alert-info"><i class="fa fa-info-circle"></i>We added metric billing for Plesk in WHMCS 8.5.</div>

You can bill clients for their use of individual items like databases or bandwidth. You can choose whether to include a certain amount in the base price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every unit of an item.

You can configure metric billing in the '''Metric Billing''' tab.

When a client orders this product, WHMCS will track the account's use of the items you configured. On the service's '''Next Due Date''', the system will record that period's usage and add the cost to the service's renewal invoice.

For more information, see [[Usage Billing]].

=== Log in to Plesk ===

When you click '''Log in to Plesk''' in the Client Area ''or'' Admin Area, WHMCS bases its actions on the server hostname if it is available. If it is not, WHMCS uses the IP address.

The use of <tt>http</tt> and <tt>https</tt> login links depends on the '''Secure''' setting in your server's configuration.

=== WHMCS Connect ===

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For more information, see [[WHMCS_Connect]].

== Troubleshooting ==

=== The client account is getting setup but the domain is not ===

This is usually due to the permissions of the domain template exceeding the server resources or containing something unsupported (for example, ColdFusion). Always test whether your domain template works directly in Plesk after setting it up.

=== I get a blank command error from WHMCS when it tries to setup an account ===

This can occur if your firewall is blocking connections on port 8443. You need to open it on both the server WHMCS is on and the server WHMCS is connecting to for inbound and outbound connections.

=== With accounts created on my Plesk server from WHMCS the www. subdomain doesn't work ===

This happens due to the default DNS settings on a Plesk server and the requirement to check a box when creating an account to enable it.

To avoid that, simply follow the steps below.
# Log in to Plesk.
# Click '''Server'''.
# Click '''DNS Settings'''.
# Click '''Add New Record'''.
# Choose '''CNAME''' under the record type.
# Enter <tt>www</tt> in '''Enter Domain Name'''.
# Enter <tt><domain></tt> in '''Enter Canonical Name'''.
# Click '''OK''' to complete the changes.

=== Page not Found/Timeout/502 Bad Gateway error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/213907285 Plesk's support article].

=== 503 Service Temporarily Unavailable error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/115003664213-Unable-to-create-domain-through-WHMCS-503-Service-Temporarily-Unavailable Plesk's support article].

===Unable to create account in Panel. The field 'username' is required.===

This means the username under the client's '''Products/Services''' tab is empty.

Enter a username, save changes, and try module creation again. Then, ensure that '''Require Domains''' is enabled for the product at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.

===0 - Unable to find appropriate manager for this version of Panel. Plesk should be at least 8.0 version===

This is a generic error message that the Plesk module returns. For example, it could indicate a connection error or invalid credentials.

To identify the underlying error that is occurring, check the '''Module Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Log'''. Enable it, reproduce the error, disable it again, and the ''''Response''' column will show the underlying error.

For more information, see [[Troubleshooting_Module_Problems]].

===1006 - Permission denied===

This indicates that your Plesk login doesn't have the necessary permissions to use the API. You need the server administrator to grant your Plesk reseller account the '''Ability to use remote API''' permission.

===1013 - Template does not exist===

This error message is coming directly from the Plesk API and indicates that the client and domain template names are incorrect or missing. You can correct these in the product's '''Module Settings''' tab.

===1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel===

There are two potential causes of this error message:

==== Incorrect product type ====

The product type is set incorrectly in WHMCS (for example, a reseller plan is configured as a shared hosting product in WHMCS).

To resolve this:

# Log in to WHMCS Admin Area.
# Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.
# Set '''Product Type''' to ''Shared Hosting'' or ''Reseller Hosting'' to match the Plesk plan type.
# Click '''Save Changes'''.

==== Missing data from a table inside Plesk ====

If the error persists after following the ''Incorrect product type'' steps above, see [https://support.plesk.com/hc/en-us/articles/213932225-Error-while-accessing-Plesk-from-WHMCS-via-API-Customer-with-external-id-whmcs-plesk-XX-is-not-found-in-panel this article].

===1013 - Error message: Customer with external id 'xxxxxxxx' is not found in panel===

Refer to the solution for [[#1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel|1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel]] above.

===1014 - Parser error: Request is invalid===

This error message indicates there is a field value missing. This is most commonly caused by having no assigned IP addresses in the client or domain template's IP pool.

===1014 - Parser error: Cannot parse the XML from the source specified===

The Plesk API only supports the characters a-z and 0-9. If the client's profile contains accents or other characters, it will cause account creation to fail. Edit the client's profile to remove these characters.

===1018 - Unable to create hosting. IP address does not exist in client's pool===

This error indicates that there is an issue with the IP address pool configuration in Plesk. For example, there may not be any available IP addresses or the first IP address may be set as dedicated instead of shared.

===1023 - Unable to accept the template: the following limitations are exceeded===

This issue occurs when the resources provided by the serivce plan addon were already used by the subscription.

To resolve this:

# In the subscription for that domain name, remove the referenced addon in Plesk.
# In WHMCS, go to the product or service's '''Products/Services''' tab.
# Use the "Upgrade/Downgrade" option to create an upgrade order.

===2306 - Domain adding was failed. Error: xxxxx template failed: Unable to apply limits===

This error message comes direct from the Plesk API. It indicates that the template you are attempting to use exceeds your limits or has a feature your server doesn't support. Create an account with the template inside Plesk to retrieve further details.

===Plesk login requires user authentication===

This issue can happen when the user has a dynamic IP addresses or an unstable internet connection. Selecting '''Allow IP changes during one session''' in Plesk [https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/session-preferences.60305/ will resolve this].

{{modules}}

Plesk

2022-09-28T11:34:52Z

John: /* Adding a Plesk 11 or Plesk 12 Server */

== About this Module ==

The Plesk module allows you to add and manage Plesk servers in WHMCS.

<div class="docs-alert-info">
* This module is compatible with Plesk versions 11, 11.5, 12, 12.5, Onyx, and Obsidian.
* You can also [[Plesk Single Sign-On|use single sign-on with Plesk]].
</div>
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 8443}}
== Adding a Plesk Server ==

To set up a Plesk 11 or Plesk 12 server in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.
# Click '''Add New Server'''.
# Select ''Plesk'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Click '''Save Changes'''.
# If this is the only Plesk server that is currently in WHMCS, click on the name and ensure that it results in an asterisk (*) next to it. This indicates that it is the default to use when any other non-specific configuration doesn't apply.

For more information, see [https://help.whmcs.com/m/87388/l/1076210 Creating Your First Plesk Server] and [[Plesk Onyx]].

== Creating a Plesk Product ==

[[File:plesk12_3new.png|thumb|Creating a Plesk Product]]

You can create a product that provisions accounts on your Plesk server at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

=== Configurable Options ===

<div class="docs-alert-info">
* If you set up configurable options, you will also use Plesk's Panel Addons. This Plesk feature is '''not''' part of WHMCS's product addon system.
* A friendly name can be assigned to configurable options in order to display a different name to clients. This is sometimes preferable to displaying the system value as it appears inside Plesk. For more information, see [[Addons_and_Configurable_Options#Friendly_Display_Names|Friendly Display Names]].
</div>

[[File:Plesk_addons.png |thumb|Plesk Panel Addons]]
[[File:Plesk_config_opt_setup_8-2.png |thumb|WHMCS Plesk Configurable Options]]
[[File:WHMCS-plesk-extra-bandwidth-8-2.png |thumb|WHMCS Plesk Bandwidth Configurable Options]]

To create configurable options that attach Plesk's Panel Addons to your Plesk products:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
# Perform one of the following actions:
#* Click the '''Edit''' icon for an existing group.
#* Click '''Create a New Group''', configure the group name, description, and assigned products, and then click '''Save Changes'''.
# Click '''Add New Configurable Option'''.
# Enter an option name using the <tt>Plesk Panel-Addon-Name</tt> name format, replacing <tt>Panel-Addon-Name</tt> with the exact name that displays in Plesk for that Plesk Panel Addon. For example:
#* In the '''Plesk Panel Addons''' image above, one of the configured Panel Addons is '''Extra Bandwidth''', with resources of <tt>5GB</tt> or <tt>10GB</tt>.
#* In WHMCS in the '''WHMCS Plesk Configurable Options''' image above, this is '''Plesk Extra Bandwidth'''.
#* In the '''WHMCS Plesk Bandwidth Configurable Options''' image above, '''10GB Extra Bandwidth''' and '''5GB Extra Bandwidth''' are set to ensure that the bandwidth options in Plesk and WHMCS match.<div class="docs-alert-info">We recommend that you set the first option to '''None''' or a similar value. When you do this, ensure that the '''Panel Addon''' uses a value of <tt>0</tt>. This gives the user the ability to choose not to have any additional values per option.</div>
# Select ''Yes/No'' or ''Dropdown'' as the '''Option Type''' setting.
# Enter the desired options and display order.
# Click '''Save Changes'''.
# Create each desired additional option.
# Click '''Close Window'''.
# Select the desired products in the '''Assigned Products''' list.
# Click '''Save Changes'''.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.
# Edit the desired product or service.
# In the '''Configurable Options''' tab, select the desired options.
# Click '''Save Changes'''.

==== Dedicated IP Address ====

To create configurable options that provision a dedicated IP address, use either or both of these exact names when you create configurable options:

* <tt>Dedicated IPv4</tt>
* <tt>Dedicated IPv6</tt>

Select ''Yes/No'' from the '''Option Type''' menu for these options.

=== Add-On Features ===

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an '''Independent Product'''), you can create an '''Add-On Feature'''. These addons let you sell module-specific features like the WordPress Toolkit offerings available through both cPanel & WHM and Plesk.

For more information and steps to create an addon, see [[Product Addons]].

=== Reseller Packages ===

When creating a reseller package, create the service plan on your Plesk server in the '''Reseller Plans''' tab at '''Hosting Services > Service Plans'''.

When you configure the product in WHMCS, use the following settings:

* In the '''Details''' tab, set the '''Product Type''' setting to ''Reseller Account''.
* In the '''Module Settings''' tab, set the '''Service Plan Name''' ''and'' '''Reseller Plan Name''' settings.

Creating a reseller account will '''not''' create a shared hosting space for the reseller's website. After account creation, the reseller can log in to Plesk and set up their own hosting space.

===Metric Billing===

<div class="docs-alert-info"><i class="fa fa-info-circle"></i>We added metric billing for Plesk in WHMCS 8.5.</div>

You can bill clients for their use of individual items like databases or bandwidth. You can choose whether to include a certain amount in the base price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every unit of an item.

You can configure metric billing in the '''Metric Billing''' tab.

When a client orders this product, WHMCS will track the account's use of the items you configured. On the service's '''Next Due Date''', the system will record that period's usage and add the cost to the service's renewal invoice.

For more information, see [[Usage Billing]].

=== Log in to Plesk ===

When you click '''Log in to Plesk''' in the Client Area ''or'' Admin Area, WHMCS bases its actions on the server hostname if it is available. If it is not, WHMCS uses the IP address.

The use of <tt>http</tt> and <tt>https</tt> login links depends on the '''Secure''' setting in your server's configuration.

=== WHMCS Connect ===

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For more information, see [[WHMCS_Connect]].

== Troubleshooting ==

=== The client account is getting setup but the domain is not ===

This is usually due to the permissions of the domain template exceeding the server resources or containing something unsupported (for example, ColdFusion). Always test whether your domain template works directly in Plesk after setting it up.

=== I get a blank command error from WHMCS when it tries to setup an account ===

This can occur if your firewall is blocking connections on port 8443. You need to open it on both the server WHMCS is on and the server WHMCS is connecting to for inbound and outbound connections.

=== With accounts created on my Plesk server from WHMCS the www. subdomain doesn't work ===

This happens due to the default DNS settings on a Plesk server and the requirement to check a box when creating an account to enable it.

To avoid that, simply follow the steps below.
# Log in to Plesk.
# Click '''Server'''.
# Click '''DNS Settings'''.
# Click '''Add New Record'''.
# Choose '''CNAME''' under the record type.
# Enter <tt>www</tt> in '''Enter Domain Name'''.
# Enter <tt><domain></tt> in '''Enter Canonical Name'''.
# Click '''OK''' to complete the changes.

=== Page not Found/Timeout/502 Bad Gateway error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/213907285 Plesk's support article].

=== 503 Service Temporarily Unavailable error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/115003664213-Unable-to-create-domain-through-WHMCS-503-Service-Temporarily-Unavailable Plesk's support article].

===Unable to create account in Panel. The field 'username' is required.===

This means the username under the client's '''Products/Services''' tab is empty.

Enter a username, save changes, and try module creation again. Then, ensure that '''Require Domains''' is enabled for the product at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.

===0 - Unable to find appropriate manager for this version of Panel. Plesk should be at least 8.0 version===

This is a generic error message that the Plesk module returns. For example, it could indicate a connection error or invalid credentials.

To identify the underlying error that is occurring, check the '''Module Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Log'''. Enable it, reproduce the error, disable it again, and the ''''Response''' column will show the underlying error.

For more information, see [[Troubleshooting_Module_Problems]].

===1006 - Permission denied===

This indicates that your Plesk login doesn't have the necessary permissions to use the API. You need the server administrator to grant your Plesk reseller account the '''Ability to use remote API''' permission.

===1013 - Template does not exist===

This error message is coming directly from the Plesk API and indicates that the client and domain template names are incorrect or missing. You can correct these in the product's '''Module Settings''' tab.

===1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel===

There are two potential causes of this error message:

==== Incorrect product type ====

The product type is set incorrectly in WHMCS (for example, a reseller plan is configured as a shared hosting product in WHMCS).

To resolve this:

# Log in to WHMCS Admin Area.
# Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.
# Set '''Product Type''' to ''Shared Hosting'' or ''Reseller Hosting'' to match the Plesk plan type.
# Click '''Save Changes'''.

==== Missing data from a table inside Plesk ====

If the error persists after following the ''Incorrect product type'' steps above, see [https://support.plesk.com/hc/en-us/articles/213932225-Error-while-accessing-Plesk-from-WHMCS-via-API-Customer-with-external-id-whmcs-plesk-XX-is-not-found-in-panel this article].

===1013 - Error message: Customer with external id 'xxxxxxxx' is not found in panel===

Refer to the solution for [[#1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel|1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel]] above.

===1014 - Parser error: Request is invalid===

This error message indicates there is a field value missing. This is most commonly caused by having no assigned IP addresses in the client or domain template's IP pool.

===1014 - Parser error: Cannot parse the XML from the source specified===

The Plesk API only supports the characters a-z and 0-9. If the client's profile contains accents or other characters, it will cause account creation to fail. Edit the client's profile to remove these characters.

===1018 - Unable to create hosting. IP address does not exist in client's pool===

This error indicates that there is an issue with the IP address pool configuration in Plesk. For example, there may not be any available IP addresses or the first IP address may be set as dedicated instead of shared.

===1023 - Unable to accept the template: the following limitations are exceeded===

This issue occurs when the resources provided by the serivce plan addon were already used by the subscription.

To resolve this:

# In the subscription for that domain name, remove the referenced addon in Plesk.
# In WHMCS, go to the product or service's '''Products/Services''' tab.
# Use the "Upgrade/Downgrade" option to create an upgrade order.

===2306 - Domain adding was failed. Error: xxxxx template failed: Unable to apply limits===

This error message comes direct from the Plesk API. It indicates that the template you are attempting to use exceeds your limits or has a feature your server doesn't support. Create an account with the template inside Plesk to retrieve further details.

===Plesk login requires user authentication===

This issue can happen when the user has a dynamic IP addresses or an unstable internet connection. Selecting '''Allow IP changes during one session''' in Plesk [https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/session-preferences.60305/ will resolve this].

{{modules}}

Plesk

2022-09-28T11:34:40Z

John: /* Adding a Plesk 11 or Plesk 12 Server */

== About this Module ==

The Plesk module allows you to add and manage Plesk servers in WHMCS.

<div class="docs-alert-info">
* This module is compatible with Plesk versions 11, 11.5, 12, 12.5, Onyx, and Obsidian.
* You can also [[Plesk Single Sign-On|use single sign-on with Plesk]].
</div>
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 8443}}
== Adding a Plesk 11 or Plesk 12 Server ==

To set up a Plesk 11 or Plesk 12 server in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.
# Click '''Add New Server'''.
# Select ''Plesk'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Click '''Save Changes'''.
# If this is the only Plesk server that is currently in WHMCS, click on the name and ensure that it results in an asterisk (*) next to it. This indicates that it is the default to use when any other non-specific configuration doesn't apply.

For more information, see [https://help.whmcs.com/m/87388/l/1076210 Creating Your First Plesk Server] and [[Plesk Onyx]].

== Creating a Plesk Product ==

[[File:plesk12_3new.png|thumb|Creating a Plesk Product]]

You can create a product that provisions accounts on your Plesk server at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

=== Configurable Options ===

<div class="docs-alert-info">
* If you set up configurable options, you will also use Plesk's Panel Addons. This Plesk feature is '''not''' part of WHMCS's product addon system.
* A friendly name can be assigned to configurable options in order to display a different name to clients. This is sometimes preferable to displaying the system value as it appears inside Plesk. For more information, see [[Addons_and_Configurable_Options#Friendly_Display_Names|Friendly Display Names]].
</div>

[[File:Plesk_addons.png |thumb|Plesk Panel Addons]]
[[File:Plesk_config_opt_setup_8-2.png |thumb|WHMCS Plesk Configurable Options]]
[[File:WHMCS-plesk-extra-bandwidth-8-2.png |thumb|WHMCS Plesk Bandwidth Configurable Options]]

To create configurable options that attach Plesk's Panel Addons to your Plesk products:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
# Perform one of the following actions:
#* Click the '''Edit''' icon for an existing group.
#* Click '''Create a New Group''', configure the group name, description, and assigned products, and then click '''Save Changes'''.
# Click '''Add New Configurable Option'''.
# Enter an option name using the <tt>Plesk Panel-Addon-Name</tt> name format, replacing <tt>Panel-Addon-Name</tt> with the exact name that displays in Plesk for that Plesk Panel Addon. For example:
#* In the '''Plesk Panel Addons''' image above, one of the configured Panel Addons is '''Extra Bandwidth''', with resources of <tt>5GB</tt> or <tt>10GB</tt>.
#* In WHMCS in the '''WHMCS Plesk Configurable Options''' image above, this is '''Plesk Extra Bandwidth'''.
#* In the '''WHMCS Plesk Bandwidth Configurable Options''' image above, '''10GB Extra Bandwidth''' and '''5GB Extra Bandwidth''' are set to ensure that the bandwidth options in Plesk and WHMCS match.<div class="docs-alert-info">We recommend that you set the first option to '''None''' or a similar value. When you do this, ensure that the '''Panel Addon''' uses a value of <tt>0</tt>. This gives the user the ability to choose not to have any additional values per option.</div>
# Select ''Yes/No'' or ''Dropdown'' as the '''Option Type''' setting.
# Enter the desired options and display order.
# Click '''Save Changes'''.
# Create each desired additional option.
# Click '''Close Window'''.
# Select the desired products in the '''Assigned Products''' list.
# Click '''Save Changes'''.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.
# Edit the desired product or service.
# In the '''Configurable Options''' tab, select the desired options.
# Click '''Save Changes'''.

==== Dedicated IP Address ====

To create configurable options that provision a dedicated IP address, use either or both of these exact names when you create configurable options:

* <tt>Dedicated IPv4</tt>
* <tt>Dedicated IPv6</tt>

Select ''Yes/No'' from the '''Option Type''' menu for these options.

=== Add-On Features ===

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an '''Independent Product'''), you can create an '''Add-On Feature'''. These addons let you sell module-specific features like the WordPress Toolkit offerings available through both cPanel & WHM and Plesk.

For more information and steps to create an addon, see [[Product Addons]].

=== Reseller Packages ===

When creating a reseller package, create the service plan on your Plesk server in the '''Reseller Plans''' tab at '''Hosting Services > Service Plans'''.

When you configure the product in WHMCS, use the following settings:

* In the '''Details''' tab, set the '''Product Type''' setting to ''Reseller Account''.
* In the '''Module Settings''' tab, set the '''Service Plan Name''' ''and'' '''Reseller Plan Name''' settings.

Creating a reseller account will '''not''' create a shared hosting space for the reseller's website. After account creation, the reseller can log in to Plesk and set up their own hosting space.

===Metric Billing===

<div class="docs-alert-info"><i class="fa fa-info-circle"></i>We added metric billing for Plesk in WHMCS 8.5.</div>

You can bill clients for their use of individual items like databases or bandwidth. You can choose whether to include a certain amount in the base price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every unit of an item.

You can configure metric billing in the '''Metric Billing''' tab.

When a client orders this product, WHMCS will track the account's use of the items you configured. On the service's '''Next Due Date''', the system will record that period's usage and add the cost to the service's renewal invoice.

For more information, see [[Usage Billing]].

=== Log in to Plesk ===

When you click '''Log in to Plesk''' in the Client Area ''or'' Admin Area, WHMCS bases its actions on the server hostname if it is available. If it is not, WHMCS uses the IP address.

The use of <tt>http</tt> and <tt>https</tt> login links depends on the '''Secure''' setting in your server's configuration.

=== WHMCS Connect ===

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For more information, see [[WHMCS_Connect]].

== Troubleshooting ==

=== The client account is getting setup but the domain is not ===

This is usually due to the permissions of the domain template exceeding the server resources or containing something unsupported (for example, ColdFusion). Always test whether your domain template works directly in Plesk after setting it up.

=== I get a blank command error from WHMCS when it tries to setup an account ===

This can occur if your firewall is blocking connections on port 8443. You need to open it on both the server WHMCS is on and the server WHMCS is connecting to for inbound and outbound connections.

=== With accounts created on my Plesk server from WHMCS the www. subdomain doesn't work ===

This happens due to the default DNS settings on a Plesk server and the requirement to check a box when creating an account to enable it.

To avoid that, simply follow the steps below.
# Log in to Plesk.
# Click '''Server'''.
# Click '''DNS Settings'''.
# Click '''Add New Record'''.
# Choose '''CNAME''' under the record type.
# Enter <tt>www</tt> in '''Enter Domain Name'''.
# Enter <tt><domain></tt> in '''Enter Canonical Name'''.
# Click '''OK''' to complete the changes.

=== Page not Found/Timeout/502 Bad Gateway error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/213907285 Plesk's support article].

=== 503 Service Temporarily Unavailable error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/115003664213-Unable-to-create-domain-through-WHMCS-503-Service-Temporarily-Unavailable Plesk's support article].

===Unable to create account in Panel. The field 'username' is required.===

This means the username under the client's '''Products/Services''' tab is empty.

Enter a username, save changes, and try module creation again. Then, ensure that '''Require Domains''' is enabled for the product at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.

===0 - Unable to find appropriate manager for this version of Panel. Plesk should be at least 8.0 version===

This is a generic error message that the Plesk module returns. For example, it could indicate a connection error or invalid credentials.

To identify the underlying error that is occurring, check the '''Module Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Log'''. Enable it, reproduce the error, disable it again, and the ''''Response''' column will show the underlying error.

For more information, see [[Troubleshooting_Module_Problems]].

===1006 - Permission denied===

This indicates that your Plesk login doesn't have the necessary permissions to use the API. You need the server administrator to grant your Plesk reseller account the '''Ability to use remote API''' permission.

===1013 - Template does not exist===

This error message is coming directly from the Plesk API and indicates that the client and domain template names are incorrect or missing. You can correct these in the product's '''Module Settings''' tab.

===1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel===

There are two potential causes of this error message:

==== Incorrect product type ====

The product type is set incorrectly in WHMCS (for example, a reseller plan is configured as a shared hosting product in WHMCS).

To resolve this:

# Log in to WHMCS Admin Area.
# Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.
# Set '''Product Type''' to ''Shared Hosting'' or ''Reseller Hosting'' to match the Plesk plan type.
# Click '''Save Changes'''.

==== Missing data from a table inside Plesk ====

If the error persists after following the ''Incorrect product type'' steps above, see [https://support.plesk.com/hc/en-us/articles/213932225-Error-while-accessing-Plesk-from-WHMCS-via-API-Customer-with-external-id-whmcs-plesk-XX-is-not-found-in-panel this article].

===1013 - Error message: Customer with external id 'xxxxxxxx' is not found in panel===

Refer to the solution for [[#1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel|1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel]] above.

===1014 - Parser error: Request is invalid===

This error message indicates there is a field value missing. This is most commonly caused by having no assigned IP addresses in the client or domain template's IP pool.

===1014 - Parser error: Cannot parse the XML from the source specified===

The Plesk API only supports the characters a-z and 0-9. If the client's profile contains accents or other characters, it will cause account creation to fail. Edit the client's profile to remove these characters.

===1018 - Unable to create hosting. IP address does not exist in client's pool===

This error indicates that there is an issue with the IP address pool configuration in Plesk. For example, there may not be any available IP addresses or the first IP address may be set as dedicated instead of shared.

===1023 - Unable to accept the template: the following limitations are exceeded===

This issue occurs when the resources provided by the serivce plan addon were already used by the subscription.

To resolve this:

# In the subscription for that domain name, remove the referenced addon in Plesk.
# In WHMCS, go to the product or service's '''Products/Services''' tab.
# Use the "Upgrade/Downgrade" option to create an upgrade order.

===2306 - Domain adding was failed. Error: xxxxx template failed: Unable to apply limits===

This error message comes direct from the Plesk API. It indicates that the template you are attempting to use exceeds your limits or has a feature your server doesn't support. Create an account with the template inside Plesk to retrieve further details.

===Plesk login requires user authentication===

This issue can happen when the user has a dynamic IP addresses or an unstable internet connection. Selecting '''Allow IP changes during one session''' in Plesk [https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/session-preferences.60305/ will resolve this].

{{modules}}

Template:Registrar

2022-09-20T09:43:49Z

John:

<includeonly>
{{#if:{{{notitle|}}}||==Supported Features==}}
{| class="wikitable" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;"
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Register
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Transfer
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Renew
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Registrar Lock
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{register|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{register|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{transfer|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{transfer|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{renew|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{renew|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{lock|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{lock|}}}|Yes|No}}
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Update Nameservers
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Update WHOIS
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Get EPP Code
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Register Nameservers
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{dns|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{dns|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{whois|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{whois|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{getepp|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{getepp|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{regns|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{regns|}}}|Yes|No}}
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| DNS Record Management
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Email Forwarding
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Domain Release
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Domain Sync Script
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{dnsmanagement|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{dnsmanagement|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{emailforwarding|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{emailforwarding|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{domainrelease|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{domainrelease|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{domainsync|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{domainsync|}}}|Yes|No}}
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Premium Domains
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Transfer Out Automation
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| TLD Pricing Sync
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{premium|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{premium|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{transferout|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{transferout|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{tldpricingsync|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{tldpricingsync|}}}|Yes|No}}
|}</includeonly><noinclude>
Registrar features grid template, produces something like:
{{registrar
| register = yes
| transfer = yes
| renew = yes
| dns = yes
| getepp = yes
| premium = yes
| tldpricingsync = yes
}}
To use:
<nowiki>{{registrar</nowiki>
| register = yes
| transfer = yes
| renew = yes
| dns = yes
| getepp = yes
| premium = yes
| tldpricingsync = yes
<nowiki>}}</nowiki>

You should '''only''' provide the options that the registrar supports. For example, saying 'whois = no' would not have worked.

Full list of options (case sensitive):
* register
* transfer
* renew
* dns
* whois
* getepp
* regns
* dnsmanagement
* emailforwarding
* domainrelease
* domainsync
* premium
* transferout
</noinclude>

Template:Registrar

2022-09-20T09:43:10Z

John:

<includeonly>
{{#if:{{{notitle|}}}||==Supported Features==}}
{| class="wikitable" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;"
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Register
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Transfer
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Renew
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Registrar Lock
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{register|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{register|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{transfer|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{transfer|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{renew|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{renew|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{lock|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{lock|}}}|Yes|No}}
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Update Nameservers
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Update WHOIS
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Get EPP Code
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Register Nameservers
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{dns|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{dns|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{whois|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{whois|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{getepp|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{getepp|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{regns|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{regns|}}}|Yes|No}}
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| DNS Record Management
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Email Forwarding
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Domain Release
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Domain Sync Script
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{dnsmanagement|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{dnsmanagement|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{emailforwarding|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{emailforwarding|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{domainrelease|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{domainrelease|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{domainsync|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{domainsync|}}}|Yes|No}}
|-
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Premium Domains
!style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;"| Transfer Out Automation
|-
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{premium|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{premium|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{transferout|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{transferout|}}}|Yes|No}}
|style="border:1px #AAA solid;padding:0.2em;{{#if:{{{tldpricingsync|}}}|color:darkgreen;|color:red;}}"| {{#if:{{{tldpricingsync|}}}|Yes|No}}
|}</includeonly><noinclude>
Registrar features grid template, produces something like:
{{registrar
| register = yes
| transfer = yes
| renew = yes
| dns = yes
| getepp = yes
| premium = yes
| tldpricingsync = yes
}}
To use:
<nowiki>{{registrar</nowiki>
| register = yes
| transfer = yes
| renew = yes
| dns = yes
| getepp = yes
| premium = yes
| tldpricingsync = yes
<nowiki>}}</nowiki>

You should '''only''' provide the options that the registrar supports. For example, saying 'whois = no' would not have worked.

Full list of options (case sensitive):
* register
* transfer
* renew
* dns
* whois
* getepp
* regns
* dnsmanagement
* emailforwarding
* domainrelease
* domainsync
* premium
* transferout
</noinclude>

Promotions

2022-08-26T10:13:21Z

John: /* Prerequisites */

Promotions can offer discounts on your products and services, product addons, and domains.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Promotions''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''

For information on setting up commonly-used promotions, see [[Common Promotions]].

==Types of promotions that can be offered==

*One Time Discounts
*Recurring Discounts
*Limited Recurring Discounts (for example, first two months free)
*Monetary Discounts (for example, $5 Off)
*Percentage Discounts (for example, 20% Off)
*Price Override (for example, Regular price $10, Discount price $8)
*Free Setup
*Apply to Specific Products/Addons/Domain TLDs
*Apply to Specific Billing Cycles or Registration Periods
*Apply Once per Order or to All Applicable Items in Cart
*Lifetime Promotion
*Valid for New Signups Only
*Valid for upgrade orders only

==How to create a new promotion==

To create a new promotion:

# Click '''Add New''' at the top of the page.
# Enter a promotion code. This is the code that customers will need to enter on the order form to receive the discount.
# Choose one of the four promotion types:
#* Percentage — Discount by a percentage of the original price.
#* Fixed Amount — Discount a specified amount from the original price.
#* Price Override — Changes the product price to this value. Use this to offer a consistent discount across multiple billing cycles.
#* Free Setup — Discount any setup fee from the original price.
# To have the discount only apply to the first invoice, do not check '''Recurring'''.
#* When you check this, the discount will apply to renewal invoices.
#* Set '''Recur For''' to <tt>0</tt> for all future renewals to discount, or enter a different number to specify how many cycles the discount lasts for. This is in addition to the initial invoice for the product. If you wish to provide a discount 6 times, enter <tt>5</tt> in the recurring box.
# For '''Value''', enter the amount of the discount in positive numbers (up to 2 decimals) only.
# Select the products, addons, and domain TLDs that the promotion applies to and what billing cycles or registration periods the discount requires. These should match those of your products. Your can press <tt>Ctrl+click</tt> to select multiple entries.
# Optionally, set the start and expiration dates. If you use one or both of these settings, the coupon will only start working after the start date and will stop working at expiration.
# Use the following checkboxes to specify who can use the promotion:
#* Apply Once — If the client orders multiple qualifying products, the system only applies the discount once.
#* New Signups — Only new clients can use the promotion.
#* Apply Once / Client — If a client has an existing active order that uses this promotion, they will not be able to use the code a second time.
#* Lifetime Promotion — Client will retain this discount even if they upgrade or downgrade their service in future, regardless of settings such as maximum uses or expiration date.
#* Existing Client — Only existing clients with one or more active orders can use the promotion.
#* Enable for product upgrades – See [[#Upgrades/Downgrades|Upgrades/Downgrades]] below.
# In the admin notes section, add information that admins may need about the promotion.

The promotion code changes the '''First Payment Amount''' when a customer or administrator uses the code while ordering. It does not change the '''Recurring Amount'''. If it did automatically update the recurring amount, this would prevent administrators from being able to manually update the recurring amount value when a promotion code was in use.

Instead, the system uses the promotion code to discount the '''Recurring Amount''' automatically on renewal invoices.

==Limiting Usage==

You can set the maximum number of times to honor a promotion. To do this:

# Locate the promotion you want to limit the usage of and click the edit icon next to it.
# For '''Maximum Uses''', enter the number of uses that you want to allow.
#* The number of times that customers have used the promotion will display below this setting.
#* For unlimited uses, enter <tt>0</tt>.
# Click '''Save Changes'''.

==Prerequisites==

By selecting products from '''Requires''', you can stipulate which products or services the client must also have in their shopping cart before applying the discount. You can use this to offer "buy x get y half price" promotions.

'''Also allow existing products in account to qualify for promotion''' allows the system to include active products that the client already owns in the promotion criteria.

For example, if the client already owns product x with an '''Active''' service status, they would be able to use the promotion code when ordering product y. If you disable this option, the client would need to order both products x and y at the same time to qualify.

==Upgrades/Downgrades==

When you check this checkbox, the client will use the promo code when placing an upgrade or downgrade order, which is particularly useful for offering incentives when upselling. When you check this, some new options will appear:

===Products/Services===

Select ''Products/Services'' as the '''Upgrade Type'''.

Use '''Type''', '''Recurring''', and '''Value''' fields to specify the value of the discount and how long it lasts.

Use '''Applies To''' to select which products to apply the promotional code to. The client will receive the discount when upgrading to this product.

For upgrades and downgrades, use '''Requires''' slightly differently. It restricts which products clients can upgrade. For example, they can upgrade from a selected product to this product and receive a discount, but not upgrade from an unselected product and receive a discount.

===Configurable Options===

To offer discounts to clients for configurable options, select ''Configurable Options'' as the '''Upgrade Type'''.

Use '''Upgrade Discount''' to specify the discount value as a percentage or fixed amount for the configurable options. Then, use '''Config Options Upgrades''' to select which option this discount applies to.

If you use the main '''Type''', '''Recurring''', and '''Value''' at the top of the page, the system will apply a discount to the parent product as well as to the configurable option. Leave this blank to only apply the discount to the configurable option.

==Promotion Links==

You can give links to users that will automatically apply a certain promotion code to their order if it applies. To do that, use a link like the one below:

cart.php?promocode=TEST '''OR''' cart.php?a=add&pid=1&promocode=TEST

Both of the above will apply the promotion code <tt>TEST</tt> to the order. With the first link, the user can choose the package they want. With the second, they will go straight to step 2 of the order process with product ID <tt>1</tt> selected.

For more information, see [[Linking to WHMCS]].

==Management==

When you create a promotion, you can specify an expiry date. If you want the promotion code to become invalid before this date, click '''Expire Now'''.

You can create a copy of any promotion by clicking '''Duplicate Promotion'''. This is particularly useful for quickly running a successful promotion again or providing a personalised promo code to a client.

==Manually Applying a Promotion==

WHMCS allows you to manually add a promotion code to an existing service. You can make this type of addition when viewing a client’s existing service in the Admin Area.

Click '''Promotion Code''' for a list of all the active promotions on the installation. From this list, you can select the promotion you would like to apply to the service, and then click '''Save Changes''' to commit your changes.

'''Recurring Amount''' on the service page is the final amount to bill the client for after taking the selected promotion into consideration. Selecting a promotion code by itself will not change the invoice amount.

Due to this behavior, it is important to update '''Recurring Amount''' so that it reflects the amount you want the customer to pay after applying the promotion code. You can do this in one of two ways:

* Manually calculate the amount that you would like the customer to pay after the discount and enter it in '''Recurring Amount'''. Then, click '''Save Changes'''.
* Select '''Auto Recalculate on Save''', and then click '''Save Changes'''. This option will have WHMCS take the current pricing for the product or service, apply the discount from the selected promotion code, and then set '''Recurring Amount''' for that value.

For client services with a promotion code, WHMCS alters how it generates the service’s invoice items for renewal invoices.

To provide the client with information concerning discounts from promotion codes, WHMCS will generate two invoice items. The first item will display the sum of '''Recurring Amount''' and the discount amount. The second item will display the discount amount.

As an example, if you have a service with a '''Recurring Amount''' of <tt>10.00</tt> and apply a promotion code that offers a 50% discount, then the system will generate the following invoice items when the service renews:

* Invoice Item for Service Renewal: 20.00
* Promotion Code (50% Off): -10.00
* Invoice Total: 10.00

This is the recommended method to convey a discount to clients.

If you had this same service with no promotion code, then the system would generate the following invoice items upon renewal instead:

* Invoice Item for Service Renewal: 10.00
* Invoice Total: 10.00

Both invoices result in a charge of 10.00, however one shows the client that they are paying this price because of a promotion code.

If you want to provide the client with a discount, but not create a promotion code invoice item, then you could do this by either manually specifying a '''Price Override''' value when creating the order, or by modifying '''Recurring Amount'''.

==Notes==

===Limited Recurring Promotions===

The system counts the number of recurrences for a Limited Recurring promotion (which are configured using the '''Recur For x Times''' setting) by looking at the invoice line items for the service. By looking at the number of invoice line items for a service, WHMCS makes a determination for how many times it has applied the promotional discount.

After the system has used all of a promotion code's recurrences for a given service, the service will revert to the standard price automatically.

If you wish to provide an an extension of the promotion, it would be necessary to increase '''Times''' in the promotion code configuration. This will apply to all existing services using this promo code, instantly. Deleting invoices will not extend the duration of the promotional discount.

===Fixed Amount Promotions and Additional Currencies===
When defining the value for a '''Fixed Amount''' promotion, it is important to note that this value applies to the base currency. For example, if the installation's '''Base Currency''' is ''USD'', then setting the '''Value''' for a '''Fixed Amount''' promotion to 100 will provide a discount of $100.00 USD when customers use it.

If the installation has additional currencies beyond the base currency, the system will use '''Base Conversion Rate''' to determine the discount for customers using these additional currencies.

For more information, see [[Currencies]].

===Create Custom Promo===

'''Create Custom Promo''' displays next to '''Promotion''' when you manually add a new order via '''Add Order''' in the Admin Area.

Clicking this button displays a modal that allows you to specify a custom promotion code that the system will automatically create and apply to the immediate order.

Use of this feature requires that the Administrator User have both '''Use Any Promotion Code on Order''' and '''Create/Edit Promotions''' as permissions. For more about permissions, see [[Administrators_and_Permissions|Administrators and Permissions]].

=== Services With Metric Billing Enabled ===

When the system applies a recurring promotion or discount to a product or service for which metric billing enabled, '''only''' the cost of the base product will be eligible for the discount.

Any usage (metric) charge that the recurring invoice includes '''will not''' receive the promotion or discount.

Maximising Performance

2022-08-25T08:05:44Z

John: /* MySQL® */

If you grow to have a large client base, page loads may become slower. This is because the more data you have, the larger the database becomes, and so calculating and looping through the data will naturally take longer.

The following steps can help you maintain faster speeds:

==Software Related==

=== Disable Ticket Counts ===

When you have a lot of tickets, calculating the number of tickets per status to display each time you open a ticket can slow things down.

To avoid that, disable the ticket counts by adding the following line to your WHMCS <tt>configuration.php</tt> file:

<div class="source-cli">
$disable_admin_ticket_page_counts = true;
</div>

=== Logging ===

In WHMCS, you can enable logging for, for example, SQL errors, hooks loading, or module commands.

The following settings control debug logging:

* '''SQL Error Reporting''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* '''Hooks Debug''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* '''Module Debug Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Debug Log'''.

Make sure to disable these when you are not actively debugging an issue, since they can and will increase the database size exponentially.

=== Customizations ===

Third party customizations can slow the performance of WHMCS. Ensure that any customization (for example, hooks and addons) that you are using is up-to-date and works with the version of WHMCS you are running.

=== Database Backups ===

The database backup process can be CPU, memory, and disk intensive while the entire database is exported, compressed, and uploaded or emailed. If performance issues are observed at the same time every day during the database backup process, this could be a potential cause.

For more information, see [[Backups#Limitations|Backups]].

==Server Related==

=== Email Provider ===

Long loading times when performing an action involving sending an email (for example, placing an order, opening or replying to a support ticket, or publishing an invoice) are often caused by connection issues to the chosen email provider.

To diagnose and resolve this, see [https://help.whmcs.com/m/troubleshooting/l/1261469-troubleshooting-email-sending-problems Troubleshooting Email Problems].

Consider switching to an external mail provider such as MailGun, SendGrid or SparkPost, as these are often more performant than SMTP systems. For further information see [[Mail_Tab#Configuring_a_Mail_Provider_in_WHMCS_8.0_and_later|Configuring a Mail Provider]].

=== MySQL® ===

WHMCS performance is largely dependent on a correct MySQL® configuration, especially for larger databases. Make any changes to the server's <tt>my.cnf</tt> file under the <tt>mysqld</tt> section, usually in <tt>/etc/my.cnf</tt> (cPanel servers and most others).

* As a starting point, set <tt>max_connections</tt> to a low value like <tt>50</tt> and increase based on the available RAM.
* When you are configuring this and the following other important settings, restart MySQL and let it run for 48 hours:
** <tt>wait_timeout</tt> (at least 300, so MySQL doesn't drop connections too soon)
** <tt>sort_buffer_size</tt> (2–4 MB)
** <tt>read_buffer_size</tt> (2–4 MB)
** <tt>max_allowed_packet</tt> (16 MB)

=== System Tweaks ===

WHMCS is a PHP MySQL script, and so the more RAM or SWAP memory and raw processing power you have at your disposal, the better the performance from your installation.

* For more information, see [[System Requirements]].
* We recommend using the higher set values and modules under the '''Recommended Settings''' for best results.

Directory Refresh Guide

2022-08-23T13:25:50Z

John: Redirected page to Contents

#REDIRECT [[Contents]]

Content goes here

Directory Refresh Guide

2022-08-23T13:25:36Z

John:

Content goes here

#REDIRECT [[Contents]]

Directory Refresh Guide

2022-08-23T13:24:35Z

John: Redirected page to Contents

#REDIRECT [[Contents]]

Directory Refresh Guide

2022-08-23T13:24:17Z

John: Created page with "#REDIRECT [[]]"

#REDIRECT [[]]

Products Management

2022-08-19T11:42:01Z

John: /* Clients Self Service */

WHMCS allows you to offer many different types of products and services, both with or without automation, and to create addons and other additional items to tailor those products and services to your clients' needs.

==Ordering Products and Services==

[[File:Admin-order-form.png|800px]]

To order new products and services for a client:

# Go to '''Orders > Add New Order''' or click '''Add New Order''' in the client profile.
# Begin entering the client details to select the client (if the system didn't already preselect them).
# Choose the payment method to use for the order and any resulting invoice.
# Select a promotion code to apply to the order items (if applicable).
# Choose the order status. Unless this is for adding an existing service that needs no provisioning, leave it as pending so that you can review the order after payment and ensure any provisioning was successful.
# Select one of the following options:
#*Order Confirmation — Keep this selected if you wish to send the Order Confirmation email to the client.
#*Generate Invoice — Keep this selected if you wish to generate an invoice for the items on the order. This is useful if you are placing an order for a new service on the client's behalf or you will to manually enter an existing service but still want to invoice them right away.
#*Send Email — Keep this selected if you wish to send the Invoice Created email whenever the system creates an invoice.
# Enter and select the details for each product you want to add to the order, including a domain name, billing cycle, quantity, and any pricing overrides.
#* Click '''Add New Product''' to add multiple products to the order.
#* If the billing cycle and price override fields have not changed, the system will use the pricing from the shortest configured billing cycle.
#* Use the '''Quantity''' option to order multiples of a single product that doesn't require any specific configuration on the initial order (such as a domain name and configurable options). For example, if you are selling a software license using our Licensing Addon and the customer wishes to receive 10 licenses, you could use 10 for the Quantity and the system will create 10 services on their account after order submission.
# Optionally, select and enter the appropriate details to add one or more domain names to the order.
#* Select ''None'' if this order doesn't require a domain,
#* For registration, the system will prompt you for the domain name, the number of years to register it for, any applicable addons, and finally any pricing overrides for the registration and future renewal amounts. If there isn't a price override, the system uses the regular price for that TLD.
#* For transfers, the system will prompt you for the same details, along with the EPP code (also commonly called the Transfer Authorization code) from the existing registrar for the domain. During the client area ordering process, the client supplies this, and you may need to obtain it from them first if it is applicable to the domain you are trying to transfer.
#* For '''Domain Only''' orders, you would not enter anything into the fields in the '''Product/Service''' section ('''Product/Service''', '''Domain''', '''Billing Cycle''', '''Quantity''', and '''Price Override''') and fill in the '''Domain Registration''' section.

<div class="docs-alert-info">
<span class="title">Premium Domains</span><br />
When ordering domains via the Admin Area, the system does not look up the domain's availability. WHMCS will therefore be unaware of whether it is a premium domain. For premium domains, [[Clients:Summary_Tab#Login_as_Owner|log in as the account owner]] and order them via the Client Area.
</div>

==Managing a Client's Products and Services==

You can manage a client's products and services in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client's profile. This tab allows you to view and modify all of a products settings. After making any changes, click '''Save Changes'''.

[[File:Module-commands.png|800px]]

If the product or service is linked to a module, the '''Module Commands''' actions display when you view that product or service for the client. This allows you to execute any of the commands available in that module.

Modules can have custom functions, but most use the same basic actions by default.

==Addons==

Product addons allow you to bill for additional items related to the main product but on independent billing cycles from the product (unlike Configurable Options, which have to bill on the same cycle).

You can create new addons or work with preconfigured addons at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Product Addons]]''' or, prior to WHMCS 8.0, '''Setup > Product Addons'''. Then, clients can order addons from the Client Area product details page or from your store.

[[File:Managing-addon.png|800px]]

After purchase, ou can manage addons for individual purchased products in the client profile.
* To view the list of addons for a product, select the parent product from the menu.
* To edit an addon, click the edit icon for that addon in the '''Addons''' list.

===Adding Addons to Users===

[[File:New-addon-button.png|800px]]

To add a new addon for a client:

# Click '''[[Clients:Products/Services Tab|Products/Services]]''' in the client profile.
# Click '''Click here to Manage''' for '''Addons'''.
# Click '''Add New Addon'''.
# If you are adding a predefined addon, select it and leave the name, price, and billing cycle empty.
# If you are adding a custom addon that will be specific to this client, set '''Predefined Addon''' to ''None'' and enter a custom name, price, and cycle.
# To delay generation of the invoice, uncheck the generate invoice checkbox.
# Click '''Save Changes''' to complete the process.

===Promotion Codes===

You can apply promotion codes to an existing service using the menu. For more information, see [[Promotions]].

===Auto Recalculate Recurring Price on Save===

Check this option to update the recurring amount field. You can use this after changing the product, configurable options, billing cycle, or promo code to auto calculate the new recurring price. We disable this by default to ensure that the system does not overwrite any discounted rates or custom pricing.

===Overide Auto Suspension===

This option can be used to allow extra time for payment to be made for specific individuals.

You can enable or disable this option from the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client profile.

==Invoicing Early==

There may be times where a client asks for you to invoice them for the next renewal date early.

To do this:

# Go to the '''[[Clients:Summary Tab|Summary]]''' tab for the client you want to invoice.
# Check the boxes of the products, services, addons, or domains that you want to generate an invoice for.
# Click '''Invoice Selected Items''' to create the invoice for them. You can create multiple invoices if the due dates and payment methods differ.

<div class="docs-alert-info">
* You won't be able to generate another invoice if an invoice has already been made for the next due date.
* If the '''Separate Invoices''' option is enabled in the client's profile or client group, when selecting multiple items here with the same '''Next Due Date''', a single invoice will be generated.
* The status of the service, domain or addon must be ''Pending'', ''Active'', or ''Suspended'' to generate an invoice.
</div>

==Upgrades/Downgrades==

===Admin Area===

[[File:Upgrade button.png|thumb|Upgrade/Downgrade Button]]

If you would like to change the product or service a client is assigned to and automatically charge or credit the difference for that change then you need to use the Upgrade/Downgrade process. You'll find the option for this next to the '''Products/Services''' menu in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab within the client profile.

To use it:
# Go to the product that you want to change.
# Perform the correct action for your WHMCS version:
#* For WHMCS 8.0 and later, click '''More''' and choose '''Upgrade/Downgrade'''.
#* For WHMCS 7.10 and earlier, go to the product you want to change, click '''Upgrade/Downgrade'''.
# Make the new product and billing cycle selections. A preview of what the charge will be for the remainder of the current cycle will display.
# Click '''Create Order'''. The system will create an order and invoice for the change.

<html><a href="http://www.youtube.com/watch?v=wXEulukuHdo" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

There will no immediate changes to the product after creating an upgrade order, the actual product or config option changes won't take effect until the invoice is paid. But as soon as the invoice is paid the product will be updated, the new recurring amount will be set, and with most supported control panels the upgrade is fully automated with the new package details/changes being passed over to the server module being used. Finally the upgrade email specified in the product configuration is sent to the user advising them of the new products details.

The same process can also be used for configurable options changes and billing the difference for those if the product contains them.

===Client Side===

Clients can also place orders for upgrades & downgrades themselves if you have permitted it in the product configuration. This allows clients to order upgrades/downgrades and complete them automatically without the need for any staff involvement.

For more information, including how to allow clients upgrades and how the system calculates upgrade charges, see [[Automated Upgrades and Downgrades]].

===Manual Upgrades===
There may be occasion when you wish to make an upgrade without placing an upgrade order (such as a free upgrade) or processing the upgrade before the client has paid for it.

To do this:

#Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab.
#Change the product in the menu.
#Check '''Auto Recalculate on Save'''.
#Click '''Save Changes'''.
#Click '''Change Package''' in the '''Module Commands''' section.

==Bulk Actions==

[[File:Bulk-actions.png|thumb|Bulk Actions Tool]]

The bulk actions option in WHMCS allows you to perform changes to two or more products inside a client's profile at the same time. The changes can consist of adjustments to the status, payment method, override auto-suspend date, first payment amount, recurring amount, next due date, and billing cycle. For example, you can use this option if you want to reduce a client's price on a number of separate products to the same level, execute module commands in bulk, or if you would like to bring multiple services in line to a matching due date.

To use this feature, from the client's '''[[Clients:Summary Tab|Summary]]''' tab, check the checkboxes next to the products, services, addons, or domains you want to update. The bulk actions will display under the item lists. Additional actions can be viewed by clicking '''Show Advanced Options'''. Enter any changes you wish to make (leaving blank any fields you don't want to change) and click '''Apply''' to complete the changes.

<html><a href="http://www.youtube.com/watch?v=WLLsQML6rEU" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

===Create Prorata Invoice===

When you change the Next Due Date of a product, service, addon, or domain, the system creates a pro-rated invoice that covers the period between the current next due date and the new one. This feature includes scenarios in which the various products have different next due dates to start with and will pro-rate each accordingly as separate line items on the invoice.

To use this, specify the new Next Due Date, check '''Create Prorata Invoice''', and then click '''Apply'''.

For example, the client could wish to pay for the following products on the 10th of the month going forward:

Product A - Next Due Date 01/01/2022 @ $30/month
Product B - Next Due Date 05/01/2022 @ $60/month

To do this, set the Next Due Date to 10/01/2022 and check the checkbox, an invoice with the following line items will be generated:

Product A (01/01/2022 - 09/01/2022) $8.00
Product B (05/01/2022 - 09/01/2022) $10.00
Total Due Today $18.00

Only once paid will the Next Due Dates for both products be updated and in future both products would be invoiced on the 10th January.

==Cancelling a Product/Service==

===Auto Terminate/Fixed Term===
You can setup products to automatically terminate after a set number of days from the date of signup. For more information refer to [[Products_and_Services#Pricing_Tab|Configuring Products/Services]].

===Clients Self Service===
[[File:Request-cancellation-form.png|800px]]

WHMCS can completely automate the process of product cancellation or wait for manual confirmation. To do this navigate to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings''', and enable the '''Show Cancellation Link''' option.

Clients can then request cancellation of any of their products & services directly from the client area.

To fully automate cancellation and have the module terminate command run (for example to remove the hosting account from the server) check '''Cancellation Requests''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' option.

Now when the cron runs any services with a cancellation request due today will be removed from the server and the status changed in WHMCS to Cancelled. The process runs as follows:

*Client clicks ''Request Cancellation'' button on the product details page in client area
*They're prompted to provide a cancellation reason and provided 2 choices for the cancellation - either '''Instant''' (on next cron run) or at the '''End of the Current Billing Cycle'''.
*If a matching domain exists under the client's account in active status with ''Auto Renew'' enabled, the customer is given the option to disable auto renew too - thereby leaving the domain to expire.
*Any unpaid invoices for the product will be cancelled ([[Invoice_Tab#Cancellation_Request_Handling|if enabled]])
*A notification email is sent to administrators and you will be able to review the reason provided in '''Clients > Cancellation Requests'''.

====Manual Cancellation====
If the Cancellation Request setting is '''not''' enabled then at this point you must navigate to the cancellation requests page, click through to the service page and click the '''Terminate''' module command button to remove the account from the server. The cancellation request is then moved from the ''Open Requests'' page to ''Completed Requests''.

====Automated Cancellation====
If the Cancellation Request setting '''is''' enabled the cancellation request will be actioned when the daily automation cron runs on the appropriate day. For example if the ''Immediate'' option was selected it will be terminated on the next cron run, if ''End of Billing Period'' was selected it will be terminated when the cron runs on the service's Next Due Date.

====Voiding Cancellation Requests====
If a Cancellation Request has been submitted by your client and they later change their mind, it is quick and easy to void their cancellation request. Simply navigate to '''Clients > Cancellation Requests''', locate the cancellation you wish to remove, and then click the red X next to the request to remove it. This will stop the cancellation from processing automatically. You'll need to make sure to mark any invoices that were cancelled as "Unpaid" to prevent billing errors.

===Admin Scheduled Cancellations===

As an admin user, you can schedule the termination of a product at the end of the currently active period by going to the Products/Services tab, checking the '''Auto-Terminate End of Cycle''' option and optionally entering a reason/note for it. Any unpaid invoices for the product will be cancelled and will suppress any further renewal invoices from generating for this product and terminate it when the next due date is reached.
The "Cancellation Requests" setting in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' must also be enabled.

===Admin Immediate Cancellation===

Finally, if you want to cancel or terminate a product or service immediately then you simply need to locate the item you wish to cancel, and from the Products/Services page, click the '''Terminate''' button if the product is linked to a module or if not, manually change the dropdown status from Active to '''Cancelled'''. Once you've done this, no further invoices will generate for the item.

===Addons===
When a product or service is terminated automatically by the WHMCS System, including through the above Admin Scheduled Cancellation routine, any child addon(s) attached to the product/service will also be cancelled at the same time. Addons do not support independent scheduled cancellations of their own however.

====Termination Date====
When an addon is Cancelled or Terminated, either manually via the admin interface or automatically as part of a product termination, the Termination Date will be assigned the current date automatically.
The termination date can be edited manually at any time via the Product Addon management screens within the admin area.
<div class="docs-alert-info">A termination date can only be set/edited when the addon is in one of either Terminated or Cancelled status.</div>

==Moving a Product/Service to another Client==
[[File:Transfer product.png|thumb|Transfer Product Popup]]
#From the Products/Services details page of the product you want to move, click '''Move Product/Service to Another Client''' located at the top-right of the page
#A popup box will appear (you will need popup blockers disabled to use this)
#In the popup enter the ID of the new owner. If you don't know the client's ID the Search field can be used to search by name, company or email address. Click the client's name and the ID will be filled in.
#After selecting the desired click, click the '''Transfer''' button
#The item will then be transferred, the window will close, and the original window will refresh to show the product under its new owner.

'''N.B.''' Moving a products/service between clients within WHMCS will not have any affect on the account on the server.

===Invoices===
Invoices cannot be moved between clients, therefore when moving a product/service any invoices will remain under the old owner. Therefore it would be advisable to check the old owner's Invoices tab for any unpaid invoices for this service and cancel them. If you wish to invoice the new owner for the service, move the Next Due Date forward/back by one day and a new invoice will be generated when the cron next runs.

==Deleting a Product/Service from a Client==

#From the Products/Services details page of the product you want to delete, scroll to the bottom and click the red '''Delete''' link
#After clicking this link, you will be asked to confirm if you are sure you want to delete the item
#If you click No you will be returned to the page, if you click Yes, the item will be deleted and you will be taken to the next product/service under that client

'''Note:''' Deleting a product from WHMCS will not terminate it on the server. If you wanted to remove it from the server aswell, you need to run the Terminate Module Command as explained above before deleting the record from WHMCS.

==Resending Product Welcome Email==
To re-send a product welcome email simply navigate to the client's Products/Services tab and click the "Resend Product Welcome Email" button at the bottom of the page.

Promotions

2022-08-12T10:08:55Z

John: /* Prerequisites */

Promotions can offer discounts on your products and services, product addons, and domains.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Promotions''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''

For information on setting up commonly-used promotions, see [[Common Promotions]].

==Types of promotions that can be offered==

*One Time Discounts
*Recurring Discounts
*Limited Recurring Discounts (for example, first two months free)
*Monetary Discounts (for example, $5 Off)
*Percentage Discounts (for example, 20% Off)
*Price Override (for example, Regular price $10, Discount price $8)
*Free Setup
*Apply to Specific Products/Addons/Domain TLDs
*Apply to Specific Billing Cycles or Registration Periods
*Apply Once per Order or to All Applicable Items in Cart
*Lifetime Promotion
*Valid for New Signups Only
*Valid for upgrade orders only

==How to create a new promotion==

To create a new promotion:

# Click '''Add New''' at the top of the page.
# Enter a promotion code. This is the code that customers will need to enter on the order form to receive the discount.
# Choose one of the four promotion types:
#* Percentage — Discount by a percentage of the original price.
#* Fixed Amount — Discount a specified amount from the original price.
#* Price Override — Changes the product price to this value. Use this to offer a consistent discount across multiple billing cycles.
#* Free Setup — Discount any setup fee from the original price.
# To have the discount only apply to the first invoice, do not check '''Recurring'''.
#* When you check this, the discount will apply to renewal invoices.
#* Set '''Recur For''' to <tt>0</tt> for all future renewals to discount, or enter a different number to specify how many cycles the discount lasts for. This is in addition to the initial invoice for the product. If you wish to provide a discount 6 times, enter <tt>5</tt> in the recurring box.
# For '''Value''', enter the amount of the discount in positive numbers (up to 2 decimals) only.
# Select the products, addons, and domain TLDs that the promotion applies to and what billing cycles or registration periods the discount requires. These should match those of your products. Your can press <tt>Ctrl+click</tt> to select multiple entries.
# Optionally, set the start and expiration dates. If you use one or both of these settings, the coupon will only start working after the start date and will stop working at expiration.
# Use the following checkboxes to specify who can use the promotion:
#* Apply Once — If the client orders multiple qualifying products, the system only applies the discount once.
#* New Signups — Only new clients can use the promotion.
#* Apply Once / Client — If a client has an existing active order that uses this promotion, they will not be able to use the code a second time.
#* Lifetime Promotion — Client will retain this discount even if they upgrade or downgrade their service in future, regardless of settings such as maximum uses or expiration date.
#* Existing Client — Only existing clients with one or more active orders can use the promotion.
#* Enable for product upgrades – See [[#Upgrades/Downgrades|Upgrades/Downgrades]] below.
# In the admin notes section, add information that admins may need about the promotion.

The promotion code changes the '''First Payment Amount''' when a customer or administrator uses the code while ordering. It does not change the '''Recurring Amount'''. If it did automatically update the recurring amount, this would prevent administrators from being able to manually update the recurring amount value when a promotion code was in use.

Instead, the system uses the promotion code to discount the '''Recurring Amount''' automatically on renewal invoices.

==Limiting Usage==

You can set the maximum number of times to honor a promotion. To do this:

# Locate the promotion you want to limit the usage of and click the edit icon next to it.
# For '''Maximum Uses''', enter the number of uses that you want to allow.
#* The number of times that customers have used the promotion will display below this setting.
#* For unlimited uses, enter <tt>0</tt>.
# Click '''Save Changes'''.

==Prerequisites==

By selecting products from '''Requires''', you can stipulate which products or services the client must also have in their shopping cart before applying the discount. This can be used to offer "buy x get y half price" style promotions.

'''Also allow existing products in account to qualify for promotion''' allows the system to include Active products that the client already owns in the promotion criteria.

For example, if the client already owns product x with an Active service status, they would be able to use the promotion code when ordering product y. If you disable this option, the client would need to order both products x and y at the same time to qualify.

==Upgrades/Downgrades==

When you check this checkbox, the client will use the promo code when placing an upgrade or downgrade order, which is particularly useful for offering incentives when upselling. When you check this, some new options will appear:

===Products/Services===

Select ''Products/Services'' as the '''Upgrade Type'''.

Use '''Type''', '''Recurring''', and '''Value''' fields to specify the value of the discount and how long it lasts.

Use '''Applies To''' to select which products to apply the promotional code to. The client will receive the discount when upgrading to this product.

For upgrades and downgrades, use '''Requires''' slightly differently. It restricts which products clients can upgrade. For example, they can upgrade from a selected product to this product and receive a discount, but not upgrade from an unselected product and receive a discount.

===Configurable Options===

To offer discounts to clients for configurable options, select ''Configurable Options'' as the '''Upgrade Type'''.

Use '''Upgrade Discount''' to specify the discount value as a percentage or fixed amount for the configurable options. Then, use '''Config Options Upgrades''' to select which option this discount applies to.

If you use the main '''Type''', '''Recurring''', and '''Value''' at the top of the page, the system will apply a discount to the parent product as well as to the configurable option. Leave this blank to only apply the discount to the configurable option.

==Promotion Links==

You can give links to users that will automatically apply a certain promotion code to their order if it applies. To do that, use a link like the one below:

cart.php?promocode=TEST '''OR''' cart.php?a=add&pid=1&promocode=TEST

Both of the above will apply the promotion code <tt>TEST</tt> to the order. With the first link, the user can choose the package they want. With the second, they will go straight to step 2 of the order process with product ID <tt>1</tt> selected.

For more information, see [[Linking to WHMCS]].

==Management==

When you create a promotion, you can specify an expiry date. If you want the promotion code to become invalid before this date, click '''Expire Now'''.

You can create a copy of any promotion by clicking '''Duplicate Promotion'''. This is particularly useful for quickly running a successful promotion again or providing a personalised promo code to a client.

==Manually Applying a Promotion==

WHMCS allows you to manually add a promotion code to an existing service. You can make this type of addition when viewing a client’s existing service in the Admin Area.

Click '''Promotion Code''' for a list of all the active promotions on the installation. From this list, you can select the promotion you would like to apply to the service, and then click '''Save Changes''' to commit your changes.

'''Recurring Amount''' on the service page is the final amount to bill the client for after taking the selected promotion into consideration. Selecting a promotion code by itself will not change the invoice amount.

Due to this behavior, it is important to update '''Recurring Amount''' so that it reflects the amount you want the customer to pay after applying the promotion code. You can do this in one of two ways:

* Manually calculate the amount that you would like the customer to pay after the discount and enter it in '''Recurring Amount'''. Then, click '''Save Changes'''.
* Select '''Auto Recalculate on Save''', and then click '''Save Changes'''. This option will have WHMCS take the current pricing for the product or service, apply the discount from the selected promotion code, and then set '''Recurring Amount''' for that value.

For client services with a promotion code, WHMCS alters how it generates the service’s invoice items for renewal invoices.

To provide the client with information concerning discounts from promotion codes, WHMCS will generate two invoice items. The first item will display the sum of '''Recurring Amount''' and the discount amount. The second item will display the discount amount.

As an example, if you have a service with a '''Recurring Amount''' of <tt>10.00</tt> and apply a promotion code that offers a 50% discount, then the system will generate the following invoice items when the service renews:

* Invoice Item for Service Renewal: 20.00
* Promotion Code (50% Off): -10.00
* Invoice Total: 10.00

This is the recommended method to convey a discount to clients.

If you had this same service with no promotion code, then the system would generate the following invoice items upon renewal instead:

* Invoice Item for Service Renewal: 10.00
* Invoice Total: 10.00

Both invoices result in a charge of 10.00, however one shows the client that they are paying this price because of a promotion code.

If you want to provide the client with a discount, but not create a promotion code invoice item, then you could do this by either manually specifying a '''Price Override''' value when creating the order, or by modifying '''Recurring Amount'''.

==Notes==

===Limited Recurring Promotions===

The system counts the number of recurrences for a Limited Recurring promotion (which are configured using the '''Recur For x Times''' setting) by looking at the invoice line items for the service. By looking at the number of invoice line items for a service, WHMCS makes a determination for how many times it has applied the promotional discount.

After the system has used all of a promotion code's recurrences for a given service, the service will revert to the standard price automatically.

If you wish to provide an an extension of the promotion, it would be necessary to increase '''Times''' in the promotion code configuration. This will apply to all existing services using this promo code, instantly. Deleting invoices will not extend the duration of the promotional discount.

===Fixed Amount Promotions and Additional Currencies===
When defining the value for a '''Fixed Amount''' promotion, it is important to note that this value applies to the base currency. For example, if the installation's '''Base Currency''' is ''USD'', then setting the '''Value''' for a '''Fixed Amount''' promotion to 100 will provide a discount of $100.00 USD when customers use it.

If the installation has additional currencies beyond the base currency, the system will use '''Base Conversion Rate''' to determine the discount for customers using these additional currencies.

For more information, see [[Currencies]].

===Create Custom Promo===

'''Create Custom Promo''' displays next to '''Promotion''' when you manually add a new order via '''Add Order''' in the Admin Area.

Clicking this button displays a modal that allows you to specify a custom promotion code that the system will automatically create and apply to the immediate order.

Use of this feature requires that the Administrator User have both '''Use Any Promotion Code on Order''' and '''Create/Edit Promotions''' as permissions. For more about permissions, see [[Administrators_and_Permissions|Administrators and Permissions]].

=== Services With Metric Billing Enabled ===

When the system applies a recurring promotion or discount to a product or service for which metric billing enabled, '''only''' the cost of the base product will be eligible for the discount.

Any usage (metric) charge that the recurring invoice includes '''will not''' receive the promotion or discount.

Maximising Performance

2022-08-12T09:28:18Z

John: /* Email Provider */

If you grow to have a large client base, page loads may become slower. This is because the more data you have, the larger the database becomes, and so calculating and looping through the data will naturally take longer.

The following steps can help you maintain faster speeds:

==Software Related==

=== Disable Ticket Counts ===

When you have a lot of tickets, calculating the number of tickets per status to display each time you open a ticket can slow things down.

To avoid that, disable the ticket counts by adding the following line to your WHMCS <tt>configuration.php</tt> file:

<div class="source-cli">
$disable_admin_ticket_page_counts = true;
</div>

=== Logging ===

In WHMCS, you can enable logging for, for example, SQL errors, hooks loading, or module commands.

The following settings control debug logging:

* '''SQL Error Reporting''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* '''Hooks Debug''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* '''Module Debug Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Debug Log'''.

Make sure to disable these when you are not actively debugging an issue, since they can and will increase the database size exponentially.

=== Customizations ===

Third party customizations can slow the performance of WHMCS. Ensure that any customization (for example, hooks and addons) that you are using is up-to-date and works with the version of WHMCS you are running.

=== Database Backups ===

The database backup process can be CPU, memory, and disk intensive while the entire database is exported, compressed, and uploaded or emailed. If performance issues are observed at the same time every day during the database backup process, this could be a potential cause.

For more information, see [[Backups#Limitations|Backups]].

==Server Related==

=== Email Provider ===

Long loading times when performing an action involving sending an email (for example, placing an order, opening or replying to a support ticket, or publishing an invoice) are often caused by connection issues to the chosen email provider.

To diagnose and resolve this, see [https://help.whmcs.com/m/troubleshooting/l/1261469-troubleshooting-email-sending-problems Troubleshooting Email Problems].

Consider switching to an external mail provider such as MailGun, SendGrid or SparkPost, as these are often more performant than SMTP systems. For further information see [[Mail_Tab#Configuring_a_Mail_Provider_in_WHMCS_8.0_and_later|Configuring a Mail Provider]].

=== MySQL® ===

WHMCS performance is largely dependent on a correct MySQL® configuration, especially for larger databases. Make any changes to the server's <tt>my.cnf</ttt> file under the <tt>mysqld</tt> section, usually in <tt>/etc/my.cnf</tt> (cPanel servers and most others).

* As a starting point, set <tt>max_connections</tt> to a low value like <tt>50</tt> and increase based on the available RAM.
* When you are configuring this and the following other important settings, restart MySQL and let it run for 48 hours:
** <tt>wait_timeout</tt> (at least 300, so MySQL doesn't drop connections too soon)
** <tt>sort_buffer_size</tt> (2–4 MB)
** <tt>read_buffer_size</tt> (2–4 MB)
** <tt>max_allowed_packet</tt> (16 MB)

=== System Tweaks ===

WHMCS is a PHP MySQL script, and so the more RAM or SWAP memory and raw processing power you have at your disposal, the better the performance from your installation.

* For more information, see [[System Requirements]].
* We recommend using the higher set values and modules under the '''Recommended Settings''' for best results.

Long Term Support

2022-07-18T11:56:04Z

John: /* WHMCS Version & LTS Schedule */ 8.2 is now EOL

== WHMCS Long-Term Support ==

Product enhancements, bug fixes and security fixes for published versions of WHMCS are common; WHMCS is constantly being refined to ensure a safe and robust experience. However, it is impractical for customers to always track the latest product refinements at the same pace as our Development Team. And for that reason, WHMCS has implemented a Long-Term Support Policy for WHMCS.

=== Overview ===
The WHMCS Long-Term Support Policy provides customers with a clear understanding of our commitment to supporting the software they have purchased a license for and installed on their systems.

WHMCS will provide periodic maintenance releases for major and minor versions of WHMCS as part of the normal WHMCS Release Process. This is called [[#Active Development | Active Development]]. Versions of WHMCS that are not under Active Development will not receive maintenance releases, however, they are candidates for Targeted Critical and Security Releases. WHMCS will only provide Targeted Releases for candidates that have not reached their [[#Defining End Of Life | End Of Life]].

Please refer to the [[#WHMCS Version & LTS Schedule|WHMCS Version and LTS Schedule]] to see what versions of WHMCS are currently covered by Long-Term Support or under Active Development.

=== Provisions of Long-Term Support ===
Once a version of WHMCS is no longer being actively developed it will receive Long-Term Support (LTS) from our Development and Security Teams. LTS is a finite period which expires on a specific date known as End Of Life (EOL). Each minor version has it's own EOL date.

Product versions that are in LTS are provided Targeted Critical and Security Releases.

Once a version has moved from Active Development to LTS it will not receive product enhancements or maintenance fixes unless they are deemed critical to the viability of a Targeted Critical or Security Release, and therefore delivered as part of LTS. If you require product enhancements or maintenance fixes, we suggest updating to a product version that is being actively developed.

=== Active Development ===
A product version that is under Active Development is in the process of being refined. Therefore, subsequent revisions are likely to be released until a new minor version is published. Revision releases can include bug fixes, security enhancements, minor optimizations, third-party updates, as well as Important or Critical updates.

At any given moment in time, there will likely be only one actively developed version of WHMCS available; it will be the latest version available for our site. However, to ensure a smooth transition from one major or minor version to the next, WHMCS may extend Active Development of the previously published version. These overlaps between product versions is usually quite small, on the order of a few weeks at most.

Please refer to [[#WHMCS Version & LTS Schedule|WHMCS Version and LTS Schedule]] to know if your version is currently under Active Development.

=== Defining End Of Life ===
A core attribute of the Long-Term Support Policy is defining a given version's End Of Life (EOL) date. The EOL date is established upon the publication of a new minor or major release and typically is set one year into the future.

For example if version 1.0.0 is published January 31, 2012, then it will have an EOL of January 1st 2013 because it is a major release. If 1.1.0 is published on May 1st, 2012, it will have an EOL of May 1st 2013 because it is a minor release. If 1.1.1 is published on May 15th 2012 it will have an EOL of May 1st 2013 because it is a maintenance release to a previous minor release. Likewise, if 1.1.5 is published on July 24th 2012 it will have an EOL of May 1st 2013 because it is a maintenance release to a previous minor release.

=== After End Of Life ===
Once a version's EOL date has passed, no further releases or updates will be provided, regardless of the observed deficiency in that version.

Products that have reached EOL are not available for download from WHMCS.

As noted below in [[#Licensing & Services | Licensing & Services]], the product will continue to function even after the EOL date has passed. The use of the software is not tied to LTS or EOL, but the active/inactive state of your license.

=== Licensing & Services ===
WHMCS has historically offered with two types of licenses: Monthly and Owned. Whilst all new sales are of the Monthly type, this document also describes how the policy applies to [[Renewing Support and Updates|grandfathered Owned licenses]]. Each license type is bundled with [[#Help Desk Support | help desk support]] and access to [[#Software Update Service | software updates]] when initially purchased.

A Monthly license always has access to these two services. An Owned license has access to these two services for one year. After one year, an Owned license holder can purchase an additional year of these two services as an addon.

An Owned license validates use of the software indefinitely, even after the term of help desk support and access to software updates expires. A Monthly license validates use of the software, help desk support, and access to software updates in one month durations. The active status of your license governs the functional state of your WHMCS installation, not the development status (Active Development/LTS/EOL) of the deployed product version.

==== Help Desk Support ====
The help desk support service allows customers to open tickets with our help desk. These tickets are managed by our Technical Analysts. Our Analysts work with customers to resolve a broad range of issues from configuration to identifying deficiency within a given version of WHMCS. With this service, customers have access to Analysts regardless of which version of the product they are using, even if that version has reached its End Of Life.

It's important to remember, however, that support provided by this service, or deficiencies identified by our Analysts, does not imply future refinements for versions. The [[#WHMCS Version & LTS Schedule|LTS schedule]], along with the severity of the identified issue, will determine what versions of WHMCS are candidates for any future refines.

==== Software Update Service ====
The software update service allows customers access to the latest versions of WHMCS. The service does not imply continued development, maintenance, or critical fixes for any given version of WHMCS. The [[#WHMCS Version & LTS Schedule|LTS schedule]] will determine what versions of WHMCS are candidates for any refinements. It is recommended that customers leverage this service and keep their WHMCS installation up to date, and optimally, tracking a version that is currently under [[#Active Development | Active Development]].

=== Grandfathered LTS ===
The WHMCS Long-Term Support policy is effective May 1st, 2013. Particular versions have been grandfathered, namely 4.5, 5.0, and 5.1.

=== WHMCS Version & LTS Schedule ===
This chart is updated upon each major or minor release of WHMCS.

{| class="table table-striped"
! WHMCS Version
! Approximate Publication Date
! Targeted End-Of-Life Date
! Current Status

|-
| 8.5 || April 2022 || May 31st, 2023 || style="background: #81D153; font-weight: bold;" | [[#Active Development | <span style="color:#333">Active Development</span>]]
|-
| 8.4 || December 2021 || January 31st, 2023 || style="background: #FFCCCC; font-weight: bold;" | LTS
|-
| 8.3 || September 2021 || October 31st, 2022 || style="background: #FFCCCC; font-weight: bold;" | LTS
|-
| 8.2 || May 2021 || June 30th, 2022 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.1 || November 2020 || December 31st, 2021 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 8.0 || August 2020 || September 30th, 2021 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 7.10 || April 2020|| April 30th, 2021 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 7.9 || November 2019 || December 31st, 2020 || style="background: #84807F; font-weight: bold;" | EOL
|-
| 7.8 || August 2019 || August 31st, 2020 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.7 || January 2019 || January 31st, 2020 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.6 || June 2018 || July 31st, 2019 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.5 || April 2018 || April 30th, 2019 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.4 || November 2017 || November 30th, 2018 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.3 || October 2017 || October 31st, 2018 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.2 || May 2017 || May 31st, 2018 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.1 || December 2016 || December 31, 2017 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 7.0 || October 2016 || October 31, 2017 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.3 || March 2016 || March 31, 2017 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.2 || December 2015 || December 31, 2016 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.1 || September 2015 || September 30, 2016 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 6.0 || July 2015 || July 31, 2016 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.3 || September 2013 || October 31, 2015 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.2 || March 2013 || March 31, 2014 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.1 || July 2012 || November 30, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 5.0 || December 2011 || July 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.5 || April 2011 || June 30, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.4 || December 2010 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.3 || September 2010 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.2 || March 2010 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.1 || November 2009 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 4.0 || May 2009 || May 31, 2013 || style="background: #84807F; font-weight: bold;color: black" | EOL
|-
| 1.x-3.x || -- || -- || style="background: #84807F; font-weight: bold; font-style: bold;color: black" | EOL
|}

''Last Updated: {{REVISIONDAY2: Long_Term_Support }}/{{REVISIONMONTH: Long_Term_Support }}/{{REVISIONYEAR: Long_Term_Support }}

Automatic Updater

2022-06-23T11:44:27Z

John: /* Unable to connect to the WHMCS Update Server */

<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.0 and above</div>

The Automatic Update utility allows admin users to update WHMCS quickly and easily in just a few clicks.

You can access this feature at '''Utilities > Update WHMCS'''.

For more information on the way in which updates change files, see [[Updater File Changes]].

== System Requirements ==

For automatic updates to be possible, the following system requirements apply:

* A PHP Memory limit of at least 128MB
* At least 250 MB of free disk space
* PHP setting allow_url_fopen enabled
* PHP max_execution_time in excess of 60 seconds
* PHP Zip Extension or the proc_open PHP function enabled
* PHP setting open_basedir to include entire WHMCS docroot

== Configuring Your Update Settings ==

=== Choosing an Update Channel ===

The WHMCS automatic updater allows you to choose an update channel that defines the type of updates you will receive. The update channel setting determines the least stable version you are willing to update to:

<table class="table table-striped">
<tr>
<td>'''Channel'''</td>
<td>'''Description'''</td>
</tr>
<tr>
<td>Stable</td>
<td>'''Recommended''' for most installations of WHMCS, the Stable channel will only apply Stable updates to your installation.</td>
</tr>
<tr>
<td>Current Version</td>
<td>Subscribing to this channel will restrict you to only receiving maintenance updates for the major/minor version that is currently installed. For example if you are on a version that is in [[Long Term Support]] and a patch is issued for that series, this channel allows you to apply the patch and remain on that series.<div class="docs-alert-info">This is useful for applying minor updates and security releases. More details below.</div></td>
</tr>
<tr>
<td>Release Candidate</td>
<td>Subscribing to the Release Candidate channel will allow you to receive releases after beta testing but before they are released to the Stable tier.</td>
</tr>
<tr>
<td>Beta</td>
<td>Subscribing to the Beta release channel will allow you to receive the very latest versions of WHMCS. This tier should only be selected for development and test based installations.</td>
</tr>
</table>

==== Patch and Maintenance Release Updates ====

* If you are on a version that is in [[Long Term Support]] and a patch is issued for that series, you can use the Updater to apply the patch and remain on that series.
* To do this, select the '''Current Version''' update channel as described above.
* You many need to click ''Check for Updates'' after any setting changes in order to refresh the available version displayed within the page.

<div class="docs-alert-warning">
You may wish to change this setting back to "Stable" after updating to ensure future checks display the latest Active Development version available to you.
</div>

=== Setting a Temporary Update Path ===

A temporary path is required for staging of files during an update. For security reasons it is recommended that this directory be located outside the public doc root, similar to the attachments, downloads and templates_c directories. The path must be an absolute path (i.e. /home/whmcsuser/tmp instead of ~/tmp) and must be writable by the user that is running PHP.

=== Setting a Maintenance Message ===

This option can be used to set a message that will be displayed to both other admin and client users whenever an update is in progress.

<div class="docs-alert-info">Modifying the update configuration requires the '''Modify Update Configuration''' administrator role permission, which is separate from the "Update WHMCS" permission.</div>

[[File:Configureupdatesettings.png|center]]

== Checking for Updates ==

New updates are checked for periodically automatically.

When an update becomes available, a notification will appear in the top left corner of admin area as shown below.

[[File:Screenshot 2017-06-01 10.32.27.png|700px]]

===Manually checking for updates===

You can check for updates on-demand by clicking the '''Check for Updates''' button.

If a release has just been published you may need to do this to see the update as available prior to the next automated check.

For Owned licenses, the version fetched by the utility will be the version of WHMCS that was available when your Support and Updates Subscription was active. Downloading the latest version of WHMCS requires an active Support and Updates Subscription.

[[File:UpdateAvailable.png|center]]

== Performing an Update ==

To perform an update:

# Make certain that your server meets the [[System_Requirements|system requirements]] and review the [[Release Notes]] for any important notices and information.
# Make a full backup of your current installation.
# In WHMCS, click '''Update Now'''. <div class="docs-alert-info"><i class="fa fa-info-circle"></i>This option only displays if an update is available for your current update channel.</div>
# Follow the prompts to complete the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.

If you have custom template files you will also need to review and make any necessary changes to your custom templates using the information provided in the Template Changes section of the [[Release_Notes|Release Notes]].

<div class="docs-alert-success"><i class="fa fa-warning"></i> Your customisations will be preserved during the update if you are leveraging the recommended methods for customising things such as [https://developers.whmcs.com/themes/ templates], [[WHOIS_Servers|WHOIS servers]], [[Additional Domain Fields]] and [[Customising Countries and Calling Codes|Countries]]</div>

<div class="docs-alert-warning"><i class="fa fa-check"></i> If you have customised the permissions on any of the files eg. /crons/pipe.php. These changes will need to be re-applied after the upgrade is complete.</div>

== Troubleshooting ==

The actions performed by the Automatic Updater are recorded in the tblupdatelog table within the WHMCS database. To troubleshoot upgrade problems it is useful to review this table for the most recent entries (the highest id values). A tool such as phpmyadmin can be used to browse to the table contents.

For additional guides to troubleshooting auto-update problems, see [http://help.whmcs.com/m/updating Updating] and [[Upgrading New Installation Prompt]].

===Please ensure you have selected a valid Update Channel and then try again===

Receiving this error message in the cron job report email or activity log, indicates that an Update Channel setting needs selecting. To do this, click '''Configure Update Settings'''.

Next select one of the four available update channel options, and Click Save Changes. The options are [[#Choosing an Update Channel|described above]].

===Permission Errors===

Permission errors in the update log may resemble the following examples:

* <tt>[WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php</tt>
* <tt>[RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.</tt>
* <tt>failed to open stream: Permission denied</tt>
* <tt>Apply update dry-run detected 1 permission issues</tt>

The exact file permission and ownership issues will depend on the individual server configuration. However, for a standard cPanel & WHM server using the suPHP PHP handler, the following configuration would be an appropriate POSIX file permissions:

* <tt>configuration.php</tt> — <tt>400</tt>
* <tt>/crons/pipe.php</tt> — <tt>755</tt>
* All other PHP files — <tt>644</tt>
* All directories — <tt>755</tt>

The file ownership and group should be the same as the user directory name. For example, on a cPanel & WHM server with a web root at <tt>/home/username/public_html/</tt>, the <tt>username</tt> user would own the files and the group would also use the name <tt>username</tt>.

Finally, the owner and group of the PHP process must be the same as the user directory name. For example, on a cPanel & WHM server with a web root at <tt>/home/username/public_html/</tt>, the PHP process owner and group would both be <tt>username</tt>.

Other types of server and PHP handlers may have different configuration requirements.

===Unable to connect to the WHMCS Update Server===
This error message may be encountered when attempting to perform an automatic update or appear in the Activity Log. It means that your server was unable to connect to our update server. From your server's command line, attempt the following two cURL connections:

<div class="source-cli">
curl -v https://releases.whmcs.com/v2/packages.json

curl -v https://pki.whmcs.com/
</div>

The expected return is a '''StatusCode: 200'''. If any other results is returned please work with your server admin or hosting provider to investigate the connectivity problem between your server and the WHMCS update server.

Automatic Updater

2022-06-23T11:42:01Z

John: /* Troubleshooting */ Need to have Unable to connect to the WHMCS Update Server heading, as it's referenced in the product.

<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.0 and above</div>

The Automatic Update utility allows admin users to update WHMCS quickly and easily in just a few clicks.

You can access this feature at '''Utilities > Update WHMCS'''.

For more information on the way in which updates change files, see [[Updater File Changes]].

== System Requirements ==

For automatic updates to be possible, the following system requirements apply:

* A PHP Memory limit of at least 128MB
* At least 250 MB of free disk space
* PHP setting allow_url_fopen enabled
* PHP max_execution_time in excess of 60 seconds
* PHP Zip Extension or the proc_open PHP function enabled
* PHP setting open_basedir to include entire WHMCS docroot

== Configuring Your Update Settings ==

=== Choosing an Update Channel ===

The WHMCS automatic updater allows you to choose an update channel that defines the type of updates you will receive. The update channel setting determines the least stable version you are willing to update to:

<table class="table table-striped">
<tr>
<td>'''Channel'''</td>
<td>'''Description'''</td>
</tr>
<tr>
<td>Stable</td>
<td>'''Recommended''' for most installations of WHMCS, the Stable channel will only apply Stable updates to your installation.</td>
</tr>
<tr>
<td>Current Version</td>
<td>Subscribing to this channel will restrict you to only receiving maintenance updates for the major/minor version that is currently installed. For example if you are on a version that is in [[Long Term Support]] and a patch is issued for that series, this channel allows you to apply the patch and remain on that series.<div class="docs-alert-info">This is useful for applying minor updates and security releases. More details below.</div></td>
</tr>
<tr>
<td>Release Candidate</td>
<td>Subscribing to the Release Candidate channel will allow you to receive releases after beta testing but before they are released to the Stable tier.</td>
</tr>
<tr>
<td>Beta</td>
<td>Subscribing to the Beta release channel will allow you to receive the very latest versions of WHMCS. This tier should only be selected for development and test based installations.</td>
</tr>
</table>

==== Patch and Maintenance Release Updates ====

* If you are on a version that is in [[Long Term Support]] and a patch is issued for that series, you can use the Updater to apply the patch and remain on that series.
* To do this, select the '''Current Version''' update channel as described above.
* You many need to click ''Check for Updates'' after any setting changes in order to refresh the available version displayed within the page.

<div class="docs-alert-warning">
You may wish to change this setting back to "Stable" after updating to ensure future checks display the latest Active Development version available to you.
</div>

=== Setting a Temporary Update Path ===

A temporary path is required for staging of files during an update. For security reasons it is recommended that this directory be located outside the public doc root, similar to the attachments, downloads and templates_c directories. The path must be an absolute path (i.e. /home/whmcsuser/tmp instead of ~/tmp) and must be writable by the user that is running PHP.

=== Setting a Maintenance Message ===

This option can be used to set a message that will be displayed to both other admin and client users whenever an update is in progress.

<div class="docs-alert-info">Modifying the update configuration requires the '''Modify Update Configuration''' administrator role permission, which is separate from the "Update WHMCS" permission.</div>

[[File:Configureupdatesettings.png|center]]

== Checking for Updates ==

New updates are checked for periodically automatically.

When an update becomes available, a notification will appear in the top left corner of admin area as shown below.

[[File:Screenshot 2017-06-01 10.32.27.png|700px]]

===Manually checking for updates===

You can check for updates on-demand by clicking the '''Check for Updates''' button.

If a release has just been published you may need to do this to see the update as available prior to the next automated check.

For Owned licenses, the version fetched by the utility will be the version of WHMCS that was available when your Support and Updates Subscription was active. Downloading the latest version of WHMCS requires an active Support and Updates Subscription.

[[File:UpdateAvailable.png|center]]

== Performing an Update ==

To perform an update:

# Make certain that your server meets the [[System_Requirements|system requirements]] and review the [[Release Notes]] for any important notices and information.
# Make a full backup of your current installation.
# In WHMCS, click '''Update Now'''. <div class="docs-alert-info"><i class="fa fa-info-circle"></i>This option only displays if an update is available for your current update channel.</div>
# Follow the prompts to complete the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.

If you have custom template files you will also need to review and make any necessary changes to your custom templates using the information provided in the Template Changes section of the [[Release_Notes|Release Notes]].

<div class="docs-alert-success"><i class="fa fa-warning"></i> Your customisations will be preserved during the update if you are leveraging the recommended methods for customising things such as [https://developers.whmcs.com/themes/ templates], [[WHOIS_Servers|WHOIS servers]], [[Additional Domain Fields]] and [[Customising Countries and Calling Codes|Countries]]</div>

<div class="docs-alert-warning"><i class="fa fa-check"></i> If you have customised the permissions on any of the files eg. /crons/pipe.php. These changes will need to be re-applied after the upgrade is complete.</div>

== Troubleshooting ==

The actions performed by the Automatic Updater are recorded in the tblupdatelog table within the WHMCS database. To troubleshoot upgrade problems it is useful to review this table for the most recent entries (the highest id values). A tool such as phpmyadmin can be used to browse to the table contents.

For additional guides to troubleshooting auto-update problems, see [http://help.whmcs.com/m/updating Updating] and [[Upgrading New Installation Prompt]].

===Please ensure you have selected a valid Update Channel and then try again===

Receiving this error message in the cron job report email or activity log, indicates that an Update Channel setting needs selecting. To do this, click '''Configure Update Settings'''.

Next select one of the four available update channel options, and Click Save Changes. The options are [[#Choosing an Update Channel|described above]].

===Permission Errors===

Permission errors in the update log may resemble the following examples:

* <tt>[WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php</tt>
* <tt>[RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.</tt>
* <tt>failed to open stream: Permission denied</tt>
* <tt>Apply update dry-run detected 1 permission issues</tt>

The exact file permission and ownership issues will depend on the individual server configuration. However, for a standard cPanel & WHM server using the suPHP PHP handler, the following configuration would be an appropriate POSIX file permissions:

* <tt>configuration.php</tt> — <tt>400</tt>
* <tt>/crons/pipe.php</tt> — <tt>755</tt>
* All other PHP files — <tt>644</tt>
* All directories — <tt>755</tt>

The file ownership and group should be the same as the user directory name. For example, on a cPanel & WHM server with a web root at <tt>/home/username/public_html/</tt>, the <tt>username</tt> user would own the files and the group would also use the name <tt>username</tt>.

Finally, the owner and group of the PHP process must be the same as the user directory name. For example, on a cPanel & WHM server with a web root at <tt>/home/username/public_html/</tt>, the PHP process owner and group would both be <tt>username</tt>.

Other types of server and PHP handlers may have different configuration requirements.

===Unable to connect to the WHMCS Update Server===
This error message may be encountered when attempting to perform an automatic update or appear in the Activity Log. It means that your server was unable to connect to our update server. From your server's command line, attempt the following two cURL connections:

<div class="source-cli">
curl https://releases.whmcs.com/packages.json

curl https://pki.whmcs.com/
</div>

The expected return is a '''StatusCode: 200'''. If any other results is returned please work with your server admin or hosting provider to investigate the connectivity problem between your server and the WHMCS update server.

Automatic Updater

2022-06-23T11:41:14Z

John: Reverted edits by John (talk) to last revision by SarahK

Automatic Updater

2022-06-23T11:34:11Z

John:

<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.0 and above</div>

The Automatic Update utility allows admin users to update WHMCS quickly and easily in just a few clicks.

== System Requirements ==

For automatic updates to be possible, the following system requirements apply:

* A PHP Memory limit of at least 128MB
* At least 250 MB of free disk space
* PHP setting allow_url_fopen enabled
* PHP max_execution_time in excess of 60 seconds
* PHP Zip Extension or the proc_open PHP function enabled
* PHP setting open_basedir to include entire WHMCS docroot

== Checking for Updates ==

New updates are checked for periodically automatically.

When an update becomes available, a notification will appear in the top left corner of admin area as shown below.

[[File:Screenshot 2017-06-01 10.32.27.png|700px]]

===Manually checking for updates===

You can check for updates on-demand by navigating to ''Utilities > WHMCS Update'' and clicking the '''Check for Updates''' button.

If a release has just been published you may need to do this to see the update as available prior to the next automated check.

[[File:UpdateAvailable.png|center]]

== Performing an Update ==

To perform an update, navigate to ''Utilities > Update WHMCS'' and click the '''Update Now''' button (pictured above).

<div class="docs-alert-info"><i class="fa fa-info-circle"></i> Please note this option will only show if an update is available based on your current Update Channel Preferences.</div>

You will then be guided through the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.

Before beginning any update, it is strongly recommended to make a full backup of your current installation and review the [[Release Notes]] for any important notices and information.

Watch our video tutorial here: https://vimeo.com/whmcs/automatic-updates-tutorial

<div class="docs-alert-success"><i class="fa fa-warning"></i> Your customisations will be preserved during the update provided you are leveraging the recommended methods for customising things such as [[Customising_the_Six_Theme|templates]], [[WHOIS_Servers|WHOIS servers]], [[Additional Domain Fields]] and [[Customising Countries and Calling Codes|Countries]]</div>

<div class="docs-alert-warning"><i class="fa fa-check"></i> If you have customised the permissions on any of the files eg. /crons/pipe.php. These changes will need to be re-applied after the upgrade is complete.</div>

== Configuring Your Update Settings ==

=== Choosing an Update Channel ===

The WHMCS automatic updater allows you to choose an update channel that defines the type of updates you will receive.

For most users, we recommend choosing the '''Stable''' channel which will only apply Stable updates to your installation.

<table class="table table-striped">
<tr>
<td>'''Channel'''</td>
<td>'''Description'''</td>
</tr>
<tr>
<td>Stable</td>
<td>'''Recommended''' for most installations of WHMCS, the Stable channel will track the latest stable version that has been released.</td>
</tr>
<tr>
<td>Release Candidate</td>
<td>Subscribing to the Release Candidate channel will allow you to receive releases after beta testing but before they are released to the Stable tier.</td>
</tr>
<tr>
<td>Beta</td>
<td>Subscribing to the Beta release channel will allow you to receive the very latest versions of WHMCS. This tier should only be selected for development and test based installations.</td>
</tr>
<tr>
<td>Current Version</td>
<td>Subscribing to this channel will restrict you to only receiving maintenance updates for the major/minor version that is currently installed. For example if the installed version of WHMCS is 7.0.0-GA, admins will be offered upgrades to 7.0.1-GA and 7.0.2-GA, but not 7.1.0.</td>
</tr>
</table>

=== Setting a Temporary Update Path ===

A temporary path is required for staging of files during an update. For security reasons it is recommended that this directory be located outside the public doc root, similar to the attachments, downloads and templates_c directories. The path must be an absolute path (i.e. /home/whmcsuser/tmp instead of ~/tmp) and must be writable by the user that is running PHP.

=== Setting a Maintenance Message ===

This option can be used to set a message that will be displayed to both other admin and client users whenever an update is in progress.

<div class="docs-alert-info">Modifying the update configuration requires the '''Modify Update Configuration''' administrator role permission, which is separate from the "Update WHMCS" permission.</div>

[[File:Configureupdatesettings.png|center]]

== Troubleshooting ==
The actions performed by the Automatic Updater are recorded in the tblupdatelog table within the WHMCS database. To troubleshoot upgrade problems it is useful to review this table for the most recent entries (the highest id values). A tool such as phpmyadmin can be used to browse to the table contents.

===Please ensure you have selected a valid Update Channel and then try again===
Receiving this error message in the cron job report email or activity log, indicates that an Update Channel setting needs selecting. To do this, navigate to ''Utilities > Update WHMCS'' and click '''Configure Update Settings'''.

Next select one of the four available update channel options, and Click Save Changes. The options are [[#Choosing an Update Channel|described above]].

===Unable to connect to the WHMCS Update Server===
This error message may be encountered when attempting to perform an automatic update or appear in the Activity Log. It means that your server was unable to connect to our update server. From your server's command line, attempt the following two cURL connections:

<div class="source-cli">
curl https://releases.whmcs.com/packages.json

curl https://pki.whmcs.com/
</div>

The expected return is a '''StatusCode: 200'''. If any other results is returned please work with your server admin or hosting provider to investigate the connectivity problem between your server and the WHMCS update server.

===Permission Errors===
Permission errors may manifest themselves in the tblupdatelog table as the following:
<div class="source-cli">
[WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php
</div>
or
<div class="source-cli">
[RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.
</div>

These kinds of file permission and ownership issues are multi-faceted and dependant upon the individual server configuration. However for a standard '''cPanel''' server using the '''suPHP''' PHP Handler an appropriate posix file permissions permissions would be:

<div class="docs-alert-warning">
configuration.php - 400<br/>
/crons/pipe.php - 755<br/>
All other PHP files 644<br/>
All directories 755<br/>
</div>

The file ownership and group should be the same as the user directory name. Eg. On a cPanel box where the web-root is located at ''/home/'''david'''/public_html/'', files should be owned by '''david''', and the group should be '''david'''.

Finally, the owner and group of the PHP process seeking to take action should be the same as the user directory name. Eg. On a cPanel box where the web-root is located at ''/home/'''david'''/public_html/'', PHP process owner and group should be '''david'''.

Other types of server and PHP handlers may have different configuration requirements, the above is intended as a guide for one particular possible combination only.

===Curl 77 Error===
CURL77 errors may manifest as the following in the tblupdatelog table:
<div class="source-cli">
[WHMCS\Installer\Composer\ComposerUpdateException] Failed to get certificate metadata from keyserver. Error: Unable to download file from URL: Message cURL error 77: Problem with the SSL CA cert (path? access rights?) update [--prefer-source] [--prefer-dist] [--dry-run] [--dev] [--no-dev] [--lock] [--no-plugins] [--no-custom-installers] [--no-autoloader] [--no-scripts] [--no-progress] [--with-dependencies] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [-a|--classmap-authoritative] [--ignore-platform-reqs] [--prefer-stable] [--prefer-lowest] [-i|--interactive] [--root-reqs] [--] []...
</div>
This error indicates that the server was unable to connect to the WHMCS update server because the security of the connection could not be verified. The connection is secured using SSL certificates and to verify the certificate your server needs up-to-date root certificates to know which to trust.

Please work with your server administrator or hosting provider to ensure the root CA bundles are fully updated on your server.