Troubleshooting

Common issues and how to resolve them. If you can't find your problem here, check the Reading the logs section to gather context, then open a ticket in our client area and we'll help you out.

Installation and licensing

"Requires ionCube Loader 13 or newer"

Billing Booster's PHP files are encoded with ionCube. If you see ionCube-related errors during install, check:

• Run php -v from the command line. The output should mention "with the ionCube PHP Loader v13" (or newer).
• If it doesn't, install or update ionCube Loader on your server (see your hosting provider's documentation).
• Restart your web server / PHP-FPM after installing.

The features are locked or the Statements/Transactions tabs are missing

Payment codes, e-invoicing, and statement processing are licensed individually, so each part of the interface follows its own entitlement. If something is locked or missing:

• Open Settings → General and confirm your license key is entered and shows status Active.
• Check the Overview tab — the Included features checklist shows which features your license unlocks. A feature your license doesn't include stays locked even when the license is active, and that is expected, not a fault.
• Just bought or renewed something? Click Force refresh next to the license key to re-check with the license server instead of waiting for the cached result to expire.
• Statements needs two things, not one: the Statement Processing feature and an enabled statement configuration. With the feature licensed but nothing configured, Transactions appears and Statements doesn't.

If the Overview tab reports an Active license that includes no features at all, an add-on entitlement has most likely lapsed — Force refresh first, then open a ticket if it stays empty.

See Licensing and what you can see for the full table of what appears when.

"Class not found" or autoload errors after upgrade

Stale opcache or a partial file copy. Fix by:

1. Make sure the file upload finished cleanly — check that /modules/addons/billboost/lib/ and /modules/addons/billboost/vendor/ are fully populated.
2. Clear your PHP opcache (restart PHP-FPM, or service php-fpm restart).
3. Reload the WHMCS admin page.

"This version of Billing Booster requires at least WHMCS version 8.11.0"

Activation checks your WHMCS version and refuses on anything older, rather than leaving you with a half-installed module. Upgrade WHMCS first — see Requirements.

The version didn't change after replacing the files

WHMCS runs a module's upgrade routine when an admin next opens Setup → Addon Modules and notices the version has moved. Open that page once. If the version still doesn't change, the file upload didn't fully replace /modules/addons/billboost.

Data storage shows "Not Writable" / file permission errors

The Data Storage directory must be writable by the user that runs PHP. The Settings tab shows a live status chip next to the path. If it reads Not Writable, Not Readable, or Not Executable, fix the directory's ownership and permissions so the PHP user can write to it.

Payment codes

A payment code isn't appearing anywhere

Before hunting through conditions, check the two wiring steps WHMCS needs:

• Is the PDF routed through Billing Booster? Either your BestPDF design carries a Payment Code component, or your active template under Setup → General Settings → General is one of the billboost-* child themes. With a stock template and no BestPDF, no code is ever drawn into the PDF, however well the configuration is set up. This is the most common cause by a distance.
• Does the email template contain {$paycode}? WHMCS builds invoice emails from your own templates, so the tag has to be there. See Installation → Add the email tag.

The client-area invoice page needs neither: if the code is missing there but present elsewhere, check whether the client has the Payment Code gateway selected — the page suppresses the injected code in that case because the gateway renders its own.

If the code appears in one place but not another, the wiring is fine and it's a condition — read on.

A payment code isn't appearing on a particular invoice

This is almost always a condition that excludes the invoice. To find out which:

1. Turn on diagnostic logging under Settings → Logging.
2. Regenerate the invoice (or trigger the email).
3. Open the Logs tab — the log explains, per invoice, which condition matched or excluded the code.

Things to check:

• Is the configuration Enabled?
• Do the invoice's currency and the client's country fall within the code's Conditions?
• Is there a payment gateway filter that excludes this invoice's gateway?
• For emails specifically: does that email template carry the {$paycode} tag? Billing Booster fills it in for seven templates only — Invoice Created, Invoice Payment Reminder, the three overdue notices, Invoice Modified, and Invoice Payment Confirmation.
• Also for emails: does the code have a No email on… toggle set on its Notifications tab? Those cancel the email outright, so nothing arrives at all.
• If another exclusive code matched first, it suppresses lower-priority codes — check the Order on the list.

"Invalid IBAN format" / "Invalid BIC format"

The editor validates the IBAN and BIC you enter on the Account Details tab. Re-check them — IBANs must be the full international format, and BICs are 8 or 11 characters.

The Swiss QR slip looks wrong or is missing

• Confirm you entered a valid CHF IBAN (or QR-IBAN) and complete Company Details (creditor address).
• Check Show separation lines on the Layout tab — if it's set to Never, In emails only, or Always except admin area, the slip won't render where you're looking. Admin-generated previews are the usual surprise.
• Not on the page you expected? Check Slip placement on the same tab. Under BestPDF the control is greyed out and placement comes from the design instead.

Every page has a large empty band at the bottom

Slip placement is set to First page. Reserving room for the slip uses TCPDF's page-break margin, which is global, so the gap appears on every page of a multi-page invoice — and the slip itself ends up mid-document.

Switch Slip placement to Last page (or Separate page after the invoice) on the payment code's Layout tab. See Slip placement.

E-invoicing

Factur-X / ZUGFeRD XML isn't in the PDF

ZUGFeRD and Factur-X embed the XML inside the PDF, which is done by BestPDF. Make sure BestPDF is installed and detected (Integrations tab) and that the E-Invoicing component is present in your active design. Without BestPDF, only standalone UBL/Peppol XML can be produced.

The XML fails validation

Schema validation almost always fails on missing company or tax identity fields. Re-check the Company Details and Tax Information tabs, then validate a fresh sample. The Logs tab records generation errors.

Untaxed lines come out as zero-rated instead of reverse charge

Reverse charge (AE) needs both VAT identifiers, and an exemption (E) needs a reason. When either is missing, Billing Booster falls back to zero-rated (Z) deliberately, so the document stays valid rather than asserting something it can't support. Check that:

• your own VAT Number is filled in on the Tax Information tab, and
• the client has a VAT number on their WHMCS record (for AE), or an Exemption reason is set (for E).

See VAT treatment of untaxed lines.

The e-invoice isn't attached to the invoice email

Check Attach e-invoices to invoice emails on the E-Invoicing tab — with it off, the XML is still generated, archived, embedded in the PDF and downloadable from the client area, but not attached. See E-Invoicing → Attaching e-invoices to emails.

Note that with the switch on, the invoice email is sent by Billing Booster rather than by WHMCS — that is how the attachment gets there, since a WHMCS hook cannot add one to a message in flight. If your customers report a change in how invoice emails arrive, this is why.

The e-Invoice button is missing from the client-area invoice page

The button only appears on invoices that actually have an e-invoice — one where e-invoicing is licensed and an e-invoicing configuration's conditions matched. Check the Logs tab for that invoice. The download itself is served by the module, so it also requires the addon to be active.

Statement processing

Can't download from the bank

• Confirm the configuration has a bank connection. Without one, Download from Bank isn't available and statements have to be uploaded.

For an MFTPF connection:

• Confirm the SFTP Username and SFTP Private Key Path are correct.
• Make sure the private key file exists at that path and is readable by the PHP user.
• Confirm the server can reach PostFinance MFTPF over SFTP (no firewall blocking the outbound connection).

For an EBICS connection:

• Confirm the bank setup is Active. Until it is, the Statements tab says the setup is not finished, and downloads are refused.
• Confirm the Bank Country is your bank's, so the right files are requested. If the bank answers that the order type or parameters are not supported, ask it for its BTF parameters and enter them under Show download parameters.
• Confirm the server can reach the EBICS URL over HTTPS, and that its CA certificates are up to date: the bank's certificate is always verified.
• "The bank will send them again" means the files arrived but could not be saved to the archive — check that the Data Storage path is writable. The bank keeps the files until they can be saved.

For a Revolut Business or Enable Banking connection:

• Confirm the bank setup reads Authorised and an Account is chosen. If the Statements tab says the bank no longer accepts the authorisation, it has expired: open the configuration, Edit the bank connection, and click Authorise Again.
• A payment the bank still reports as pending isn't downloaded yet; it comes in with the next download after it is booked.

The EBICS setup doesn't get past a step

• Sending the keys fails: check the EBICS URL, Host ID, Partner ID and User ID against your bank's contract letter. If only the second half failed, Retry Sending Keys resends the same keys.
• "EBICS needs these PHP extensions on the server": install the extensions it names (see Requirements).
• Check Bank Activation keeps failing: the bank has not activated your access yet — it needs the signed initialisation letter first. The message shows the bank's own reason.
• The hash values don't match: don't activate. Contact your bank, then use Start over with new keys once it has reset your EBICS access.

A Revolut or Enable Banking setup doesn't finish

• Nothing happens after authorising: the setup listens for the window it opened. Allow pop-ups for your admin area, and finish the authorisation in that window rather than in another tab.
• The authorisation window ends on a 403 or an error page: the bank sends your browser back to modules/addons/billboost/oauth/callback.php, and your web server has to let it through. Billing Booster's oauth/.htaccess does that on Apache; on nginx, or behind a web application firewall, allow the path yourself.
• Enable Banking offers no banks, or the wrong ones: check the Application ID, the Bank Country and the Account Type — a bank serving only personal accounts isn't listed for a business account, and the other way round. Your accounts must also be linked to the application in the Enable Banking control panel.
• The bank refuses the authorisation: the refusal is written to the Logs tab with everything the bank said.

An uploaded file is refused

Each configuration takes files in its own format. "… is a camt.053 file; upload it on the tab of a camt.053 configuration" means the file belongs on another configuration's subtab — add a configuration of that format if there is none. "… which statement processing does not read" means another ISO 20022 message, such as a camt.052 intraday report — ask your bank for camt.053 or camt.054 instead. "… is not a camt.054 file" means the file is not a camt statement at all.

On a CSV configuration, a file that lacks one of the mapped columns is refused with the column's name — the bank has changed its export, or the file is from another account. Open the configuration and map the columns again from a current export (see CSV Columns).

Some payments are missing from the preview

The preview lists incoming payments only; outgoing payments in a camt.053 are skipped. If the import warns about bookings without payment details, your bank booked several payments as one line without listing them. Those can't be matched: ask your bank to include the details, or use camt.054 (see camt.054 or camt.053?).

Payments aren't matching invoices

Matching relies on the structured reference carried by the payment. If transactions come back unmatched:

• Confirm the originating payment code's reference format produces a reference your matching can read (e.g. client number + invoice number).
• For SEPA payments, turn on Use an RF creditor reference on the EPC payment code, so the payment carries a reference instead of free text.
• For payments without a reference, set Match by invoice number in the payment note to Review or Automatic. Such a match needs exactly one unpaid invoice that the amount pays in full — a partial payment, or a note naming several invoices, stays unmatched on purpose (see How payments are matched).
• For CHF, turn on Accept 5-cent rounded CHF payments under Shared settings, so a 5-cent rounding difference doesn't block the match.
• Check the Logs tab for the specific reason a transaction was skipped.

A payment can't be selected in the preview

A row without a checkbox is a payment that can't be applied: its invoice wasn't found, or the payment is already recorded (Exists). A payment on an invoice that is already Paid can be applied, but is never preselected — tick it only if you mean to book it; see A payment on an invoice that is already paid.

Payments are waiting for review on the Overview

That is automatic processing handing you what it could not settle by itself — an invoice already paid, a match from the payment note, an overpayment, a failure. Open Details to see the payment and the invoice, then Apply or Dismiss it. See Payments to review.

"Paycode gateway not found" when applying payments

Applied payments are booked against the Payment Code gateway, so it has to exist. Go to Setup → Payments → Payment Gateways, open All Payment Gateways, and activate Payment Code. See Installation.

The Transactions tab is empty even though payments were applied

The tab lists WHMCS transactions booked against the Payment Code gateway. If the gateway was installed after the fact, or the payments were recorded by hand against a different gateway, they won't be listed there — check the client's payment history in WHMCS instead.

Automatic processing isn't running

Automatic processing needs a ready bank connection on the configuration — for EBICS, a setup that is Active; for Revolut Business and Enable Banking, an authorisation that hasn't expired — and Enable automatic sync switched on. Without both, neither cron picks it up.

Then work out which cron is supposed to be driving the sync, because the shared setting Sync in the WHMCS daily cron decides that and the two have different failure modes. See Automatic processing.

If the setting is on (the WHMCS daily cron drives it):

• Make sure the WHMCS system cron is configured and running on the server. There is no separate task to enable: Billing Booster runs off the WHMCS cron directly.
• Remember the run happens once a day, at the time set under Setup → Automation Settings, not every time cron.php fires.
• crons/billboost.php refuses to run in this state, and logs that it did. Remove its cron entry, or turn the setting off.

If the setting is off, nothing runs automatically until you schedule crons/billboost.php yourself. Either turn the setting on, or add the system cron entry shown in On your own schedule. Running the script by hand is the quickest way to see what it says:

php -q /home/example/public_html/crons/billboost.php

In both cases:

• Confirm Statement Processing is included in your license; the run stops early without it.
• Check the Logs tab. Every run announces itself and every early exit names its reason, so the log tells you which of the two crons ran and what stopped it.

Reading the logs

The Logs tab inside the Billing Booster interface shows the module's activity log — the first place to look when something doesn't behave as expected.

Controls

• Filter by level — Debug, Info, Warning, Error.
• Search — substring match against the log message and date.
• Sort — by date or level, ascending or descending. Defaults to most recent first.
• Refresh — re-fetch the latest entries.

What's logged

• INFO — routine operations: code generated, e-invoice produced, statement processed, payment applied.
• WARNING — recoverable issues: an invoice was skipped by a condition, a transaction couldn't be matched.
• ERROR — unrecoverable issues: invalid bank details, e-invoice generation failure, SFTP or EBICS download failure, file write permission denied.
• DEBUG — verbose tracing, written when diagnostic logging is enabled. This is what to turn on when a payment code isn't appearing.

When to attach logs to a support ticket

If you're opening a ticket in our client area, turn on diagnostic logging, reproduce the issue, then filter the log to the relevant time window at DEBUG level and copy the matching entries into the ticket. This gives us enough context to diagnose without repeated round-trips.

Frequently asked questions

Will my configurations survive an upgrade?

Yes. Payment code, e-invoicing, and processing configurations live in the WHMCS database. Replacing the module files preserves them, as do your template routing, email tags, and gateway settings.

Deactivating the addon keeps them too, unless Remove all data when the addon is deactivated is switched on under Settings → Advanced — then deactivating drops Billing Booster's tables outright. See Uninstall.

Can I switch off the payment code for one type of email?

Yes — each payment code has a Notifications tab with a toggle per email type. Note that these cancel the whole email rather than just hiding the code; see Payment codes → Notifications.

Can I have different payment codes for different countries or currencies?

Yes — that's exactly what Conditions are for. Create one configuration per account/standard and scope each with currency, country, and gateway conditions. Use Exclusive and Order when several could match the same invoice.

Do I need BestPDF?

No — Billing Booster works standalone. Without BestPDF, switch to the billboost-* child theme of your template, which wraps its invoicepdf.tpl and places the code for you at a fixed position. BestPDF replaces that with pixel-precise placement, and is required for embedding ZUGFeRD / Factur-X XML into the PDF. Pick one route or the other — a billboost-* theme and a BestPDF Payment Code component would draw the code twice. See Integrations.

Can statement processing work with banks other than PostFinance?

Yes. Statement processing reads camt.054 and camt.053 files, which practically any bank can export, and any bank's CSV export once its columns are mapped: upload them on the Statements tab to match and apply payments. For automatic download, the EBICS connection works with practically every bank in Switzerland, Germany and Austria, Enable Banking with most European banks, and Revolut Business has a connection of its own; PostFinance can also be reached through MFTPF.

Uninstalling

If you want to remove Billing Booster from your installation entirely, see the dedicated Uninstall page.