VibeFox Netopia for Adobe Commerce — Ayuda

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the OpenSSL, DOM and SimpleXML extensions.

Currency: the order currency (the currency the customer pays in at checkout) must be RON, EUR, USD or GBP. EUR, USD and GBP must be enabled on your Netopia account. For other currencies the payment method is hidden at checkout.

Netopia account: you need a Netopia Payments seller account with a point of sale. From its technical settings you need the account signature and, for each environment you use (sandbox and live), the public certificate (.cer) and the private key (.key). Nothing has to be set up on the Netopia side: the IPN address is sent with every payment request.

Public store: the IPN (confirm) URL must be reachable from the internet, not behind a login or basic authentication. Orders are marked paid only by the Netopia IPN.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-netopia-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/NetopiaPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_NetopiaPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Netopia Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. In the Netopia admin open your point of sale, copy the account signature and download the certificate and private key of the sandbox and of the live environment. Paste the signature and the full file contents into the settings (see Configuration). Set Enable to Yes and click Save Config. Test a payment in sandbox mode, then set Test mode to No to take real payments.

The module adds the Card Payment (Netopia) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Netopia payment requests, notifications and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Netopia Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. Delete data on uninstall is read for the default store view, so set it in the Default Config. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Netopia: enter a payment title of 1 to 128 characters.), or a Sort Order that is not a whole number (Netopia: sort order must be a whole number.). An invalid certificate or private key is not saved: Magento shows Netopia: invalid certificate or private key in plus the field name, the previous value is kept and the other fields are saved.

General

Enable: shows or hides Netopia at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Card Payment (Netopia). Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: Pay securely with your credit or debit card via Netopia. Below it the customer also sees You will be redirected to Netopia to complete your payment. and, in test mode, TEST MODE: no real payment will be made.

Netopia account

In the Netopia admin go to Seller accounts > your point of sale > Technical settings: copy the account signature and download the public certificate (.cer) and the private key (.key) of each environment. Open the files in a text editor and paste their full content, including the BEGIN/END lines.

Account signature: the seller account signature (format XXXX-XXXX-XXXX-XXXX-XXXX), the same for sandbox and live.

Test mode: uses the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys. Default: Yes. Set it to No to take real payments with the live keys on secure.mobilpay.ro.

Sandbox public certificate (.cer): the content of the sandbox public certificate file. It is used to encrypt the payment request.

Sandbox private key (.key): the content of the sandbox private key file. It is used to decrypt the IPN.

Clear saved sandbox private key: set it to Yes and click Save Config to remove the saved sandbox private key. It goes back to No after saving.

Live public certificate (.cer): the content of the live public certificate file.

Live private key (.key): the content of the live private key file.

Clear saved live private key: set it to Yes and click Save Config to remove the saved live private key.

Certificates and private keys are stored encrypted. A saved private key is never shown again: the field stays empty, and the note under it says Paste the full PEM content. Never displayed after saving; leave empty to keep the saved key. Use Clear saved key to remove it. Paste a new key to replace it. An empty certificate field removes the certificate.

Orders

Order status after payment: the status of a paid order.

Conditions

Payment from Applicable Countries: All Allowed Countries (the default) offers Netopia for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Netopia only for billing addresses in these countries.

Minimum Order Total: offer Netopia only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Netopia only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Advanced

Debug log: writes requests and IPN processing to var/log/netopia_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Card data, keys and customer contact details are not logged. Errors and warnings, for example rejected IPNs, are always logged, even when this option is No. Default: No.

Log: shows the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings (including the saved keys) and the log (see Uninstall). The license key is always removed. The Netopia payment records always stay. Default: No.

IPN and setup

The last row of the group shows the IPN (confirm) URL. It is the storefront URL of the default store view and looks like https://your-store/wcpnetopiagateway/notify/index/; the URL sent with a payment is built for the store view of the order. It is sent with every payment request as the confirm URL, so you do not need to enter it in the Netopia admin. When Enable is Yes, the row also warns you with Netopia: enter the account signature, public certificate and private key of the active environment. when something is missing (the payment method is then hidden at checkout), and shows TEST MODE: no real money is charged. while test mode is on.

Netopia sends the IPN to this URL. The module decrypts it with the saved private keys of both environments and checks your account signature and the payment request of the order. Netopia reports these actions:

A notification with a Netopia error code (for example a declined card) cancels the waiting order. Notifications that cannot be decrypted, carry another account signature or do not answer a payment request of that order are rejected and change nothing.

Checkout

At the payment step the customer chooses the payment method (by default Card Payment (Netopia)) and clicks Place Order. Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The next page shows You are being redirected to Netopia. and sends the customer to the Netopia payment page automatically, with the button Pay via Netopia and the link Back to checkout as a fallback. The payment request is encrypted with your Netopia certificate and contains the order total in the order currency, the description Order # with the order number and your store name, and the billing and shipping contact details. In test mode the request goes to the Netopia sandbox. Every payment attempt has its own request ID.

The customer pays by card on the Netopia page and returns to your store. The return itself never pays an order. The order is marked paid only after Netopia confirms it by the IPN. Magento then creates the invoice with the Netopia transaction as the transaction ID, the order gets the status from Order status after payment and the order e-mail is sent. A customer who returns after the confirmation sees the standard order success page. A customer who comes back in another browser lands on the home page.

If the IPN has not arrived yet when the customer comes back, a page shows Netopia has not confirmed your payment yet (or Payment requires manual review for an order on hold) and Please wait for confirmation before making another payment. with the links Check again and Back to checkout. The order is confirmed as soon as the IPN arrives.

If Netopia reported a cancellation or a decline, the order is cancelled (the stock goes back), and the returning customer is back in the cart with the cart restored and can try again or choose another payment method. Back to checkout also restores the cart while Netopia has not reported anything for the payment; the order then stays in Pending Payment. While a payment of the cart is authorized, under review or on hold, the cart is not restored and no new payment is started for it.

If the payment cannot be started, for example because the settings of the active environment are incomplete, the order currency is not supported or the order has nothing to pay, the order is cancelled, the cart is restored and the customer sees We could not start the Netopia payment. Please try again or choose another payment method. in the cart.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the payment cannot be stopped at Netopia. If Netopia confirms it later, the order is not reopened, and a note asks you to review the payment.

The module takes card payments through the Netopia v1 card protocol only. It has no capture or online refunds from Magento, no saved cards or one-click payments, no subscriptions, installments or other payment methods, and no Netopia API v2. Netopia is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Netopia, but Netopia has not confirmed the payment yet. This also covers a pre-authorization waiting for capture in the Netopia admin and a payment under review at Netopia (with a note). There is no invoice.

Processing or Complete: Netopia confirmed the payment. The status follows Order status after payment. The invoice is created with the Netopia transaction as the transaction ID, and a note shows the amount, the masked card number, the Netopia transaction and the request; sandbox payments are marked [sandbox].

On Hold: the amount or currency confirmed by Netopia differs from the order, only part of the payment was captured, or a sandbox (test) payment was confirmed while the store is in live mode (no real money was received). No invoice is created, and a note explains it. Check the transaction in the Netopia admin, then process the order or refund the payment there.

Canceled: Netopia cancelled or declined the payment of a waiting order, the payment could not be started, or the order was cancelled in Magento.

Closed: the payment was fully refunded in the Netopia admin and the module recorded the refund.

If Netopia confirms another payment for an order or cart that is already paid, or a payment for a cancelled order, the order is not changed or reopened. A note asks you to review and refund the duplicate in the Netopia admin. A repeated notification is acknowledged without changes. The notes are order comments that the customer does not see.

Netopia payment history

On the admin order page (Sales > Orders > View) the payment information shows the payment method title. The Information tab also shows Netopia payment history: all payment requests of the order with the request, environment (sandbox or live), amount, received amount, status, last IPN action, Netopia transaction and masked card, and below it the Refund history. The block is read-only. It is also shown when the module is disabled. The customer sees only the payment method title.

Refunds

Refunds are not made from Magento: the Netopia v1 card protocol has no refund call. Refund the transaction in the Netopia admin. Netopia then sends a credit IPN, and the module records the refund automatically as an offline credit memo for the refunded amount (an adjustment refund: no items are returned to stock) with an order note. A partial refund keeps the order status; a full refund closes the order. For EUR, USD and GBP orders the refunded amount, which Netopia reports in RON, is converted back to the order currency. A refund is never recorded twice and never for more than the amount not refunded yet. If Netopia reports an error for the refund, only a note is added. A refund of a payment on hold (without an invoice) is recorded in the refund history, and a full refund cancels the order.

The Refund button of a credit memo is not available for Netopia, and Refund Offline does not send money back through Netopia.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Netopia Gateway is the first row of the VibeFox Netopia Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-netopia and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Netopia is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees We could not start the Netopia payment. Please try again or choose another payment method. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds made in the Netopia admin are still recorded.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Netopia does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the active environment is complete (Account signature plus the certificate and private key of the sandbox when Test mode is Yes, or of live when it is No) and that the order currency is RON, EUR, USD or GBP. The IPN and setup row shows a warning when something is missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the IPN did not reach your store or was rejected, or the payment is a pre-authorization or under review at Netopia (see the order notes). Check that the IPN (confirm) URL from the settings is reachable from the internet (no basic authentication or firewall). Look at the Log field: rejected IPNs are always logged. Set Debug log to Yes to see every IPN. The customer's return alone never marks an order paid.

Log shows failed decrypting data: the private key does not match the certificate Netopia used. The IPN is decrypted with the saved private key of each environment, so keep the key of the other environment saved while its payments are still open. Netopia retries the IPN.

Log shows signature mismatch: the Account signature differs from the point of sale that sent the IPN. Copy it again from the Netopia admin.

Log shows unknown request or environment: the IPN does not answer a payment request your store made for that order in that environment (sandbox or live). Nothing is changed.

Log shows gateway not configured: no private key or no account signature is saved. Netopia retries the IPN, and the payment is recorded once the settings are complete.

Log shows payment busy, order missing or processing failed: the cart was being processed by another request at the same moment, or the order could not be updated. Netopia retries the IPN automatically.

The IPN URL shows an error in the browser: this is normal. The URL accepts only POST requests from Netopia.

IPNs fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the IPN URL too. Netopia retries the IPN, and the order is confirmed after the store is open again.

Warning on save about the certificate or private key: the pasted text is not a valid certificate or key. Paste the full file content including the BEGIN/END lines. The previous value was kept.

Order is On Hold after payment: read the order notes (see Order statuses). The amount or currency differed, only part was captured, or a sandbox payment was confirmed while the store is in live mode. Check the transaction in the Netopia admin.

A refund made in Netopia does not appear on the order: the credit IPN did not reach the store or was rejected. Check the log.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

For developers: the events netopia_p_supported_currencies and netopia_p_icon change the list of accepted currencies and the payment method icon.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_NetopiaPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_NetopiaPayment to remove the data, then bin/magento module:disable Vibefox_NetopiaPayment, delete the folder app/code/Vibefox/NetopiaPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete data on uninstall is Yes, the gateway settings (including the saved certificates and keys) and the log are removed too. If it is No, the settings are kept for a re-install. The tables of Netopia payment requests, notifications and refunds are always kept, so the payment history of earlier orders is still shown and their refunds are still recorded after a re-install. Existing orders keep their invoices, credit memos, payment notes and transaction IDs.

Netopia Payments and mobilPay are trademarks of their respective owners. This module is not affiliated with or endorsed by Netopia Payments.