WHMCS Documentation - User contributions [en]

Invoicing Issues

2024-05-22T16:03:15Z

JoshQ: /* Double Invoices/Charges/Blank Invoices */

There may be occasions when the system doesn't generate invoices properly. The problem is usually a misconfiguration or human error.

==Invoices/Payment Reminders not Generated==

Make certain to deselect '''Overdue Notices''' in the client's '''[[Clients:Profile Tab|Profile]]''' tab. This prevents the system from sending overdue notices to the client.

If the email templates do not exist, the system cannot send an email. Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates''' and ensure the '''Invoice Created''' and '''Overdue Notice''' email templates display.

Invoice generation, payment reminders, and account suspensions and terminations are some of the tasks that the daily [[Crons|cron job]] handles in accordance with your [[Automation Settings|automation settings]]. If you find that some or none of the above are occurring, this could indicate the cron job is not running successfully.

Review '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' ('''Utilities > Logs''' in WHMCS 7.x and earlier) and make sure that you see a number of entries beginning with ''Cron Job'' each day. The final entry every day should be ''Cron Job: Completed''.

* If you see no cron job entries, this means you have not configured your automation cron job correctly. You must do this per our installation instructions. For more information, see [[Crons|Crons]].

* If you see some cron job entries, but none after ''Cron Job: Running Usage Stats Update'', your cron job is getting stuck at the '''Usage Stats Update''' stage. The most likely cause of this error is that you have an old server in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers''' that is no longer available.
** To resolve this, update or remove any inactive or offline servers so that they can all connect successfully.
** Alternatively, you can disable '''Update Usage Statistics''' under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

* If you see some cron job entries but no ''Cron Job: Completed'' entry, your server may be prematurely terminating the cron job. Increase the <tt>memory_limit</tt> setting in your server's <tt>php.ini</tt> file to 64 MB or 128 MB. Then, check whether you start getting the cron job report again over the next few days.

If the cron job still doesn't complete with the increased memory limit, make sure that <tt>display_errors</tt> is enabled in the server's PHP configuration. Enable '''Display Errors''' 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'''. Then, visit the <tt>cron.php</tt> file in your browser to run the cron manually. You should now see error output.

For more information about the most common errors and their causes, see:

*[[Server Modules]]
*[[Domain Registrars]]
*[[Common_Troubleshooting_Tips#Server_Errors]]

==Items Not Invoicing==

There are a couple of reasons for invoices not generating. The most obvious reason is that there's a cancellation request for the service or it's in cancelled, terminated, fraud or expired status. For domains, selecting the '''Disable Auto Renew''' option stops the system from generating renewal invoices automatically. It could also be that the cron job is not running. For more information, see [[#Invoices/Payment Reminders not Generated|the section above]].

The system only generates invoices when the service's '''Next Due Date''' is within the '''Invoice Generation''' setting at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

For example, if the '''Next Due Date''' is in the future, the system won't generate an invoice. If today's date is 01/01/2012:

Next Due Date: 07/01/2012<br />
Invoice Generation: 7<br />
= Invoice '''will''' generate.

Next Due Date: 08/01/2012<br />
Invoice Generation: 7<br />
= Invoice '''not''' generated.

If it's none of those, then it's possible that the system generated an invoice that was then deleted by a member of staff. Check the client's '''[[Clients:Log Tab|Log]]''' tab for any ''Invoice Deleted'' or ''Order Deleted'' entries. WHMCS never generates duplicate invoices for the same service on the same due date, so if you require a new invoice after deleting an invoice, you must manually move the '''Next Due Date''' forward or back by one day.

==Double Invoices/Charges/Blank Invoices==

There are several invoicing issues that a common misconfiguration can cause. The system may generate two invoices for the same service and due date, may double-charge a client for the same invoice, or may generate a completely blank invoice.

A cron job running twice at the same time can cause this. The cron job should only run once per day, and should never run simultaneously. To confirm this, review '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' ('''Utilities > Logs''' in WHMCS 7.x and earlier). There should only be one ''Cron Job: Starting Daily Automation Tasks'' and one ''Cron Job: Completed Daily Automation Tasks'' entry per day. If there is more than one of either of these entries, check the server's cron job configuration to ensure there is only one entry for the <tt>cron.php</tt> file.

For more information, see our [[Crons]] documentation.

==Tax Not Applied to Invoices==

If the system has not applied tax, WHMCS may be operating as though it is not eligible under your tax rules.

First, ensure that tax is enabled and that you have selected the relevant '''Apply Tax''' options at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Tax Configuration]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Tax Configuration'''. If it's an invoice for a product, ensure this option is selected in the product configuration.

Secondly, ensure that '''Tax Exempt''' is deselected on the client's '''[[Clients:Profile Tab|Profile]]''' tab. A member of staff or our [[EU_VAT_Addon|EU VAT Invoicing]] addon module may have selected this.

Finally, the client might not match any of your tax rules. The state and country must be '''exact''' matches and are case sensitive. For example, if a tax rule exists for the state ''TX'' and the client's state is ''Texas'', these do not match and the system would not apply tax. This scenario would require two tax rules, one for ''TX'' and another for ''Texas''.

The system will apply any changes to subsequent invoices, but will not change existing invoices.

==Multiple Invoices for the same Service==

The system may generate multiple invoices for the same service with different due dates if the service has a due date in the past. This usually occurs with services that you import or a staff member manually added, in which the '''Next Due Date''' is <tt>00/00/0000</tt>. As this due date is in the past, WHMCS generates all invoices between then and today to ensure the client has paid their balance in full.

To correct this, change the '''Next Due Date''' to the date of the client's next payment via their '''[[Clients:Products/Services Tab|Products/Services]]''' tab. You can safely delete or cancel any erroneous invoices.

{{troubleshooting}}

Invoicing Issues

2024-05-22T16:02:51Z

JoshQ: /* Double Invoices/Charges/Blank Invoices */

There may be occasions when the system doesn't generate invoices properly. The problem is usually a misconfiguration or human error.

==Invoices/Payment Reminders not Generated==

Make certain to deselect '''Overdue Notices''' in the client's '''[[Clients:Profile Tab|Profile]]''' tab. This prevents the system from sending overdue notices to the client.

If the email templates do not exist, the system cannot send an email. Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates''' and ensure the '''Invoice Created''' and '''Overdue Notice''' email templates display.

Invoice generation, payment reminders, and account suspensions and terminations are some of the tasks that the daily [[Crons|cron job]] handles in accordance with your [[Automation Settings|automation settings]]. If you find that some or none of the above are occurring, this could indicate the cron job is not running successfully.

Review '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' ('''Utilities > Logs''' in WHMCS 7.x and earlier) and make sure that you see a number of entries beginning with ''Cron Job'' each day. The final entry every day should be ''Cron Job: Completed''.

* If you see no cron job entries, this means you have not configured your automation cron job correctly. You must do this per our installation instructions. For more information, see [[Crons|Crons]].

* If you see some cron job entries, but none after ''Cron Job: Running Usage Stats Update'', your cron job is getting stuck at the '''Usage Stats Update''' stage. The most likely cause of this error is that you have an old server in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers''' that is no longer available.
** To resolve this, update or remove any inactive or offline servers so that they can all connect successfully.
** Alternatively, you can disable '''Update Usage Statistics''' under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

* If you see some cron job entries but no ''Cron Job: Completed'' entry, your server may be prematurely terminating the cron job. Increase the <tt>memory_limit</tt> setting in your server's <tt>php.ini</tt> file to 64 MB or 128 MB. Then, check whether you start getting the cron job report again over the next few days.

If the cron job still doesn't complete with the increased memory limit, make sure that <tt>display_errors</tt> is enabled in the server's PHP configuration. Enable '''Display Errors''' 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'''. Then, visit the <tt>cron.php</tt> file in your browser to run the cron manually. You should now see error output.

For more information about the most common errors and their causes, see:

*[[Server Modules]]
*[[Domain Registrars]]
*[[Common_Troubleshooting_Tips#Server_Errors]]

==Items Not Invoicing==

There are a couple of reasons for invoices not generating. The most obvious reason is that there's a cancellation request for the service or it's in cancelled, terminated, fraud or expired status. For domains, selecting the '''Disable Auto Renew''' option stops the system from generating renewal invoices automatically. It could also be that the cron job is not running. For more information, see [[#Invoices/Payment Reminders not Generated|the section above]].

The system only generates invoices when the service's '''Next Due Date''' is within the '''Invoice Generation''' setting at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

For example, if the '''Next Due Date''' is in the future, the system won't generate an invoice. If today's date is 01/01/2012:

Next Due Date: 07/01/2012<br />
Invoice Generation: 7<br />
= Invoice '''will''' generate.

Next Due Date: 08/01/2012<br />
Invoice Generation: 7<br />
= Invoice '''not''' generated.

If it's none of those, then it's possible that the system generated an invoice that was then deleted by a member of staff. Check the client's '''[[Clients:Log Tab|Log]]''' tab for any ''Invoice Deleted'' or ''Order Deleted'' entries. WHMCS never generates duplicate invoices for the same service on the same due date, so if you require a new invoice after deleting an invoice, you must manually move the '''Next Due Date''' forward or back by one day.

==Double Invoices/Charges/Blank Invoices==

There are several invoicing issues that a common misconfiguration can cause. The system may generate two invoices for the same service and due date, may double-charge a client for the same invoice, or may generate a completely blank invoice.

A cron job running twice at the same time can cause this. The cron job should only run once per day, and should never run simultaneously. To confirm this, review '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' ('''Utilities > Logs''' in WHMCS 7.x and earlier). There should only be one ''Cron Job: Starting Daily Automation Tasks'' and one ''Cron Job: Completed Daily Automation Tasks'' entry per day. If there is more than one of either of these entries, check the server's cron job configuration to ensure there is only one entry for the <tt>cron.php</tt> file. For more information, see our [[Crons]] documentation.

==Tax Not Applied to Invoices==

If the system has not applied tax, WHMCS may be operating as though it is not eligible under your tax rules.

First, ensure that tax is enabled and that you have selected the relevant '''Apply Tax''' options at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Tax Configuration]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Tax Configuration'''. If it's an invoice for a product, ensure this option is selected in the product configuration.

Secondly, ensure that '''Tax Exempt''' is deselected on the client's '''[[Clients:Profile Tab|Profile]]''' tab. A member of staff or our [[EU_VAT_Addon|EU VAT Invoicing]] addon module may have selected this.

Finally, the client might not match any of your tax rules. The state and country must be '''exact''' matches and are case sensitive. For example, if a tax rule exists for the state ''TX'' and the client's state is ''Texas'', these do not match and the system would not apply tax. This scenario would require two tax rules, one for ''TX'' and another for ''Texas''.

The system will apply any changes to subsequent invoices, but will not change existing invoices.

==Multiple Invoices for the same Service==

The system may generate multiple invoices for the same service with different due dates if the service has a due date in the past. This usually occurs with services that you import or a staff member manually added, in which the '''Next Due Date''' is <tt>00/00/0000</tt>. As this due date is in the past, WHMCS generates all invoices between then and today to ensure the client has paid their balance in full.

To correct this, change the '''Next Due Date''' to the date of the client's next payment via their '''[[Clients:Products/Services Tab|Products/Services]]''' tab. You can safely delete or cancel any erroneous invoices.

{{troubleshooting}}

Stripe

2024-04-15T13:20:17Z

JoshQ: /* Migrating to Stripe */

== 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.

<div class="docs-alert-info">For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]]. </div>
{{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'''.

<div class="docs-alert-warning">
<span class="title">PCI DSS Compliance</span><br />
After migrating to Stripe, you may receive an email from Stripe requesting that you complete the [https://listings.pcisecuritystandards.org/documents/SAQ_D_v3_Merchant.pdf Self Assessment Questionnaire D] (SAQ D) form.

This is because the system is attempting to send raw card data that your previous merchant gateway stored to Stripe's API. You can only do this when your Stripe account has been flagged as [https://stripe.com/guides/pci-compliance PCI compliant].

To gain full access to Stripe's API, complete the SAQ D form to certify that you are PCI compliant and send it to Stripe. Stripe can then enable use of raw card data with their API.

For more information, [https://support.stripe.com/ contact Stripe support].
</div>

=== 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}}

System Environment Guide

2024-02-22T15:15:52Z

JoshQ: Add steps to resolve "Could not connect to database" error for Encrypted Database Connections

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 Privileges ===
When installing or updating WHMCS, activating or deactivating modules, or resetting the '''Module Log''' entries at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Logs''', you must grant the following privileges:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the 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.

=== Encrypted Database Connections ===

<div class="docs-alert-info">We added this support in WHMCS 8.8.</div>

Support for encrypted MySQL connections uses the following configuration variables in the <tt>configuration.php</tt> file:

* <tt>db_tls_ca</tt> — The path to the CA <tt>.pem</tt> file (for example, <tt>/var/www/html/whmcs/ca.pem</tt>).
* <tt>db_tls_ca_path</tt> — The path to the directory that contains the CA certificate files.
* <tt>db_tls_cert</tt> — The path to the client's certificate.
* <tt>db_tls_cipher</tt> — A list of one or more ciphers to use for SSL encryption, in an OpenSSL-compatible format.
* <tt>db_tls_key</tt> — The path to the client's key.
* <tt>db_tls_verify_cert</tt> — Disable (<tt>0</tt>) or enable (<tt>1</tt>) the server certificate.

You can configure these variables before, during, or after installation using the [[Install On The Command Line|command-line installation method]] or after installation using the [[Installing WHMCS|browser-based installation method]]. For steps, see [https://help.whmcs.com/m/installation/l/1706785-enabling-encrypted-mysql-connections Enabling Encrypted MySQL Connections].

<div class="docs-alert-warning">
If you set <tt>db_tls_verify_cert</tt> to <tt>1</tt> (enabled), the <tt>db_host</tt> value in the <tt>configuration.php</tt> file '''must''' match the Common Name (CN) or be a Subject Alternative Name (SAN) of the certificate that you specify for <tt>db_tls_cert</tt>.

If the hostname does not match and <tt>db_tls_verify_cert</tt> is enabled, you will see a <tt>Could not connect to database</tt> error. To resolve this issue, set <tt>db_tls_verify_cert</tt> to <tt>0</tt> or provide a new certificate with a CN or SAN that matches the <tt>db_host</tt> value.
</div>

<div class="docs-alert-info">
* For more information about the required MySQL configuration and variables, see [https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html Using Encrypted Connections] and [https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Current_tls_ca Server State Variables].
* For steps to configure encrypted MySQL connections on cPanel & WHM servers, see [https://docs.cpanel.net/knowledge-base/security/how-to-configure-mysql-ssl-connections/ cPanel's How to Configure MySQL SSL Connections Documentation].
</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 (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; 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.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; JSON
: JSON exchanges data in the UI (for example, displaying success messages after completing an action like changing a password on a service).
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.
; 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.
;Reflection
: Reflection adds the ability to examine and identify classes, interfaces, functions, methods, and extensions within your application. As part of this, the extension can check also for and retrieve documented comments within the same classes, interfaces, functions, and methods.
; 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.
; XML
: WHMCS uses the SimpleXML extension that PHP compiles by default. It is highly used for communication with remote systems, such as registrars, payment gateways, and servers.

==== Recommended ====
; 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.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; 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.
; Intl
: Intl performs character inspection and transformation, such as in IDN to perform Punycode conversions and transliterations. While we provide a third party dependency to compensate for the absence of Intl, it is much more performant to have the actual extension in the environment.
; 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.

=== 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}}

WHMCS cPanel Licensing Module

2024-01-29T16:07:43Z

JoshQ: Add steps to follow after changing Manage2 credentials.

== About this Addon Module ==

<div class="docs-alert-warning">
<span class="title">Licensing Addon</span><br />
* The cPanel Licensing Automation module is not associated with the WHMCS [[Licensing Addon]].
* This module is for cPanel Partners. If you are not yet a partner, see [https://www.cpanel.net/partners/ the cPanel website].
</div>

The cPanel Licensing Automation module for WHMCS is a tool that utilizes the cPanel Manage2 API to provide an automated solution for cPanel Partners to provision, manage, and bill for cPanel & WHM licenses.

For help to get started, see [[WHMCS cPanel Licensing Module Getting Started Guide]].

<table class="table" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;">
<tr>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Addon Name</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Latest Release</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Current Version</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Compatible With</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Included in WHMCS</th>
</tr>
<tr>
<td style="border:1px #AAA solid;padding:0.2em;">WHMCS cPanel Licensing Module</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;color:darkred;">No</td>
</tr>
</table>

== Activating WHMCS cPanel Licensing Module ==

You will need to download and upload the module before you can activate the addon through the Admin Area.

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the <tt>cpanellicensing</tt> directory to the <tt>/modules/addons</tt> folder of your WHMCS installation.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' or, prior to WHMCS 8.0, '''Setup > Addon Modules'''.
# Click '''Activate''' for '''cPanel Licensing'''.
# Click '''Configure'''.
# Select the admin role groups who will have access to this addon.
# Select the admin users who can configure settings within the addon.
# Click '''Save Changes'''.

== Using WHMCS cPanel Licensing Module ==

[[File:CPLic_AuthenticatingIntoManage2.png|thumb|Manage2 Login Prompt]]

After configuring the module, you will need to authenticate into Manage2.

To do this, navigate to '''Addons > cPanel Licensing''' and log in using your Manage2 username and password. The system will import your Manage2 data into WHMCS. This may take several minutes depending on the amount of licenses associated with the Manage2 account.

=== Autoscale ===

'''Autoscale''' allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of accounts associated with its cPanel license. Use the Autoscale settings below when you want WHMCS to automatically upgrade a license to the next tier based on usage.

Autoscale uses the following procedure:

# A server administrator provisions an extra cPanel account which in turn pushes the server into the next cPanel license tier.
# cPanel's Manage2 software detects this and changes the license tier for billing purposes in the cPanel Partner account.
# WHMCS performs a synchronisation with Manage2 at specific intervals that picks up this change.
# The Control Panel configurable option in WHMCS changes to match the new cPanel license tier and as a result of this, the service price is auto recalculated to include the additional cost of the new license tier.
# The next renewal invoice generated by the service (per the Next Due Date) will reflect the new cPanel license tier.

This ensures that the client is always billed appropriately for their current cPanel license tier without any manual intervention.

=== Settings ===

[[File:CPLic_Settings.png|thumb|Settings Tab]]

The cPanel Licensing addon offers further configuration settings concerning Data and API Permissions, as well as Invoice and Cart Display Options.

These can be accessed by navigating to '''Addons > cPanel Licensing''', and then clicking on the '''Settings''' tab. The settings seen on this page are detailed below.

==== Data and API Permissions ====

*'''Manage2 Account''' - Your Manage2 Registered Email. Here you will see the logged in user and a '''Logout''' button.
*'''Provisioning Default Group''' - The default group to assign new licenses to.
*'''Permissions''' - Access controls for functionality within this addon.

==== Invoice and Cart Display Options ====

*'''Invoicing Line Item Format''' - The line item description used for invoicing by packages that offer bulk cPanel accounts.
*'''Option Info Tooltip''' - Optional tooltip text to display near license configurable options during checkout. HTML is supported.
*'''Option Description Format''' - The configurable option selection format for display on the order form for packages that offer bulk cPanel accounts.
*'''Autoscale Label''' - The label to be displayed on the order form.
*'''Autoscale Notification Email''' - The email template to be sent upon an autoscale change. For more information, see the [[WHMCS cPanel Licensing Module#Autoscale Notification Email|Autoscale Notification Email]] section.

==== Autoscale Notification Email ====

The cPanel Licensing module can be configured to send a custom email notification to a client upon an Autoscale Change.

To configure this functionality you will need to first create the custom email to be used. You can do this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates'''. This custom email template type must be either '''Product/Service Messages''' or '''Notification Messages'''.

The custom template to be used will have access to the following merge fields:

*'''newOption''' - The display name of the configurable option being upgraded to.
*'''oldOption''' - The display name of the configurable option being upgrade from.
*'''isUsageUpgrade''' - A boolean indicating whether or not the upgrade is due to usage activity.

Once the custom email template has been created, it can be set as the ''Autoscale Notification Email'' template.

To do this:

# Go to '''Addons > cPanel Licensing'''.
# Click on the '''Settings''' tab.
# Locate the '''Autoscale Notification Email''' setting.
# Select the custom email template from the menu.
# Click '''Save Changes'''.

=== Pricing ===

[[File:CPLic_Pricing.png|thumb|Pricing Tab]]

cPanel licenses are sold as configurable options of products. This interface allows you to set pricing for those options as well as respective metric pricing for cPanel accounts.

Typically the configurable option would be assigned to a product with which a cPanel license would beneficial; a VPS or Dedicated Server. It can also be sold as a [[#Standalone_Product|standalone product]].

On this tab you will see the ''ID'', ''Configuration Name'', ''Selections'', and ''Auto-Scale'' columns displayed for each option that has been created with, or imported into, the cPanel Licensing addon.

Additionally, you will see buttons labelled ''New'', ''Import'', and ''Manage'' which allow you to create, import, and manage options respectively. The functionality of these buttons is detailed below.

==== Create New Option ====

[[File:CPLic_CreateNewOption.png|thumb|Create New Option Modal]]

Clicking on the ''New'' button will bring up the ''Create New Option'' modal. It is within this modal that you can create a new [[Configurable Options|configurable option]] to be used for offering cPanel licenses to your customers via this module.

The following configuration settings are displayed on this modal:

*'''Parent Group''' - The option group to create the new option within. Should the ''Create New Group'' option be selected, then the ''Group Name'' option will appear.
*'''Group Name''' - The name for the new configurable option group. This option will only appear when the ''Create New Group'' option has been selected from the ''Parent Group'' drop-down menu.
*'''Option Name''' - The display name for the new configurable option.
*'''Option Type''' - The type to be used by the new configurable option. Only drop-down and radio option types are supported.
*'''Auto-Populate''' - Automatically populate the new option with the default cPanel license package offerings and recommended retail pricing.
*'''Hardware Type''' - Offers a selection between the ''Dedicated/Metal'' and ''VPS/Cloud'' options.
*'''Default Visibility''' - Toggles whether or not the option is visible from the Order Form.

Once the settings have been completed, clicking on the ''Create'' button will generate the Configurable Option Group, create Configurable Options if the ''Auto-Populate'' option was selected, and display the option group in the Pricing tab of the module.

==== Import Existing Option ====

[[File:CPLic_ImportExistingOption.png|thumb|Import Existing Option Modal]]

If you have an existing '''Configurable Option Group''' and '''Configurable Options''' that you would like to be used for the provisioning and billing of cPanel licenses, then these can be imported for use with the cPanel Licensing addon.

During this process you will be prevented with a list of configurable options, and be asked to associate them with a cPanel Package. If a configurable option is not related to a cPanel license, then leave the dropdown at the ''Not a cPanel License Option'' value. Options left at this value will not be used by the cPanel Licensing module, and will continue to function as a normal configurable option.

<div class="docs-alert-warning">Only ''Dropdown'' or ''Radio'' configurable options are supported for import. Other option types will not be available for import.</div>

Clicking on the ''Import'' button will bring up the ''Import Existing Option'' modal. It is within this modal that you can import an existing configurable option to be used for the provisioning and billing of cPanel licenses via this module.

Within the ''Import Existing Option'' modal you will be presented with the ''Option Name'' drop-down menu. This menu allows you to select which Configurable Option you would like to import.

Selecting the desired option from the drop-down and clicking the ''Continue'' button will bring you to the ''Configure Import'' section. Here you will see a list of ''Selectable Options'' displayed. For each selectable option, please select a cPanel Package below that it relates to. If an option is not related to a cPanel license, leave the dropdown at the default value.

Clicking the ''Import'' button will import the configurable options into the module, and make them available for further configuration via the ''Pricing'' tab.

====Option & Price Management====

[[File:CPLic_OptionPriceManagement.png|thumb|Option & Price Management Modal]]

Within the ''Manage'' column for each associated option a button with a wrench icon exists. This is the ''Manage'' button, and clicking on this button will bring up the ''Option & Price Management'' modal. It is within this modal that you can modify options within the group, as well as modify the cPanel related options themselves.

This modal is made up of three elements: the ''Configurable Option Settings'' section in the top-left, the ''Selectable Options'' section in the bottom-left, and the ''Selectable Option Content'' panel on the right.

===== Configurable Option Settings =====

The '''Configurable Option Settings''' section provides the ability to alter the ''Configurable Option Type'', and toggle both the ''Visibility'' and ''Autoscale'' Option.

The '''Autoscale Option''' toggle allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of licenses associated with its cPanel account. This should be used when you want WHMCS to automatically upgrade a license to the next tier based on usage. Enabling this option requires that all configurable options associated with a cPanel Package have pricing configured.

All changes made in this section are automatically saved.

===== Selectable Options =====

The '''Selectable Options''' section displays the full list of existing configurable options, and offers the ability to create new options via the ''Add Option'' button. Clicking on an option from this list will display that option's content within the ''Selectable Option Content'' panel.

Additionally, in Version 7.7 and later, dragging the options allow you to rearrange their order as desired. All changes made in this section are automatically saved.

===== Selectable Option Content =====

The '''Selectable Option Content''' section provides both an overview of that option, as well as the ability to configure it further. The ''Name'', ''Visibility'', and ''Package'' details are immediately displayed at the top, and can all be altered as desired. Additionally, the ''Configurable Option ID'' is displayed in the top-left corner.

The Pricing section is offers the ability to configure pricing for the option. Here the ''Base Recurring'', and ''Setup Fee'' values can be modified. The ''Metric: cPanel Accounts'' and ''Threshold'' values can also be modified for packages that support them.

The ''Auto populate other billing cycles based on monthly pricing'' toggle will render the Billing Cycle tabs un-clickable and will automatically populate their pricing based on the pricing present in the Monthly pricing tab.

Changes to this section are not automatically saved, and clicking on the ''Save'' button will commit the changes. Inversely, clicking on the ''Delete'' button will delete the configurable option.

===== Metric: cPanel Accounts =====

The '''Metric: cPanel Accounts''' setting is displayed when configuring pricing for packages that offer an unlimited number of cPanel accounts. This setting provides the ability to set a per-account value that the customer will be billed for, as well as a threshold to define the number of accounts a customer must have before they are billed on a per-account basis.

When a customer orders a package, with the ''Metric: cPanel Accounts'' offering, a snapshot of the current price is taken. This snapshot is then stored, and used when generating renewal invoices for the customer's service in the future. This is done to ensure that changes can be made to a package's metric pricing without affecting existing customer orders.

If you need to ensure that the pricing snapshot is updated to the current metric pricing, then this can be achieved by selecting the [[Clients:Products/Services_Tab#Auto_Recalculate_on_Save|''Auto Recalculate on Save'']] checkbox and saving the service. This will see the existing snapshot discarded, and a new one created with the current metric pricing for the associated package.

The cPanel Licensing Addon retrieves the cPanel account value from the cPanel licensing system (Manage2) at the time of invoice generation. This is to ensure use of the most accurate value relative to Manage2, to which the license reseller is accountable. Manage2 doesn't provide the historical data necessary to calculate any prior month's usage. At this time, the cPanel Licensing Addon doesn't have historical snapshot capabilities that can augment this canonical data source.

The ''Auto Recalculate on Save'' option will continue to function as normal. When used a service's ''Recurring Amount'' will be populated with current pricing based on the service and configurable options selected.

====Standalone Product====

To present a standalone product that provisions a cPanel license, use the cPanel licensing module with the Auto Release provisioning module:

# 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'''.[[File:Cpanel standalone2.png|thumb|Configure Pricing]]
#Click '''Create a New Product'''.
#Select '''Other''' for '''Product Type'''.
#Enter a '''Product Name'''.
#Select ''Auto Release'' for '''Module Name'''.
#Click '''Continue'''.
# Select the '''Pricing''' tab.
#Choose '''Recurring''' for '''Payment Type'''.[[File:Cpanel standalone3.png|thumb|Configure the Auto Release Module]]
# Check the checkboxes in the '''One Time/Monthly''' column.
#Specify '''Setup''' and '''Price''' values of <tt>0.00</tt>.
#Select the '''Module Settings''' tab.
#Choose the '''Automatically setup the product as soon as the first payment is received''' option.
#Select the '''Configurable Options''' tab.
#Click the configurable option group for the cPanel license types. The cPanel Licensing Addon [[#Pricing|creates this]].
#Configure any other options are desired.
#Click '''Save Changes'''.

When this product is ordered, clients will be presented with the cPanel License Tier configurable option at the product configuration stage of the shopping cart and a license provisioned upon payment. The price of the configurable option will form the amount invoiced to the client each month.

===Manage2 Data===
The data imported from Manage2 is displayed within the module itself. This information is located within the ''Licenses'', ''Groups'', and ''Packages'' tabs. This allows you to quickly review and action your Manage2 data without leaving WHMCS.

====Licenses====
[[File:CPLic_Manage2DataLicenses.png|thumb|Licenses Tab]]

Licenses are associated with a clients' services. This interface allows modification of the license data stored at Manage2. The WHMCS data can be managed at the linked service.

On this tab you will see ''License ID'', ''Package/Group'', ''IP/Hostname'', ''Assigned Service'', and ''Status'' columns displayed for each license associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated license.

*'''Assign License''' - Assign the license to an existing service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.
*'''Change IP''' - Change the license's IP Address.
*'''Change group''' - Change the license's Group.
*'''Change package''' - Change the license's Package.
*'''Expire''' - Expire the license within Manage2.
*'''View License Details''' - Review a detailed output of license information.

====Groups====
[[File:CPLic_Manage2DataGroups.png|thumb|Groups Tab]]

Groups are arbitrary categories. They are unique to your Company. They can help keep your licenses organised by modeling how you sell and manage the product-customer lifecycle.

On this tab you will see the ''Group ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each group associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated group.

*'''Change name''' - Change the group's name within Manage2.
*'''Change tax status''' - Change the group's tax status within Manage2.
*'''Show Licenses''' - Display a filtered list of licenses associated with the specific group.

====Packages====
[[File:CPLic_Manage2DataPackages.png|thumb|Packages Tab]]

Packages are SKUs. They represent the product, features, or bundled options that are granted to the license holder.

On this tab you will see the ''Package ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each package associated with your Manage2 account.

The ''Actions'' column offers the ability to perform the following actions against the associated package.

*'''Show Licenses''' - Display a filtered list of licenses associated with the specific package.

===Service Management===
[[File:CPLic_ServiceManagement.png|thumb|cPanel Licensing Service Panel]]

Services associated with a cPanel Licensing related Option Group will see a panel labeled ''cPanel Licensing'' when viewing that service via the Admin Area.

When a service is associated with a cPanel license, an overview if the license details is displayed along with the following buttons:

*'''Sync IP''' - Change the license's IP Address to the value displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Sync Package''' - Change the license's Package to the value displayed in the cPanel Licensing configurable option.
*'''View Details''' - Display a modal containing the cPanel License Information.
*'''Expire''' - Expire the license within Manage2.

The following buttons will be displayed within the panel at all times:

*'''Provision New cPanel License''' - Automatically provision a new license from Manage2 using the package displayed in the cPanel Licensing configurable option and the IP address displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Link to Existing License''' - Display a modal that allows for the search of existing licenses to be assigned to the service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.

===Handling Manual License Cancellations===
Expiring a license, either by clicking '''Expire''' in the '''[[Clients:Products/Services_Tab|Products/Services]]''' tab of the client profile or in Manage2, does not automatically update the '''Recurring Amount''' for the parent service. The system cannot determine whether to bill a license using the license's state.

To cancel a license and ensure that the system updates the '''Recurring Amount''' value correctly:
# Click '''Expire''' in the '''Service Management''' section.
# Set the parent service's [[WHMCS cPanel Licensing Module#Configurable Option Settings|configurable option]] to ''None''.
# Set '''Recalculate on Save''' to ''ON''.
# Click '''Save Changes'''.

The system will update the parent service's '''Recurring Amount''' to no longer include the cost of the expired license.

===Assign License & Link to Existing License===
[[File:CPLic_AssignLicense.png|thumb|Assign License Modal]]
[[File:CPLic_LinkExistingLicense.png|thumb|Link to Existing License Modal]]

Both the Licenses tab, seen on the cPanel Licensing module page, and the cPanel Licensing panel, seen on the Service page, offer the ability to manually assign a service to a license and vice versa.

The '''Assign License''' modal provides a searchable drop-down menu that can be used to locate and select the desired service. Once the service has been selected, clicking on the ''Assign'' button will assign the service to that specific license.

The '''Link to Existing License''' modal provides a searchable drop-down menu that can be used to locate and select the desired license. Once the license has been selected, clicking on the ''Assign'' button will assign the license to that specific service.

In both cases, it is important to note that the configurable option will not be automatically selected. You must navigate to the Service page in the Admin Area, set the configurable option to coincide with the appropriate package if fixed, or enable the autoscale option if applicable. '''This is necessary for automated billing to occur.'''

Additionally, only a singular active license can be assigned to a service. Using the ''Link to Existing License'' or ''Assign License'' functionality to assign a new license to a service already in possession of an active license will result in the replacement of that active license. In this instance, a prompt will appear to confirm this action.

===Updating Manage2 Account Credentials===

The cPanel Licensing Addon uses your Manage2 username and password to authenticate with the Manage2 API. To facilitate this, the system encrypts and stores your Manage2 credentials in WHMCS's database. Because updating your credentials in Manage2 does not automatically trigger an update in WHMCS, the system will no longer be able to successfully authenticate requests.

After updating your Manage2 credentials, ensure that the system can communicate with Manage2:

# In the Admin Area, go to '''Addons > cPanel Licensing''' and click on the '''Settings''' tab.
# In the '''Manage2 Account''' section, click '''Logout'''.
# Log in using your Manage2 account credentials.

After successfully logging in, the system will store your new Manage2 login details in the database.

== Upgrading ==

If you have an earlier version of the cPanel Licensing Module installed, follow the steps below:

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the 'cpanellicensing' directory to the '/modules/addons' folder of your WHMCS installation.

====Troubleshooting====
This section covers the error messages which may be encountered during license assignment.

=====A license was deactivated on the same IP last month before billing could occur=====
This response indicates that the previous cPanel license associated with the service's IP address accrued usage, and was deactivated before billing could occur within Manage2.

A reactivation fee must be paid before a new license can be provisioned for that IP address. This must be done via Manage2 directly.

=====This license is already assigned to another service=====
Review the '''Addons > cPanel Licensing''' page to see the current service to which the license is assigned in WHMCS.

Click the ''Assign'' button a second time to remove the current assignment and assign to the current service.

=====You cannot assign a license to this service=====
'''You cannot assign a license to this service as the product to which it is assigned does not have a configurable option for a cPanel license'''

There is no license pricing configuration assigned to the product in use, a license can only be assigned when a pricing scheme is associated with the product. The following steps will make the necessary adjustments to the product/service configuration:

# Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Check whether the cPanel Licenses configurable option appears. If it does not:
## 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'''.
## Click '''Edit''' for the cPanel licensing option group.
## Press Ctrl + Click to select all the applicable products that will offer a cPanel license option. Make certain to select the product that is currently exhibiting the error.
## Click '''Save Changes'''.
# If the cPanel License configurable option is displayed, select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

=====cPanel Licensing options of product are not set for this service=====

'''cPanel Licensing options of product are not set for this service. Review and save the cPanel licensing options for this service and try again'''

A license pricing configuration is assigned to the product in use, but the desired option has not been selected for the individual service record. WHMCS needs to know the desired license tier to invoice the client correctly.

The following steps will make the necessary adjustments to the service record:

# Go to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Use the cPanel License configurable option to select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

== Change Log ==

''N/A''

WHMCS cPanel Licensing Module

2024-01-17T14:59:55Z

JoshQ: Add steps for manually cancelling a license

== About this Addon Module ==

<div class="docs-alert-warning">
<span class="title">Licensing Addon</span><br />
* The cPanel Licensing Automation module is not associated with the WHMCS [[Licensing Addon]].
* This module is for cPanel Partners. If you are not yet a partner, see [https://www.cpanel.net/partners/ the cPanel website].
</div>

The cPanel Licensing Automation module for WHMCS is a tool that utilizes the cPanel Manage2 API to provide an automated solution for cPanel Partners to provision, manage, and bill for cPanel & WHM licenses.

For help to get started, see [[WHMCS cPanel Licensing Module Getting Started Guide]].

<table class="table" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;">
<tr>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Addon Name</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Latest Release</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Current Version</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Compatible With</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Included in WHMCS</th>
</tr>
<tr>
<td style="border:1px #AAA solid;padding:0.2em;">WHMCS cPanel Licensing Module</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;color:darkred;">No</td>
</tr>
</table>

== Activating WHMCS cPanel Licensing Module ==

You will need to download and upload the module before you can activate the addon through the Admin Area.

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the <tt>cpanellicensing</tt> directory to the <tt>/modules/addons</tt> folder of your WHMCS installation.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' or, prior to WHMCS 8.0, '''Setup > Addon Modules'''.
# Click '''Activate''' for '''cPanel Licensing'''.
# Click '''Configure'''.
# Select the admin role groups who will have access to this addon.
# Select the admin users who can configure settings within the addon.
# Click '''Save Changes'''.

== Using WHMCS cPanel Licensing Module ==

[[File:CPLic_AuthenticatingIntoManage2.png|thumb|Manage2 Login Prompt]]

After configuring the module, you will need to authenticate into Manage2.

To do this, navigate to '''Addons > cPanel Licensing''' and log in using your Manage2 username and password. The system will import your Manage2 data into WHMCS. This may take several minutes depending on the amount of licenses associated with the Manage2 account.

=== Autoscale ===

'''Autoscale''' allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of accounts associated with its cPanel license. Use the Autoscale settings below when you want WHMCS to automatically upgrade a license to the next tier based on usage.

Autoscale uses the following procedure:

# A server administrator provisions an extra cPanel account which in turn pushes the server into the next cPanel license tier.
# cPanel's Manage2 software detects this and changes the license tier for billing purposes in the cPanel Partner account.
# WHMCS performs a synchronisation with Manage2 at specific intervals that picks up this change.
# The Control Panel configurable option in WHMCS changes to match the new cPanel license tier and as a result of this, the service price is auto recalculated to include the additional cost of the new license tier.
# The next renewal invoice generated by the service (per the Next Due Date) will reflect the new cPanel license tier.

This ensures that the client is always billed appropriately for their current cPanel license tier without any manual intervention.

=== Settings ===

[[File:CPLic_Settings.png|thumb|Settings Tab]]

The cPanel Licensing addon offers further configuration settings concerning Data and API Permissions, as well as Invoice and Cart Display Options.

These can be accessed by navigating to '''Addons > cPanel Licensing''', and then clicking on the '''Settings''' tab. The settings seen on this page are detailed below.

==== Data and API Permissions ====

*'''Manage2 Account''' - Your Manage2 Registered Email. Here you will see the logged in user and a '''Logout''' button.
*'''Provisioning Default Group''' - The default group to assign new licenses to.
*'''Permissions''' - Access controls for functionality within this addon.

==== Invoice and Cart Display Options ====

*'''Invoicing Line Item Format''' - The line item description used for invoicing by packages that offer bulk cPanel accounts.
*'''Option Info Tooltip''' - Optional tooltip text to display near license configurable options during checkout. HTML is supported.
*'''Option Description Format''' - The configurable option selection format for display on the order form for packages that offer bulk cPanel accounts.
*'''Autoscale Label''' - The label to be displayed on the order form.
*'''Autoscale Notification Email''' - The email template to be sent upon an autoscale change. For more information, see the [[WHMCS cPanel Licensing Module#Autoscale Notification Email|Autoscale Notification Email]] section.

==== Autoscale Notification Email ====

The cPanel Licensing module can be configured to send a custom email notification to a client upon an Autoscale Change.

To configure this functionality you will need to first create the custom email to be used. You can do this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates'''. This custom email template type must be either '''Product/Service Messages''' or '''Notification Messages'''.

The custom template to be used will have access to the following merge fields:

*'''newOption''' - The display name of the configurable option being upgraded to.
*'''oldOption''' - The display name of the configurable option being upgrade from.
*'''isUsageUpgrade''' - A boolean indicating whether or not the upgrade is due to usage activity.

Once the custom email template has been created, it can be set as the ''Autoscale Notification Email'' template.

To do this:

# Go to '''Addons > cPanel Licensing'''.
# Click on the '''Settings''' tab.
# Locate the '''Autoscale Notification Email''' setting.
# Select the custom email template from the menu.
# Click '''Save Changes'''.

=== Pricing ===

[[File:CPLic_Pricing.png|thumb|Pricing Tab]]

cPanel licenses are sold as configurable options of products. This interface allows you to set pricing for those options as well as respective metric pricing for cPanel accounts.

Typically the configurable option would be assigned to a product with which a cPanel license would beneficial; a VPS or Dedicated Server. It can also be sold as a [[#Standalone_Product|standalone product]].

On this tab you will see the ''ID'', ''Configuration Name'', ''Selections'', and ''Auto-Scale'' columns displayed for each option that has been created with, or imported into, the cPanel Licensing addon.

Additionally, you will see buttons labelled ''New'', ''Import'', and ''Manage'' which allow you to create, import, and manage options respectively. The functionality of these buttons is detailed below.

==== Create New Option ====

[[File:CPLic_CreateNewOption.png|thumb|Create New Option Modal]]

Clicking on the ''New'' button will bring up the ''Create New Option'' modal. It is within this modal that you can create a new [[Configurable Options|configurable option]] to be used for offering cPanel licenses to your customers via this module.

The following configuration settings are displayed on this modal:

*'''Parent Group''' - The option group to create the new option within. Should the ''Create New Group'' option be selected, then the ''Group Name'' option will appear.
*'''Group Name''' - The name for the new configurable option group. This option will only appear when the ''Create New Group'' option has been selected from the ''Parent Group'' drop-down menu.
*'''Option Name''' - The display name for the new configurable option.
*'''Option Type''' - The type to be used by the new configurable option. Only drop-down and radio option types are supported.
*'''Auto-Populate''' - Automatically populate the new option with the default cPanel license package offerings and recommended retail pricing.
*'''Hardware Type''' - Offers a selection between the ''Dedicated/Metal'' and ''VPS/Cloud'' options.
*'''Default Visibility''' - Toggles whether or not the option is visible from the Order Form.

Once the settings have been completed, clicking on the ''Create'' button will generate the Configurable Option Group, create Configurable Options if the ''Auto-Populate'' option was selected, and display the option group in the Pricing tab of the module.

==== Import Existing Option ====

[[File:CPLic_ImportExistingOption.png|thumb|Import Existing Option Modal]]

If you have an existing '''Configurable Option Group''' and '''Configurable Options''' that you would like to be used for the provisioning and billing of cPanel licenses, then these can be imported for use with the cPanel Licensing addon.

During this process you will be prevented with a list of configurable options, and be asked to associate them with a cPanel Package. If a configurable option is not related to a cPanel license, then leave the dropdown at the ''Not a cPanel License Option'' value. Options left at this value will not be used by the cPanel Licensing module, and will continue to function as a normal configurable option.

<div class="docs-alert-warning">Only ''Dropdown'' or ''Radio'' configurable options are supported for import. Other option types will not be available for import.</div>

Clicking on the ''Import'' button will bring up the ''Import Existing Option'' modal. It is within this modal that you can import an existing configurable option to be used for the provisioning and billing of cPanel licenses via this module.

Within the ''Import Existing Option'' modal you will be presented with the ''Option Name'' drop-down menu. This menu allows you to select which Configurable Option you would like to import.

Selecting the desired option from the drop-down and clicking the ''Continue'' button will bring you to the ''Configure Import'' section. Here you will see a list of ''Selectable Options'' displayed. For each selectable option, please select a cPanel Package below that it relates to. If an option is not related to a cPanel license, leave the dropdown at the default value.

Clicking the ''Import'' button will import the configurable options into the module, and make them available for further configuration via the ''Pricing'' tab.

====Option & Price Management====

[[File:CPLic_OptionPriceManagement.png|thumb|Option & Price Management Modal]]

Within the ''Manage'' column for each associated option a button with a wrench icon exists. This is the ''Manage'' button, and clicking on this button will bring up the ''Option & Price Management'' modal. It is within this modal that you can modify options within the group, as well as modify the cPanel related options themselves.

This modal is made up of three elements: the ''Configurable Option Settings'' section in the top-left, the ''Selectable Options'' section in the bottom-left, and the ''Selectable Option Content'' panel on the right.

===== Configurable Option Settings =====

The '''Configurable Option Settings''' section provides the ability to alter the ''Configurable Option Type'', and toggle both the ''Visibility'' and ''Autoscale'' Option.

The '''Autoscale Option''' toggle allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of licenses associated with its cPanel account. This should be used when you want WHMCS to automatically upgrade a license to the next tier based on usage. Enabling this option requires that all configurable options associated with a cPanel Package have pricing configured.

All changes made in this section are automatically saved.

===== Selectable Options =====

The '''Selectable Options''' section displays the full list of existing configurable options, and offers the ability to create new options via the ''Add Option'' button. Clicking on an option from this list will display that option's content within the ''Selectable Option Content'' panel.

Additionally, in Version 7.7 and later, dragging the options allow you to rearrange their order as desired. All changes made in this section are automatically saved.

===== Selectable Option Content =====

The '''Selectable Option Content''' section provides both an overview of that option, as well as the ability to configure it further. The ''Name'', ''Visibility'', and ''Package'' details are immediately displayed at the top, and can all be altered as desired. Additionally, the ''Configurable Option ID'' is displayed in the top-left corner.

The Pricing section is offers the ability to configure pricing for the option. Here the ''Base Recurring'', and ''Setup Fee'' values can be modified. The ''Metric: cPanel Accounts'' and ''Threshold'' values can also be modified for packages that support them.

The ''Auto populate other billing cycles based on monthly pricing'' toggle will render the Billing Cycle tabs un-clickable and will automatically populate their pricing based on the pricing present in the Monthly pricing tab.

Changes to this section are not automatically saved, and clicking on the ''Save'' button will commit the changes. Inversely, clicking on the ''Delete'' button will delete the configurable option.

===== Metric: cPanel Accounts =====

The '''Metric: cPanel Accounts''' setting is displayed when configuring pricing for packages that offer an unlimited number of cPanel accounts. This setting provides the ability to set a per-account value that the customer will be billed for, as well as a threshold to define the number of accounts a customer must have before they are billed on a per-account basis.

When a customer orders a package, with the ''Metric: cPanel Accounts'' offering, a snapshot of the current price is taken. This snapshot is then stored, and used when generating renewal invoices for the customer's service in the future. This is done to ensure that changes can be made to a package's metric pricing without affecting existing customer orders.

If you need to ensure that the pricing snapshot is updated to the current metric pricing, then this can be achieved by selecting the [[Clients:Products/Services_Tab#Auto_Recalculate_on_Save|''Auto Recalculate on Save'']] checkbox and saving the service. This will see the existing snapshot discarded, and a new one created with the current metric pricing for the associated package.

The cPanel Licensing Addon retrieves the cPanel account value from the cPanel licensing system (Manage2) at the time of invoice generation. This is to ensure use of the most accurate value relative to Manage2, to which the license reseller is accountable. Manage2 doesn't provide the historical data necessary to calculate any prior month's usage. At this time, the cPanel Licensing Addon doesn't have historical snapshot capabilities that can augment this canonical data source.

The ''Auto Recalculate on Save'' option will continue to function as normal. When used a service's ''Recurring Amount'' will be populated with current pricing based on the service and configurable options selected.

====Standalone Product====

To present a standalone product that provisions a cPanel license, use the cPanel licensing module with the Auto Release provisioning module:

# 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'''.[[File:Cpanel standalone2.png|thumb|Configure Pricing]]
#Click '''Create a New Product'''.
#Select '''Other''' for '''Product Type'''.
#Enter a '''Product Name'''.
#Select ''Auto Release'' for '''Module Name'''.
#Click '''Continue'''.
# Select the '''Pricing''' tab.
#Choose '''Recurring''' for '''Payment Type'''.[[File:Cpanel standalone3.png|thumb|Configure the Auto Release Module]]
# Check the checkboxes in the '''One Time/Monthly''' column.
#Specify '''Setup''' and '''Price''' values of <tt>0.00</tt>.
#Select the '''Module Settings''' tab.
#Choose the '''Automatically setup the product as soon as the first payment is received''' option.
#Select the '''Configurable Options''' tab.
#Click the configurable option group for the cPanel license types. The cPanel Licensing Addon [[#Pricing|creates this]].
#Configure any other options are desired.
#Click '''Save Changes'''.

When this product is ordered, clients will be presented with the cPanel License Tier configurable option at the product configuration stage of the shopping cart and a license provisioned upon payment. The price of the configurable option will form the amount invoiced to the client each month.

===Manage2 Data===
The data imported from Manage2 is displayed within the module itself. This information is located within the ''Licenses'', ''Groups'', and ''Packages'' tabs. This allows you to quickly review and action your Manage2 data without leaving WHMCS.

====Licenses====
[[File:CPLic_Manage2DataLicenses.png|thumb|Licenses Tab]]

Licenses are associated with a clients' services. This interface allows modification of the license data stored at Manage2. The WHMCS data can be managed at the linked service.

On this tab you will see ''License ID'', ''Package/Group'', ''IP/Hostname'', ''Assigned Service'', and ''Status'' columns displayed for each license associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated license.

*'''Assign License''' - Assign the license to an existing service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.
*'''Change IP''' - Change the license's IP Address.
*'''Change group''' - Change the license's Group.
*'''Change package''' - Change the license's Package.
*'''Expire''' - Expire the license within Manage2.
*'''View License Details''' - Review a detailed output of license information.

====Groups====
[[File:CPLic_Manage2DataGroups.png|thumb|Groups Tab]]

Groups are arbitrary categories. They are unique to your Company. They can help keep your licenses organised by modeling how you sell and manage the product-customer lifecycle.

On this tab you will see the ''Group ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each group associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated group.

*'''Change name''' - Change the group's name within Manage2.
*'''Change tax status''' - Change the group's tax status within Manage2.
*'''Show Licenses''' - Display a filtered list of licenses associated with the specific group.

====Packages====
[[File:CPLic_Manage2DataPackages.png|thumb|Packages Tab]]

Packages are SKUs. They represent the product, features, or bundled options that are granted to the license holder.

On this tab you will see the ''Package ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each package associated with your Manage2 account.

The ''Actions'' column offers the ability to perform the following actions against the associated package.

*'''Show Licenses''' - Display a filtered list of licenses associated with the specific package.

===Service Management===
[[File:CPLic_ServiceManagement.png|thumb|cPanel Licensing Service Panel]]

Services associated with a cPanel Licensing related Option Group will see a panel labeled ''cPanel Licensing'' when viewing that service via the Admin Area.

When a service is associated with a cPanel license, an overview if the license details is displayed along with the following buttons:

*'''Sync IP''' - Change the license's IP Address to the value displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Sync Package''' - Change the license's Package to the value displayed in the cPanel Licensing configurable option.
*'''View Details''' - Display a modal containing the cPanel License Information.
*'''Expire''' - Expire the license within Manage2.

The following buttons will be displayed within the panel at all times:

*'''Provision New cPanel License''' - Automatically provision a new license from Manage2 using the package displayed in the cPanel Licensing configurable option and the IP address displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Link to Existing License''' - Display a modal that allows for the search of existing licenses to be assigned to the service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.

===Handling Manual License Cancellations===
Expiring a license, either by clicking '''Expire''' in the '''[[Clients:Products/Services_Tab|Products/Services]]''' tab of the client profile or in Manage2, does not automatically update the '''Recurring Amount''' for the parent service. The system cannot determine whether to bill a license using the license's state.

To cancel a license and ensure that the system updates the '''Recurring Amount''' value correctly:
# Click '''Expire''' in the '''Service Management''' section.
# Set the parent service's [[WHMCS cPanel Licensing Module#Configurable Option Settings|configurable option]] to ''None''.
# Set '''Recalculate on Save''' to ''ON''.
# Click '''Save Changes'''.

The system will update the parent service's '''Recurring Amount''' to no longer include the cost of the expired license.

===Assign License & Link to Existing License===
[[File:CPLic_AssignLicense.png|thumb|Assign License Modal]]
[[File:CPLic_LinkExistingLicense.png|thumb|Link to Existing License Modal]]

Both the Licenses tab, seen on the cPanel Licensing module page, and the cPanel Licensing panel, seen on the Service page, offer the ability to manually assign a service to a license and vice versa.

The '''Assign License''' modal provides a searchable drop-down menu that can be used to locate and select the desired service. Once the service has been selected, clicking on the ''Assign'' button will assign the service to that specific license.

The '''Link to Existing License''' modal provides a searchable drop-down menu that can be used to locate and select the desired license. Once the license has been selected, clicking on the ''Assign'' button will assign the license to that specific service.

In both cases, it is important to note that the configurable option will not be automatically selected. You must navigate to the Service page in the Admin Area, set the configurable option to coincide with the appropriate package if fixed, or enable the autoscale option if applicable. '''This is necessary for automated billing to occur.'''

Additionally, only a singular active license can be assigned to a service. Using the ''Link to Existing License'' or ''Assign License'' functionality to assign a new license to a service already in possession of an active license will result in the replacement of that active license. In this instance, a prompt will appear to confirm this action.

== Upgrading ==

If you have an earlier version of the cPanel Licensing Module installed, follow the steps below:

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the 'cpanellicensing' directory to the '/modules/addons' folder of your WHMCS installation.

====Troubleshooting====
This section covers the error messages which may be encountered during license assignment.

=====A license was deactivated on the same IP last month before billing could occur=====
This response indicates that the previous cPanel license associated with the service's IP address accrued usage, and was deactivated before billing could occur within Manage2.

A reactivation fee must be paid before a new license can be provisioned for that IP address. This must be done via Manage2 directly.

=====This license is already assigned to another service=====
Review the '''Addons > cPanel Licensing''' page to see the current service to which the license is assigned in WHMCS.

Click the ''Assign'' button a second time to remove the current assignment and assign to the current service.

=====You cannot assign a license to this service=====
'''You cannot assign a license to this service as the product to which it is assigned does not have a configurable option for a cPanel license'''

There is no license pricing configuration assigned to the product in use, a license can only be assigned when a pricing scheme is associated with the product. The following steps will make the necessary adjustments to the product/service configuration:

# Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Check whether the cPanel Licenses configurable option appears. If it does not:
## 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'''.
## Click '''Edit''' for the cPanel licensing option group.
## Press Ctrl + Click to select all the applicable products that will offer a cPanel license option. Make certain to select the product that is currently exhibiting the error.
## Click '''Save Changes'''.
# If the cPanel License configurable option is displayed, select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

=====cPanel Licensing options of product are not set for this service=====

'''cPanel Licensing options of product are not set for this service. Review and save the cPanel licensing options for this service and try again'''

A license pricing configuration is assigned to the product in use, but the desired option has not been selected for the individual service record. WHMCS needs to know the desired license tier to invoice the client correctly.

The following steps will make the necessary adjustments to the service record:

# Go to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Use the cPanel License configurable option to select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

== Change Log ==

''N/A''

Tax Configuration

2023-12-22T14:18:48Z

JoshQ: /* Auto Tax Exempt */

<div class="docs-alert-info"><i class="fa fa-question-circle"></i>For this feature in WHMCS 7.6 and earlier, [https://docs.whmcs.com/index.php?title=Tax/VAT&redirect=no click here].</div>

WHMCS can gather necessary taxes when you make sales.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Tax Configuration''' or, prior to WHMCS 8.0, '''Setup > Payments > Tax Configuration'''.

==Enabling Tax Support==

In order to charge tax:

# Enable '''Tax Support'''.
# Click '''Save Changes'''.
# Set the desired settings below.
# Click '''Save Changes''' again.

==General Tax Settings==

===Tax/VAT ID Number===
Enter your company Tax/VAT ID in this field. Invoices will display this under the company address in the client area and on PDF printable invoices.

===Inclusive/Exclusive Tax===

By default, tax is exclusive. You need to add tax onto the prices you enter in WHMCS at the rate you entered. The alternative is inclusive tax, in which the prices you enter in WHMCS already include tax. For inclusive tax, WHMCS needs to work backwards to calculate the amount of tax to charge based on the rates you've set.

*'''Exclusive Tax''' > Tax Amount = Item Price x ( Tax Rate / 100 )
*'''Inclusive Tax''' > Tax Amount = ( Item Price / ( 100 + Tax Rate ) ) x Tax Rate

==Custom Invoice Numbering==

<div class="docs-alert-info">Custom Invoice Number is part of the EU VAT Addon.</div>

To enable Custom Invoice Numbering, toggle the appropriate switch on '''Tax Configuration''' and click '''Save Changes'''. After you enable it, the configured custom invoice numbering will apply to invoices that you generate from then on.

===Custom Invoice Numbering Format===

This is the format of the custom invoice number to apply to the invoices WHMCS generates. The default value of this is <tt>{NUMBER}</tt>, which will contain only the value from '''Next Invoice Number'''.
The field can contain any text in the invoice number that the client will see. You can add more tags to the field, which the system will replace when it generates the invoice.

Available tags are:
* <tt>{NUMBER}</tt> — The value for '''Next Invoice Number'''.
* <tt>{YEAR}</tt> — The four-digit year value for the current date.
* <tt>{MONTH}</tt> — The two-digit month value for the current date.
* <tt>{DAY}</tt> — The two-digit day value for the current date.

===Next Invoice Number===

The number that the system will assign to the next invoice it generates.

<div class="docs-alert-info">Only fill in this field if you want to change the number of the next invoice. Only increase this number; do not decrease it.</div>

===Auto Reset Numbering===
This allows you to automatically reset the invoice number periodically. The automatic invoice numbering reset occurs when the automation cron runs on the last day of the month or year. If you want to use this feature, we recommend that you configure the cron job to run late at night in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

==VAT Settings==

===VAT Mode===

Toggle '''VAT Mode''' to ''ON''. This will automatically display a window allowing you to set your VAT label display name. Enter one and then click '''Create Rules'''.

====Auto Configure VAT Tax Rules====

If you accidentally delete a rule or need to recreate or change the name of a rule, click here. Follow the prompts, using the appropriate VAT Rate for each EU country.

===Custom Field Migration===

If a WHMCS installation previously used the EU VAT Addon and a custom field to contain the client VAT Number, this option will display to perform a migration of the tax numbers from the custom field to store them in the client table.

===VAT Number Validation===

Toggle this to ''ON'' to enable validation of VAT numbers during registration and checkout. WHMCS uses VIES to validate EU VAT numbers and HMRC to validate UK VAT numbers.

===Auto Tax Exempt===

Check this to set clients as tax exempt when their VAT number successfully validates.

When you save a client's profile, WHMCS will revalidate their VAT number with the relevant authority (VIES for EU VAT numbers and HMRC for UK VAT numbers). If the VAT number is invalid, the client will lose their tax exempt status, and the system will apply tax to all newly-generated invoices accordingly.

===Your Home Country===

Select the country for your main business location.

===Home Country Exclusion===

Check this to always charge VAT if the customer's billing address is in the country you selected above.

===Proforma Invoicing/Sequential Paid Invoice Numbering===

Toggle this to ''ON'' to enable the invoice numbering format you set below.

===Sequential Invoice Number Format===

Enter a format for invoice numbering. You can include these tags, which will be replaced with the corresponding information when the invoice is generated:

* <tt>{YEAR}</tt> — The current year.
* <tt>{MONTH}</tt> — The current month.
* <tt>{DAY}</tt> — The current day.
* <tt>{NUMBER}</tt> — The sequential invoice number.

===Next Paid Invoice Number===

Enter a number to use to number the next invoice that WHMCS generates.

===Auto Reset Numbering===

Select the frequency with which WHMCS should automatically reset invoice numbering. Select ''Never'' if you do not want to automatically reset numbering.

===Set Invoice Date on Payment===

Check this to set the invoice date to the current date when payment is applied.

==Tax Rules==

You must configure tax rules in order to automatically charge tax in the cart. You can view and add tax rules in the '''Tax Rules''' tab.

===Adding a Rule===

To add a rule:

* For '''Name''', enter a name for the tax zone, which allows you to identify it.
* For '''Country''', choose whether this tax rate applies to all countries or only applies to a selected country.
* For the state, choose whether it applies to all states in the selected country or only a selected state.
* Finally, enter the tax rate as a percentage (for example, <tt>17.5</tt>).
* Click '''Add Rule'''. The system will create the tax rule and automatically add it to the appropriate table for Level 1 or Level 2 rules.

For example, a UK business would set up the system to charge VAT. In the country field, you would choose '''United Kingdom''' and for the state you would choose '''Apply Rule to All States'''. You would then enter the tax rate of '''20.0''' and click '''Add Rule'''. You can set up an unlimited number of tax rules.

===Changing Tax Rates===

Sales tax rates generally change over time. To change a tax rate in WHMCS, delete the existing rule and then create a new rule using the new rate and exactly the same name, country, and state.

For more information, see [https://help.whmcs.com/m/payments/l/1271960-changing-tax-rates Changing Tax Rates].

===Supported Values===

WHMCS 8.0 and later supports tax rates with up to three decimal places and currency values up to 99 trillion.

[[File:TaxDecimals.png|500px|thumb|center|Tax Rates]]

Prior to WHMCS 8.0, WHMCS only supported tax rates with up to two decimal places.

==Advanced Rules==

===Setting Taxed Items===

The flexible tax system in WHMCS allows you to set, individually, which items apply for tax. WHMCS sets products as untaxed by default. Even if you have tax rules set up, the system won't charge tax for it. This allows you to, for example, charge tax on the products you offer but not on services.

====Setting a Product/Service as Taxable====

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'''.
#Click the edit icon next to the product you wish to set to be taxable.
#Check the checkbox next to the item labelled '''Tax Product'''.
#Save your changes to the product.

====Setting Domains as Taxable====

You can set whether to apply taxes to domains.

====Setting Billable Items as Taxable====

You can set whether to apply tax to billable items.

====Setting Late Fees as Taxable====

You can set whether to apply tax to late fees on invoices.

====Setting Custom Invoices as Taxable====

You can set whether to apply tax to custom (manually created) invoices.

===Compound Tax===

The system calculates compound tax after and on top of a primary tax. If you need to add the Level 2 tax to the Level 1 tax, toggle this option on the advanced tab.

===Deduct Tax Amount===

If the '''Tax Type''' is ''Inclusive'' and the client's country and state or province selections result in them not meeting any of the configured tax rules, deduct an amount from the order. Base this on the total amount for taxable items on the order and the percentage of tax that would apply to the default country 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'''. It will deduct the percentage that applies to the first applicable Level 1 and Level 2 tax rules.

===Tax Calculation Mode===

The '''Calculation Mode''' setting determines how the system calculates taxes.

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

There are two possible values for this setting:

* '''Calculate individually per line item''' — Selecting this option will calculate taxes on a per line item basis. When you select this, the system will calculate tax for each line item, rounded to 2 decimal places. It will also calculate the total tax using the sum of the tax calculation for each individual line item.
* '''Calculate based on collective sum of the taxable line items''' — Selecting this option will calculate taxes using the sum of the taxable line items on an invoice. When you select this, the system totals the individual taxable line items and calculates tax based on the sum total of those taxable line items.

====Tax Amount Differences====
Due to rounding for tax calculation modes and the calculation amounts, the resulting tax amounts may differ.

=====Calculate Individually per Line Item=====

Example tax calculation for 11 line items at $2.21 each:

<div class="docs-related-pages">
(2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) = 4.84
</div>

=====Calculate Based on the Collective Sum of the Taxable Line Items=====

Example tax calculation for 11 line items at $2.21 each:

<div class="docs-related-pages">
(24.31 x 20%) = 4.86
</div>

System Logs

2023-12-11T18:30:20Z

JoshQ: /* Module Log */

WHMCS logs all activity, admin logins, gateway communications, sent and received email communications, and domain lookups. This allows you to monitor and track all the activity taking place inside your WHMCS system.

You can view the system logs at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Logs''' or, prior to WHMCS 8.0, '''Utilities > Activity Log'''.

<div class="docs-alert-success">
You can view logs for payment gateway transactions at '''Billing > [[Gateway Log]]'''.
</div>

<div class="docs-alert-danger">
If you enable error logging, those errors will display here. However, we strongly recommend that you disable error logging unless you are actively troubleshooting an issue. You can configure error logging 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'''.
</div>

== Activity Log ==

This records both system events and the actions and events for a single client from throughout WHMCS.

== Admin Log ==

This records login sessions for admins, including login and logout times, IP addresses, and usernames.

== Module Log ==

This records activity between WHMCS and third-party APIs or other module systems.

For more information, see [[Troubleshooting Module Problems]].

== Email Message Log ==

This records all of the emails that WHMCS sends to clients except for '''Automated Password Reset''', '''Client Email Address Verification''', and '''Password Reset Validation''' emails.

You can disable logging of support ticket responses to this log in the '''[[Support_Tab|Support]]''' 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'''.

== Ticket Mail Import Log ==

This records all of the support ticket emails that WHMCS added to the support ticket system via email piping or email importing.

* For more information about error messages in this log and how to address them, see [[Email Piping]] and [[Email Importing]].
* For more information about blocked, insecure, or failed ticket reply importing, see [[Blocked Support Email Replies]].

=== View Log ===

Click '''View Log''' for a log entry to view the imported reply. This displays the same information that you see when you view the associated support ticket.

== WHOIS Lookup Log ==

This logs the domains that clients search for from within the Client Area.

== Log Accumulation ==

Over time, log records in your WHMCS system will accumulate. As the number of records increases, your database will become larger and you may notice a reduction in performance. WHMCS allows you to empty logs from within the Admin Area.

* To empty your logs, go to '''Utilities > [[System Cleanup]]'''.
* To configure the maximum number of system-related entries stored in the system logs, 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'''.

GoCardless

2023-11-16T15:26:30Z

JoshQ: Fix typos

== 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.
{{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.

Once a mandate has been created, WHMCS can use it for processing renewal payments for any other services associated with the client as long as they are set to the GoCardless gateway as well.

When making a manual payment, customers are able to select to use a previously stored bank account or enter a new one.

Customers never leave your WHMCS installation during checkout or adding/removing a new bank account. Personal bank information is submitted directly to GoCardless and is never stored 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]].

{{modules}}