Nexi XPay Greece for VirtueMart — Documentation

Overview

Nexi XPay Greece for VirtueMart connects a VirtueMart checkout to the Nexi XPay Greece Hosted Payment Page. Payment details are entered on the Nexi-hosted page, while the plugin creates the payment request, redirects the customer, verifies the authoritative result with Nexi and updates the VirtueMart order.

This documentation applies to version 1.0.0.

The plugin supports the Nexi XPay Greece Hosted Payment Page for:

• card payments;
• card installments based on configurable order-total tiers;
• IRIS, when enabled on the merchant terminal;
• Apple Pay, when enabled by Nexi and available on the customer’s device and browser;
• Google Pay, when enabled by Nexi and available on the customer’s device and browser;
• terminal-default accounting or explicit/manual capture;
• capture and full or partial refunds when Nexi exposes the corresponding action for the verified operation.

The plugin does not decide which alternative payment methods are enabled for a merchant. Availability on the Hosted Payment Page depends on the Nexi contract, terminal configuration, environment, customer device and browser.

Requirements

Before installation, confirm the following:

1. Joomla 4 or Joomla 5 is installed and working.
2. VirtueMart is installed, configured and enabled. Tested with version 4.6.8.
3. PHP 7.4 or later is available.
4. The production shop uses a public HTTPS URL with a valid certificate.
5. The merchant has an active Nexi XPay Greece agreement and the correct API key for the selected TEST or LIVE environment.
6. IRIS, Apple Pay, Google Pay, installments and explicit accounting are enabled in the merchant’s Nexi agreement or terminal where those features are required.
7. The shop’s checkout, terms, privacy and cancellation/refund information meet the merchant agreement and applicable legal requirements.

Installation

1. Back up the Joomla files and database.
2. Sign in to the Joomla administrator area.
3. Open System → Install → Extensions.
4. Upload the versioned installable ZIP supplied by 2o2code. Do not extract the ZIP before uploading it through the Joomla installer.
5. Confirm that Joomla reports a successful installation.
6. Open System → Manage → Plugins.
7. Search for Nexi XPay Greece for VirtueMart.
8. Confirm that the plugin is enabled.
9. Activate the installation-wide software license before attempting a new Nexi payment.
10. Create and configure a VirtueMart payment method as described below.

Installing an update over an existing version preserves the plugin configuration and existing Nexi payment records. Always use Joomla’s installer or update system; do not replace plugin files manually.

License activation and protected updates

License management is installation-wide. The license is configured once in the Joomla plugin settings and is not duplicated inside individual VirtueMart payment methods.

Activate the license

To activate the license:

1. Open System → Manage → Plugins.
2. Open Nexi XPay Greece for VirtueMart.
3. In License and updates, enter the software license key.
4. Select Activate license.
5. Confirm that the status becomes Active.
6. Confirm that Protected updates becomes Connected. A temporary “Token ready; update site pending” status means the license is active but Joomla has not yet completed the update-site connection.

License behavior

• Initial activation on the website is required before new Nexi payments can start.
• If the subscription expires, an already activated installation keeps processing payments. Updates and support end, and the license cannot be used for a new activation.
• If the license is deactivated locally, disconnected from the customer account or authoritatively revoked, new Nexi payments stop on that installation.
• Customer returns, notifications, Nexi verification, reconciliation, capture and refunds for transactions that already exist remain available regardless of the current license state.
• A temporary Freemius, DNS or network problem preserves the last successfully verified local entitlement. A transient outage does not deactivate an already verified installation.
• Protected downloads require a current update entitlement and fail closed when that entitlement cannot be confirmed.

Creating the VirtueMart payment method

1. In the Joomla administrator area, open VirtueMart → Shop → Payment Methods.
2. Select New.
3. Enter the customer-facing payment-method name, for example Card, IRIS, Apple Pay or Google Pay via Nexi.
4. Publish the payment method.
5. Select Nexi XPay Greece for VirtueMart as the payment plugin.
6. Save the payment method once so VirtueMart can load the plugin-specific configuration.
7. Open the configuration tab, complete the settings below and save again.

Use separate VirtueMart payment methods only when the shop genuinely needs different customer-facing names, restrictions, default HPP methods, fees or status mappings. The software license remains global to the Joomla installation.

Nexi API settings

Test mode

• TEST — Nexi sandbox uses only the Nexi XPay Greece sandbox endpoint and the TEST API key.
• LIVE — Production uses the production endpoint and LIVE API key.

Keep TEST mode enabled until the merchant’s acceptance checks are complete. Switching to LIVE is a separate production decision.

TEST API key

Enter the server-side API key for the Nexi sandbox terminal. The field is masked and stored using VirtueMart’s encrypted-field support. Do not place the key in frontend code, screenshots or debug output.

IRIS sandbox testing may require the dedicated public IRIS TEST API key supplied or documented by Nexi rather than the card-terminal sandbox key.

LIVE API key

Enter the production API key only when the shop is ready to use the LIVE environment. Leave this field empty during sandbox testing.

Capture mode

• Terminal default omits an explicit capture instruction and lets the Nexi terminal configuration decide the accounting behavior.
• Explicit (manual capture) requests authorization first for supported card and wallet payments. The merchant must later capture the permitted amount from the VirtueMart order.

IRIS is always sent as implicit capture, even when the payment method is configured for explicit capture.

Use the API key that belongs to the intended terminal accounting configuration. Do not assume that a key issued for an implicit terminal can provide explicit capture actions, or the reverse.

Default HPP payment method

• All methods enabled on the terminal lets Nexi display the methods available for that terminal, contract, device and browser.
• Cards initially opens the card flow.
• IRIS initially opens IRIS.
• Apple Pay initially opens Apple Pay when available.
• Google Pay initially opens Google Pay when available.

This setting selects or preselects a method; it does not enable a method that is absent from the Nexi contract or terminal. When the customer selects more than one installment, the plugin always opens the card flow because installments are card-only.

Notification HTTPS base URL

Leave this field empty on a normal production shop that already uses public HTTPS. The plugin will use the Joomla site URL.

Use an override only when a separate public HTTPS origin is required for a controlled test environment, such as a temporary HTTPS tunnel. Enter only the HTTPS base URL, for example:

https://example-tunnel.example

For a Joomla installation in a subdirectory, the subdirectory may be included:

https://example-tunnel.example/shop

Do not add index.php, callback query parameters, user information, a fragment or an existing query string. The plugin appends the correct callback paths and protected per-order parameters.

Safe debug

Safe debug records only bounded operational information such as action names, HTTP status codes and correlation IDs. It does not log API keys, authorization headers or full payment payloads.

Enable debug only while diagnosing a problem and disable it afterward. Never publish an unreviewed Joomla or VirtueMart log file.

Installments

Installment availability is configured as one amount tier per line:

100=3
300=6
600=12

Each rule means:

minimum order total = maximum number of installments

For the example above:

• totals below 100 offer one payment only;
• totals from 100 up to 299.99 offer up to 3 installments;
• totals from 300 up to 599.99 offer up to 6 installments;
• totals of 600 or more offer up to 12 installments.

The highest matching minimum applies. A colon may be used instead of an equals sign, decimal minima may use a comma or full stop, and lines beginning with # are treated as comments. Invalid lines are ignored.

Important rules

• Keep every installment quantity within the merchant’s Nexi agreement.
• Installments are available only for cards.
• Selecting installments forces the card HPP flow.
• If the payment method explicitly defaults to IRIS, Apple Pay or Google Pay, the checkout offers one payment only.
• When no valid tier matches the order total, no installment plan is sent to Nexi.

VirtueMart status mapping

The plugin maps the state verified through the Nexi API to configurable VirtueMart order statuses.

Use distinct VirtueMart statuses for the six roles. Mapping multiple roles to the same status makes order history less clear and causes the plugin to apply the most protective role when evaluating transitions.

A partial refund does not change the order to Fully refunded. The captured status is retained until the verified refunded total covers the full order amount.

Protection of manual order decisions

The plugin allows only forward, payment-safe transitions between its configured status roles. It does not regress a captured or refunded order to pending or failed.

If a merchant manually moves an order to a custom status outside the six Nexi mappings—for example after receiving a separate bank transfer—the later Nexi synchronization does not overwrite that custom status. A manually assigned captured/paid mapping is also protected from regression to pending.

Currency, country and amount restrictions

Payment currency

Select the currency sent to Nexi. Configure EUR unless Nexi has explicitly enabled another currency for the terminal. The plugin converts the VirtueMart order total into the selected payment currency before creating the HPP request.

Countries

Select the billing countries for which the payment method is displayed. Leave the field empty to allow all billing countries.

Minimum amount

The payment method is hidden when the checkout total is below this amount. Use 0 when no minimum is required.

Maximum amount

The payment method is hidden when the checkout total is above this amount. Use 0 for no maximum.

Accepted-payment logos

The payment method can display an official Nexi accepted-payment banner below the payment-method name:

• No logo;
• Without American Express — the default;
• With American Express — contract required.

Use the American Express banner only when the merchant has the corresponding card-acceptance agreement.

Additional images selected from VirtueMart’s payment-logo media area are rendered in the same responsive logo area as the official banner. Additional logos do not enable the corresponding payment service.

Payment fees

VirtueMart can apply:

• a fixed fee per transaction;
• a percentage fee calculated from the order total;
• an optional VirtueMart tax rule for the payment fee.

Before adding a surcharge, confirm that it is permitted by the merchant agreement and applicable law. Leave both fee values at zero when no payment fee is required.

Checkout and Hosted Payment Page behavior

When the customer confirms the order:

1. The plugin confirms that the software license permits a new payment.
2. It validates the selected environment, API key, amount, currency and installment selection.
3. It creates a unique Nexi order reference and correlation ID.
4. It stores a pending payment-attempt record linked to the exact VirtueMart order.
5. It creates the Nexi Hosted Payment Page session.
6. It redirects the browser only to the expected HTTPS Nexi HPP host.
7. Nexi presents the methods enabled for the terminal and available on the customer’s device and browser.
8. On return, cancellation or notification, the plugin retrieves the order from the Nexi API before changing the VirtueMart status.

If JavaScript redirect is unavailable, the confirmation page includes a manual Continue to Nexi link.

The Nexi sandbox or HPP may display a Return to store control instead of returning automatically. A customer closing the browser does not prevent server notification or later administrator reconciliation from verifying the transaction.

HPP language selection

The plugin uses the language saved with the VirtueMart order. If the order has no stored language, the active Joomla language is used. Unsupported language tags fall back to English.

Version 1.0.0 maps the following Joomla language prefixes to XPay HPP language identifiers:

The plugin sends the correct XPay identifier, including ELL for Greek. The final wording and availability of translations on the hosted page remain controlled by Nexi.

Callback and notification URLs

The HPP request includes three protected URLs:

• a successful browser-return URL;
• a browser-cancellation URL;
• a server notification URL.

Each payment attempt receives separate random callback capabilities. Only hashes are stored locally. Callback data from the browser or the incoming notification is not accepted as proof of payment; the plugin retrieves the authoritative order state from Nexi.

Production requirements

For production:

• Use a public HTTPS Joomla URL.
• Normally leave Notification HTTPS base URL empty.
• Allow Nexi to reach the notification endpoint.
• Avoid authentication walls, maintenance rules, CDN challenges or firewall rules that block Nexi callbacks.
• Keep Joomla able to make outbound HTTPS requests to the Nexi API.

If notification delivery fails, the order can still be verified on browser return or when an administrator opens the VirtueMart order.

Order verification and reconciliation

The plugin verifies a Nexi order in these situations:

• the customer returns through the HPP result URL;
• the customer returns through the cancellation URL;
• Nexi calls the notification URL;
• an administrator opens the VirtueMart order;
• an administrator completes a capture or refund.

Opening an order in the VirtueMart administrator requests the current Nexi state and refreshes the displayed Nexi details. Repeated requests within a short cooldown may reuse the latest verified result to avoid duplicate API traffic. This reconciliation can also occur when an old order is opened months later, subject to the Nexi API still making that order available.

The order panel displays the Nexi order ID, latest correlation ID, last operation, authorized amount, captured amount, refunded amount, installment quantity and action history.

Capture and refunds

Capture and refund controls appear in the VirtueMart order only when Nexi reports that the specific operation currently allows the action.

Capture

Use capture after a successful authorization created under an explicit/manual-capture flow:

1. Open the order in the VirtueMart administrator.
2. Review the verified authorized and captured amounts.
3. Locate Available Nexi actions.
4. Enter an amount within the minimum and maximum displayed by Nexi.
5. Select Capture.
6. Wait for the plugin to re-verify the order before taking another action.

Full or partial refund

1. Open the captured order.
2. Review the verified captured and already refunded amounts.
3. Enter a refund amount within the range currently allowed by Nexi.
4. Select Refund.
5. Confirm the new verified amounts after the page reloads.

The order changes to the configured Fully refunded status only when the verified refunded total covers the complete order amount. A partial refund retains the captured status.

Administrator actions require VirtueMart management permission and a valid Joomla security token. Amount limits are re-read from Nexi immediately before the request, and each request uses idempotency protection. Do not submit the same action repeatedly after a slow response; reopen the order and review the verified state first.

Capture and refunds for existing transactions remain available even if the software license has expired or new payments have been disabled after a license disconnection.

Testing and production readiness

Complete the merchant acceptance checks in TEST mode before entering a LIVE API key.

Recommended minimum checks

1. Confirm that the payment method appears only for the intended countries, currency and amount range.
2. Complete one successful card transaction and verify the result in both VirtueMart and the Nexi dashboard.
3. Complete one declined or failed card transaction and confirm that it does not become paid.
4. If installments are enabled, complete a card payment using an allowed installment quantity.
5. Confirm that the notification URL is publicly reachable and that the VirtueMart order is verified.
6. If using explicit capture, confirm authorization and then perform an allowed capture.
7. If refunds are required, perform a permitted refund and verify the amounts.
8. Test IRIS, Apple Pay and Google Pay only when each service is enabled for the terminal and a suitable test or real wallet environment is available.

Reaching an Apple Pay or Google Pay screen is not proof of a completed wallet transaction. A successful test requires confirmation by the wallet and an authoritative Nexi order state.

Before switching to LIVE

• Confirm the production API key and terminal accounting mode.
• Confirm which payment methods are enabled by Nexi.
• Use the permanent public HTTPS shop URL.
• Remove temporary notification URL overrides.
• Confirm the shop’s terms, privacy and cancellation/refund information.
• Confirm that safe debug is disabled unless it is temporarily required.
• Verify the customer-facing payment name and accepted-payment logos.

Troubleshooting

Data, privacy and security

Data sent to Nexi

To create and verify a payment, the plugin sends the required order reference, amount, currency, selected installment plan, callback URLs and available customer information from the VirtueMart order. Customer information may include the cardholder name, email, telephone number and available billing and shipping address fields.

Merchants remain responsible for providing the appropriate privacy notice and lawful basis for processing customer and order data through VirtueMart and Nexi.

Data stored by the plugin

The plugin stores a payment record linked to the VirtueMart order. It includes:

• VirtueMart and Nexi order identifiers;
• operation and correlation identifiers;
• currency and payment amounts;
• authorized, captured and refunded totals;
• installment quantity;
• operation status and bounded action history;
• hashed callback capabilities and synchronization timestamps;
• configured fee values associated with the order.

The plugin does not duplicate the customer’s name, email or postal address in its payment-record table. Those details remain part of the VirtueMart order.

Data not stored by the plugin

The plugin does not collect or store:

• card numbers;
• card security codes;
• wallet payment credentials;
• raw browser or notification callback capabilities;
• full Nexi API payloads in debug logs.

Card and wallet credentials are entered on and handled by the Nexi Hosted Payment Page.

Secret handling

• TEST and LIVE Nexi API keys use VirtueMart’s encrypted-field storage.
• Software-license and protected-update credentials use authenticated local encryption tied to the Joomla installation.
• API keys, license keys, authorization headers and update tokens are excluded from safe debug output.
• Browser returns and incoming notifications never prove payment status without a fresh or safely cached Nexi API verification.

Updating the plugin

An activated license with current update entitlement connects the plugin to protected Joomla updates.

To check for updates:

1. Open System → Update → Extensions in Joomla.
2. Select Check for Updates.
3. Review the version and changelog.
4. Back up the website.
5. Install the update through Joomla.

Do not share or manually copy the Download Key shown in Joomla’s Update Sites interface. Treat it as a secret.

If the subscription has expired, the installed plugin keeps processing payments, but protected updates and support are no longer included.

Version 1.0.0 limitations

Version 1.0.0 does not support:

• Joomla 6;
• Nexi contracts or regional products outside XPay Greece;
• stored cards or card tokenization;
• recurring payments or subscriptions;
• payment methods not enabled for the merchant’s Nexi terminal or contract;
• forcing Apple Pay or Google Pay on an unsupported device or browser;
• forcing the Nexi HPP to return automatically when the provider page requires the customer to select Return to store.

Getting support

Before opening a support request, collect:

• Joomla version;
• VirtueMart version;
• plugin version;
• TEST or LIVE environment, without the API key;
• VirtueMart order number;
• Nexi order ID;
• correlation ID;
• approximate date and time of the issue;
• the expected result and the actual result;
• a screenshot with all keys, Download Keys, customer data and private identifiers removed;
• relevant safe debug lines after reviewing them for sensitive data.