This plugin integrates the payment method NetsEasy into your JTL shop.
Nets (Network for Electronic Transfers) is part of the Nexi Group and offers simple, fast and secure payment solutions. A charge can be understood as a payment collection of a previously reserved amount.
The Nets Easy plugin enables payments to be offered via Nets Easy.
Payment method “Nets Easy”
Overview and search of payments
Manual payment processing (Full-/Partial- Charge und Refund)
Configuration help for the plugin
Cancelling from the WAWI
Automatic full charge for partial or complete shipment
Explanation of terms
A reserved amount is reserved/authorized for payment collection, but no payment has been collected on it yet.
A charge can be understood as a payment collection of a previously reserved amount. Accordingly, full charge means that the entire order amount is collected.
A refund is a refund of a previously collected payment.
A cancel is the cancellation of a reserved payment before the payment is collected.
The installation of the plugin is carried out according to the JTL standard as described here or you can also provide your existing ZIP file of the plugin via the "Upload" tab in the plugin administration and then start the installation in the "Existing" tab.
When updating to a newer version, you can follow the general installation with the difference that you have to press the update button directly in the plugin administration to update.
The plugin supports you in setting up the payment method, select the "Help" tab in the plugin for this. There you will get an overview of the configuration. At this point, check the settings you have stored for the payment and shipping methods.
The configuration of the payment type is done via the standard administration in the JTL shop. You can find the payment types under Administration → Payment methods. You can also find a direct link to this on the help page of the plugin. Select Nets Easy via the pencil icon and configure the payment method if required.
Here you can change or remove the payment method logo. Ideally, the logo should display the payment providers that you have agreed upon with netsEasy.
Some sample logos are contained in the plugin directory (<Shop>/plugins/s360_netseasy_shop5/paymentmethod/images). However, you also can configure any image you uploaded to your shop.
Always enter the logo url as an absolute URL (starting with https://).
In addition to the standard settings for payment methods, the settings for the payment method are located in the plug-in under Settings. Here you can store the data from your Nets Easy account that is necessary for operation in the plugin.
Here you can activate or deactivate the plugin outside the plugin administration.
Live Secret Key
The API key for Live Mode. You can find this key in your Nets Easy account under "Company > Integration > Live Environment > Secret key".
Live Checkout Key
The checkout key for Live Mode. You can also find this key in your Nets Easy account.
Test Secret Key
The API key for the test mode. You can find this key in your Nets Easy account under "Company > Integration > Test Environment > Secret key".
Test Checkout Key
The checkout key for Test Mode. You can also find this key in your Nets Easy account.
Select the operating mode here
Test - the plugin is in test mode and communicates with the sandbox. No real payments are made in this mode.
Live - the plugin is in live mode and accepts real payments.
Select the checkout mode here
Hosted - customers are redirected to an external Nets Easy site and complete the payment process there. Afterwards, they will be redirected back to the shop.
Embedded - to complete the checkout process, an iframe is displayed below the product overview on the order summary page. After successful payment, the customer is redirected to the order confirmation page. Further settings may be necessary for this. (See Tab. 2)
If an optional GTC URL is stored, it is transferred to Nets Easy and set in the checkbox text. If this is not specified, the shop's GTC URL is used.
If an optional data protection URL is stored, it is transferred to Nets Easy and set in the checkbox text.
This option describes when a charge is performed:
manual - no charges are performed, the merchant must trigger the charge via the plugin or the Nets Easy backend.
Immediately - a Full-Charge will be executed immediately after the reservation in Nets Easy.
First partial shipment - after the Wawi reconciliation, a full charge is carried out at Nets Easy for a partial shipment.
Complete shipment - after the Wawi reconciliation, a full charge is carried out at Nets Easy for a full shipment.
Note: Some payment methods (like SOFORT) are always immediately charged, independend of this setting.
Payment error email
Alternative e-mail address of the shop administrator. If an e-mail address is stored, an automatic e-mail is sent in the event of errors in charge or refund. Otherwise, the Shop Master e-mail address is used.
Mail template language
Select the language in which the notification e-mails are to be sent. If you select German, the e-mails will be sent in German. The same applies to English.
Activate extended logs in the shop log for the frontend. This adds additional debug messages to the debug log.
Activate extended logs in the shop log for the backend. This adds additional debug messages to the debug log.
PHP Query Selector
Enter an alternative class or ID of the element in the DOM to which the embedded checkout is to be intergated.
If the embedded checkout is selected, the "Complete order" button is always hidden. Make sure you always specify a valid element, otherwise the embedded checkout will not be displayed and the customer will not be able to complete an order with Nets Easy.
PHP Query Method
Specify here the method in which the embedded checkout is to be integrated.
after - the checkout is added after the specified element.
before - the checkout is added before the specifying element.
append - the checkout is appended to the specifying element.
prepend - the checkout is prepended to the specifying element
replaceWith - the specified element is replaced with the checkout
PHP Query Hide elements
Specify here the elements in the DOM that are to be hidden when using embedded checkout. By default, the element "#complete-order-button" (the “Complete order” button in JTL defaults) is always hidden. If your button ID is labeled differently, you can enter your own selector here.
Now assign Nets Easy to the desired shipping methods/countries under Administration → Shipping. The plugin also takes into account any surcharges for the payment method. You can also find a direct link to this on the plugin's help page.
In order for the payments made via Nets Easy to be assigned to the orders in the JTL WAWI, further settings must be made here.
Set up payment method
Open the payment method management in the JTL-WAWI via Payments → Payment methods.
Create Online checkout as the payment method. Please note that the payment types must correspond to the "Displayed name" in the JTL Shop in each language.
By default, the payment collection is set to immediate. However, if you decide on payment collection for the first partial shipment or only for complete shipment, then further settings are required. “Auslieferung vor Zahlungseingang möglich“ must be activated. The full charge will then be executed depending on the plug-in settings with the next Wawi synchronisation.
Attention, incorrect settings may occur!
If “Auslieferung vor Zahlungseingang möglich“ is activated and charge is set to "manual" in the plug-in settings, then no charge will be performed out by the plug-in.
In this case, you send the goods without an incoming payment!
The Nets Easy payment method is only available to customers under certain conditions
Your shop must support the currencies Danish Krone, Euro, British Pound, Norwegian Krone, Swedish Krona, US Dollar, Polish Zloty or Swiss Franc.
If the currently active currency is not supported, Nets Easy will not be offered as a payment method.
In the plug-in backend, you can view the orders that were paid for with Nets Easy. The search function helps you to find the desired orders.
The payment ID of Netz Easy
The JTL shop order no.
Total amount of the order in the JTL shop
Total amount of the reservation at Nets Easy
Total amount of the charge at Nets Easy
Total amount of repayments at Nets Easy
Status Amounts Reserved, Charge and Refunded to each other
Status of the last action performed
Actions that can be applied to a payment
Show - Click the eye icon to view the payment details. In addition to the order details and payment information, the charges and refunds are also listed here (see payment details page). This action is always available.
Charge - Click the dollar icon to perform a full charge. The total reserved amount will be charged. This action is possible as long as the payment status is "reserved".
Cancel - Click the stop icon to cancel the payment. The total reserved amount is released to the customer. This action is possible as long as the payment status is "reserved".
Refund - Click on the undo icon to perform a full refund. The total charged amount charged is refunded to the customer. This action is possible as long as the payment status is "charged".
On the payment overview, actions can only be performed in the context of a full request of charge, refund or cancel.
Payment details page
The payment details page displays the information provided by Nets Easy for the payment. This includes customer and payment information as well as billing and shipping address. If debugging is activated for the backend, the raw data of the transaction is displayed on it.
The subsequent order items are loaded from the JTL shop cart and can be selected via the checkboxes for a partial charge or partial refund. The partial actions (partial charge / partial refund) are only available on the payment detail page.
If an error occurs during processing, you will be informed in the backend in the info area of the payment overview page with the corresponding error message. This message is also logged in the shop log.
Take care not to charge or refund more than the maximum possible item quantity.
If partial charging has been performed once, a full charge can no longer be executed. You must "charge" the remaining amount via one or more further partial charges.
The order quantities of the order items are decremented by the number of quantities that have been charged. If an order item is at 0, then no further charges can be performed for it. For a better overview, the initial quantity is displayed next to the input field. If no further charge can be performed, the button partial charges is no longer displayed.
You can carry out one refund or one or more partial refunds for each charge. Refunds across batches are not possible.
A second partial refund can only be performed if the refund has been successfully completed or cancelled beforehand. Cancelling a refund is only possible as long as the refund is in the "pending" status and as long as the "Cancel refund" button is displayed.
Rounding differences may occur when creating a charge or refund. Especially with partial charges or partial refunds for cart items. The plugin uses the JTL shop cart items and JTL's own calculation procedure. It is therefore able to compensate rounding differences, as all amounts are based on a uniform and more accurate calculation. In this case, it is no longer necessary to create compensation items.
Deviations from those in the Nets Easy backend are unavoidable because only two decimals are taken into account and not significantly more, as in the JTL Shop.
In order to compensate rounding differences in the Nets Easy Backend, you must insert a compensation item and adjust the sum of the items to the total sum of the charge or refund.
Purchase with credit
When using credit at JTL, please note that this credit does not exists as a cart item in the initial order. It is generally reduced from the total amount. In this case, however, the total amount of the shopping basket items no longer corresponds to the total amount of the order.
In order to be able to correct this, a pseudo shopping basket item is added to the Nets Easy payment and treated as a normal item in the payment procedure. Credits and vouchers are negative items in the shopping basket.
Vouchers and coupons
Vouchers and coupons are listed as normal cart items and should be considered more closely when partial charges or partial refunds are performed. As these are negative items, care should be taken when making payments to ensure that the total amounts are neither exceeded nor negative. In this case, Nets Easy will refuse the action with an API error.
Cannot overcharge payment …
Bad Request (negative Amount)
Incoming orders and incoming payments made with Nets Easy are transferred to the JTL WAWI by synchronisation with the Shop. Only the actions Full-Charge (depending on the payment collection) and Cancel can be executed from the WAWI.
Depending on the plugin settings for payment collection (see Table 1), the orders are already charged. Only in the case of payment on first partial shipment or full shipment extended settings must be made (see Setting up the payment type). The full-charge is then performed at Nets-Easy after the WAWI synchronization.
If the charge could not be performed, an info mail is sent to the shop administrator by the plug-in.
Go to the JTL-WAWI → F6 → Select order → right mouse button → Storno → Stornieren
Synchronize with JTL-Shop
The full charge is performed against Nets-Easy after the WAWI syncronization.
+++ ATTENTION, IMPORTANT +++
Please make sure that you do not accidentally cancel a wrong order in the JTL-WAWI! The JTL-WAWI offers the possibility to reverse a cancellation, but the actions you have made in this regard are transferred 1:1 to the online shop!
In this case, the order will be cancelled first and the payment will be cancelled against Nets Easy. Afterwards, the order would be reactivated but a payment will not be possible anymore!
If you subsequently send the goods, this will be done without a payment!
The payment method is displayed in the standard selection of payment methods in the JTL shop and has no customizable elements.
Why is there a status and a last status in the overview in the plug-in backend?
The first status is the Nets Easy status of the payment, this is determined depending on the amounts of reserved, charged and refunded amount. The last status is the resulting status from the last executed action for the payment in the backend. If a payment is managed via the Nets Easy backend, this action is forwarded to the plugin via a webhook and the payment is updated in the shop.
Charge equals zero
Reserved greater than charged amount
Reserved equals charged amount
Charged greater than refunded amount
Charged equals refund amount
Why are the status and action buttons not displayed?
The status and action buttons are only displayed if the API keys are entered under Settings. Please make sure that you transfer the keys correctly, otherwise you will see this message:
Why are refunds offered for some payments and not for others?
If the refund action is offered on the overview, then this payment was paid via a full charge. Otherwise, the full amount has been paid via several partial charges. Full Charges can be triggered via the Full Charge button or via the WAWI.
Only full-charges can be executed via the WAWI. This can be set once for the first partial shipment or for the complete shipment.
Why I can't enter a free charge or refund amount in the plugin backend?
The plugin calculates the totals for charges or refunds from the JTL shopping cart. In this way, we ensure that the calculation of the amounts is always based on JTL's own calculation procedure. This minimizes rounding errors when you charge or refund partial quantities for an order item.
Why is useCredit as an item in the order?
If the customer pays with credit from their customer account, inconsistencies arise in relation to Nets Easy. In JTL shop, the balance is reduced from the total amount and is not an order item. Nets Easy, on the other hand, expects the total sum of all items to match the total amount, for which the credit would have to be an general order item.
"useCredit" is added once to the order as a pseudo-element to compensate for this inconsistency.
If you observe problems with the plugin, first check the logs and, if necessary, contact our support or your service partner if you cannot solve the problem on your own.
The more information you can give the support team about a problem, the sooner we will be able to help you. Non-reproducible problems, on the other hand, are also difficult to analyze.
This currency is not supported
This message is displayed if the customer has accidentally set the currency on the order summary page to a currency not supported by Nets Easy. The customer is returned to the Shipping and Payment page and can select a payment method that matches the selected currency or change the currency in that way Nets Easy is available as a payment method again.
The payment was terminated
This message is displayed if the customer has clicked on "< Go back" in the Nets Easy Checkout and cancels the payment without going through the checkout.
The payment could not be confirmed and was cancelled
In some cases it may happen that the payment could not be confirmed immediately. For example, if there are time delays between the customer's redirect to the return url and the processing of the payment. In this case, the customer is put on hold. The waiting loop periodically (max. 60 seconds) checks for an incoming callback from Nets Easy for the current Payment-Id. If no callback arrives on the webhook after the waiting time has elapsed, then the payment is cancelled against Nets Easy and the above message is displayed.
The payment was already terminated
This message is displayed if the payment has been terminated or cancelled in the meantime.
The charge has failed
This message is displayed when the charge could not be made. The payment was cancelled against Nets Easy. Check the shop log.
A general error has occurred
This message is displayed when the API client is initialized with invalid configuration. Check the shop log.
An API error has occurred
This message is displayed when there are errors in the communication with the Nets Easy API. Reasons for this can be invalid input characters or incorrect API credentials. Check the shop log.
An internal error has occurred
This message is displayed when an error has occurred at the communication level. Internal data cannot be validated or there is an internal problem that prevents communication with Netz Easy.
In the plug-in backend, success and error messages are displayed to the merchant for each action. The plug-in logs all actions into the shop log (debug level). All corresponding messages and the general communication with the Nets Easy API can then be conveniently filtered with the prefix "NETSEASY>".
To do this, first activate debugging in the log settings. Activate debugging in the plug-in settings, if required:
Outputs additional information of the notification endpoint.
Outputs the complete RetrievePaymentResponse.
Outputs additional information about the processing of the callbacks.
Outputs the curl options in the API client.
To find out where a problem lies, the logs help you and us. Depending on the error pattern, one of the following 3 logs is more or less relevant.
The browser log is usually relevant when something in the shop's frontend behaves strangely or does not react. (Example: You click a button and apparently nothing happens).
You can see the browser log by pressing F12 in the browser and then switching to Console.
The shop log is always interesting if unexpected error messages are displayed in the frontend or if the plug-in reacts to inputs in the frontend but does not deliver the expected result. Sometimes the browser log also shows that the information is more likely to be found in the shop log.
You can find the shop log in the JTL admin area under Administration → Troubleshooting → Log.
The JTL log works with log levels in order not to fill the database with log data indefinitely. Conversely, this means that you will only see log messages if they have been generated after the log level has been changed. The plug-in logs almost exclusively in the debug log level, except for critical errors. So if something does not work, you should first activate the debug log level, then perform a test order, then deactivate the debug log level again and consult the messages logged in the meantime.
The web server log becomes relevant if you encounter an error 500 (= white page) somewhere.
Your hoster can provide you with the web server log.
In the standard configuration, the JTL shop does not log anything in the web server log, not even critical errors such as an error 500.
In order for the shop to log these errors, the individual *_LOG_LEVEL values must be changed from 0 to E_ERROR in /includes/config.JTL-Shop.ini.php.
Attention: Only edit the shop's config file if you know what you are doing! Incorrect adjustments here can make your shop inaccessible or (encrypted) data unusable. If in doubt, ask your hoster or service partner for help.
v1.0.7 (August 2023)
Improvement: Webhook-Handling logs more specific/helpful information
Improvement: Internal Admin-Mails extended with information on order number and payment IDs to be more helpful. Attention: E-Mail Templates are not automatically updated with plugin updates. You have to manually reset the plugin mail templates in the shop admin to benefit from the improved mail templates.
v1.0.6 (July 2023, unreleased)
Improvement: Use product SKU instead of internal product ID towards NetsEasy
Improvement: Only set payment ID as transaction ID on payments to better allow for automatic handling in JTL Wawi
Improvement: Better backend url generation when in JTL-Shop >= 5.2.0
Fix: Check for existing column in migration.
v1.0.5 (May 2023)
Rework of payment logic to support both, embedded and redirected checkout, as well as different payment handlers.
Renamed initial display name to “Online Checkout”
Delivery now includes preset payment method description and logos
More debug logging messages and option to turn them on/off
multiple further improvements and fixes
v1.0.3 (February 2023)
Fix Bestellungen werden nach erfolgreicher Zahlung nicht angelegt!