Sema Online Return for VirtueMart

Joomla extension (package = plugin + component) providing a mandatory “Withdraw from contract” button as required by EU Directive 2023/2673 (effective June 19, 2026).

Two variants are available:

2. Installation

Obtaining the Installation Package

Download the correct ZIP file:

• J4/5: pkg_semavmwithdrawal.zip (or semavmwithdrawal_vX.Y.Z.zip)
• J3: pkg_semavmwithdrawal.zip from the J3 build (or semavmwithdrawal_vX.Y.Z_j3.zip)

Installation Steps

1. Log in to the Joomla administration panel.
2. Navigate to System > Install > Extensions (J4/5) or Extensions > Manage > Install (J3).
3. Upload the pkg_semavmwithdrawal.zip file.
4. Joomla installs both parts at once:
   • Plugin: plg_system_semavmwithdrawal (System – SemaVirtueMart Contract Withdrawal)
   • Component: com_semavmwithdrawal (Contract Withdrawals – admin overview)

Upgrade: Same procedure as installation. Joomla uses method="upgrade" and runs migration SQL automatically. Data in the #__sema_withdrawals table is preserved.

4. Basic Configuration

Open the plugin settings:

• J4/5: System > Plugins > click the plugin name
• J3: Extensions > Plugins > click the plugin name

Required / Recommended Parameters

Additional Parameters

Multilingual Support (since v1.7.0)

The plugin automatically displays the modal, emails, and error messages in the visitor's language. Supported languages: Czech (cs-CZ), English (en-GB), German (de-DE), Slovak (sk-SK). If the visitor's language is not available, English is used as a fallback.

Button text: When the “Button text” parameter is empty (default), the text is taken from the language file – automatically in the visitor's language. If a custom text is entered, it is used for all languages.

Terms URL: For multilingual sites, you can specify different URLs for each language. Format in the text area (one line = one language):

cs-CZ=https://example.cz/podminky
en-GB=https://example.cz/en/terms
de-DE=https://example.cz/de/agb
sk-SK=https://example.cz/sk/podmienky

A single URL without a language prefix still works (backward compatible). If the visitor's language is not in the list, the first URL is used as a fallback.

6. Button – Placement and Appearance

Button Position

Button Color

The “Button & control color” parameter (color picker, default #1f6feb) determines:

• the floating button color
• the color of modal UI controls (confirm button, checkboxes, active states)
• hover state darkens automatically

The color is applied via the CSS custom property --vmw-accent.

8. Withdrawal Period

• Period length: Default 14 days (parameter period_days).
• Period handling: Determines what happens when an order is older than the configured period.
  • Do not check: No verification; the form is always submitted without warning.
  • Warn but allow: Shows the customer a warning “OUTSIDE estimated period” but does not block submission.

Important: The plugin NEVER blocks a withdrawal. The period legally runs from the date of goods receipt (not the order date), which the plugin cannot verify precisely. Therefore it only warns – the final decision is up to the shop.

10. CSV Export

1. In the withdrawal records admin view, click the “Export CSV” button in the toolbar.
2. A CSV file is downloaded with all records (respects the current search filter).
3. Encoding: UTF-8, delimiter: semicolon (;).

CSV export requires core.manage permission on the component.

12. Emails

The plugin sends two types of email. Since version 1.7.0, emails are sent in the visitor's language (including the subject, body text, and footer).

Customer Confirmation (HTML)

• Recipient: Customer email (from the VM order).
• Subject: “Confirmation of contract withdrawal – order [number]”
• Content:
  • Header with company logo (if configured)
  • Confirmation of withdrawal receipt
  • Order number, order date, date received
  • Period information (within period / outside estimate)
  • Chosen resolution (if selected)
  • List of selected items and total amount (if items were chosen)
  • Statutory withdrawal declaration text
  • Return address for goods
  • Link to terms & conditions (if configured)
  • Footer with company details (ID, address, phone, email)

This email serves as a durable medium under the directive – it is legal proof that the withdrawal was received.

Shop Notification (Plain Text)

• Recipient: Email from the “Notification e-mail” parameter (or system sender).
• Subject: “New contract withdrawal – order [number]”
• Content: Brief overview – order number, customer, email, resolution, items, date.

Email Footer Contact Fallback

The email in the footer is determined by cascading fallback:

1. “Contact e-mail” parameter (company_email_contact)
2. If empty: “Notification e-mail” parameter (notify_email)
3. If empty: Joomla system sender (mailfrom)

Currency

Amounts are shown in the order currency as configured in VirtueMart – the symbol, the separators and the position of the symbol all come from the VirtueMart currency table. This applies to the modal and to both e-mails. Since version 1.7.3; before that the currency was hard-coded to Czech koruna, so a shop selling in euro showed the wrong symbol.

14. Uninstallation

Procedure

1. J4/5: System > Manage > Extensions > search for SemaVMwithdrawal > Uninstall.
2. J3: Extensions > Manage > search for SemaVMwithdrawal > Uninstall.

What Gets Deleted

• Plugin plg_system_semavmwithdrawal (PHP, JS, CSS, language files)
• Component com_semavmwithdrawal (admin files)
• Table #__sema_withdrawal_ratelimit (rate limit records)

What Is PRESERVED

• Table #__sema_withdrawals (audit records of withdrawals)
• Table #__sema_withdrawal_items (items linked to withdrawals)

Why is data preserved? Withdrawal records are legal evidence. Automatic deletion on uninstall could cause legal problems. If you truly want to remove the tables, do it manually via phpMyAdmin:

DROP TABLE IF EXISTS `#__sema_withdrawal_items`;
DROP TABLE IF EXISTS `#__sema_withdrawals`;

(replace #__ with your actual table prefix)

16. Troubleshooting

Button Does Not Appear

1. Verify the plugin is enabled (Status = Enabled / green checkmark).
2. Check the “Button position” parameter – is it set to “Do not inject”?
3. Verify no other plugin/module on the page is blocking onAfterRender.
4. Check the browser console (F12) for JavaScript errors.

Error “The request could not be processed”

• After upgrade: Customer must perform a hard refresh (Ctrl+Shift+R) to load the new JS with CSRF token.
• Expired session: Refreshing the page will renew the token.
• Enable Debug mode in plugin settings for more detailed error messages.

Error “Too many attempts”

Rate limiting. The customer must wait a few minutes. If this is legitimate traffic behind a proxy, set the correct trusted proxy IP header.

Email Not Delivered

1. Verify Joomla mail settings: System > Global Configuration > Server > Mail Settings (J4/5) or System > Global Configuration > Server (J3).
2. Check the spam folder.
3. Verify the “Notification e-mail” parameter is correctly filled in.
4. Enable Debug mode – the AJAX response will include information about whether the email was sent.

Order Not Found

• The customer must enter the exact VirtueMart order number and the email associated with the order.
• The plugin searches the #__virtuemart_orders table joined with #__virtuemart_order_userinfos (type BT).

Admin – “Contract Withdrawals” Menu Not Visible

• Verify the component com_semavmwithdrawal is installed.
• Verify user permissions – core.manage on the component is required.

J3 – Czech Texts Appear in English

Known issue with loading Czech in J3 system plugins. Possible solutions:

1. Go to Extensions > Manage > Discover and click Discover (re-detects language files).
2. Manually copy files from plugins/system/semavmwithdrawal/language/cs-CZ/ to administrator/language/cs-CZ/.
3. Clear the Joomla cache.

Launch Checklist

• Plugin installed and enabled
• Shop name filled in
• Notification email filled in
• Company details filled in (logo, ID, address, phone, email)
• Return address filled in
• Terms & conditions URL configured
• Button position selected
• Debug mode DISABLED
• Trusted proxy IP header configured (if site runs behind a proxy)
• Test withdrawal completed and email received
• Terms & conditions updated with information about the withdrawal button on the website

Inside the administration