Skip to main content

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​

"Plugin requires ionCube Loader 13 or newer"​

Pingen Post'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 operational tabs are locked​

The Invoices, Quotes and Mailroom tabs only unlock when a valid license is active; Integrations works without one. If they show a license required panel:

  • Open Settings → General and confirm your license key is entered.
  • Check the Overview tab — it shows the resulting license status. Anything other than Active keeps those tabs locked.

"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 /plugins/pingen/lib/ is fully populated.
  2. Clear your PHP opcache (restart PHP-FPM, or service php-fpm restart).
  3. Reload the Blesta admin page.

Connecting to Pingen​

"Authentication failed" / letters won't submit​

Almost always a credential or environment mismatch:

  • On Settings → Account, confirm the Environment matches the credentials you entered — staging credentials only work against staging, production against production.
  • Re-check the Organisation ID, Client ID, and Client Secret for the selected environment. Regenerate them if unsure (Pingen Account Configuration).
  • Staging and production live on different dashboards — make sure you copied from the right one.

I'm in staging and nothing arrives by post​

That's expected. In Staging, letters are validated and tracked but never physically dispatched and never charged. Switch Environment to Production on Settings → Account once you're ready.

Sending​

A paper-delivery invoice was never mailed​

Work down this list:

  • Is Send Paper-delivery invoices via Pingen enabled on Settings → Delivery?
  • Is the invoice's delivery method actually set to Paper?
  • Is the Pingen Paper Delivery cron task enabled, and is Blesta's system cron running? See Configuration → Scheduled tasks.
  • If the invoice has a zero balance, is Send when balance is zero turned on?
  • Does the invoice match the payment-gateway restriction, if you set one? Skipped invoices stay in the pending-paper queue and the skip is logged.
  • Did the document fail Pingen's validation? Check the Logs.

"Document validation failed" / margins or address rejected​

Pingen enforces minimum margins and a correctly positioned recipient address. If a PDF is rejected:

  • Generate the document with BestPDF, which produces Pingen-ready PDFs (correct margins, no sender address, proper fold marks).
  • For a manually uploaded PDF, adjust the source document to meet Pingen's requirements and try again.

The Swiss QR slip is missing​

  • The QR slip only applies to recipients in Switzerland and Liechtenstein — it's intentionally omitted elsewhere.
  • Confirm Billing Booster is installed and detected on the Integrations tab.

Tracking shows no events​

Detailed tracking depends on the speed and the destination country. Economy mail and unsupported destinations report little or nothing; try Priority to a supported country for full tracking.

Reading the logs​

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

The Logs tab

Controls​

  • Filter by level — Debug, Info, Warning, Error.
  • Search — substring match against the log message.
  • Refresh — re-fetch the latest entries.

What's logged​

  • INFO — routine operations: invoice submitted, letter sent, cron sweep run.
  • WARNING — recoverable issues: an invoice skipped by a condition, a letter that couldn't be tracked.
  • ERROR — unrecoverable issues: authentication failure, document validation rejected, submission failure.
  • DEBUG — verbose tracing for deeper diagnosis.

Entries older than the Log retention (days) setting (Settings → General) are pruned daily by the log-cleanup cron task.

When to attach logs to a support ticket​

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

Frequently asked questions​

Will my configuration survive an upgrade?​

Yes. Credentials, letter defaults, and delivery settings live in the Blesta database. Replacing the plugin files preserves them.

Uninstalling the plugin keeps them too, unless Remove all data when the plugin is uninstalled is switched on under Settings → Advanced. See Uninstall.

Do I need BestPDF?​

Not strictly — but Pingen only posts PDFs that pass its validation, and BestPDF produces Pingen-ready documents automatically. Without it, you must ensure your PDFs meet Pingen's margin and address-position requirements yourself. See Integrations.

Can clients choose to receive paper themselves?​

Yes. Clients pick the Paper delivery method from the client area, and Pingen Post mails those invoices automatically. Pair it with a delivery fee so the postage cost is added when they opt in.

How do I test without spending money?​

Use the Staging environment. Letters are validated and move through the whole flow but are never physically posted or charged.

Uninstalling​

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