Nets Easy (English)

Introduction

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.

Features

Frontend:

  • Payment method “Nets Easy”

Backend:

  • Overview and search of payments

  • Manual payment processing (Full-/Partial- Charge und Refund)

  • Configuration help for the plugin

Wawi:

  • Cancelling from the WAWI

  • Automatic full charge for partial or complete shipment

 

Installation / Update

System requirements

  • JTL-Shop 5.00+ and its requirements

Other requirements

You need a trader account. Register at https://portal.dibspayment.eu/registration.

Registration

Plugin-Installation

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.

Plugin-Update

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.

Configuration

Shop

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.

Payment 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.

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.

Option

Description

Option

Description

Plugin active

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".

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".

Plugin mode

Select the operating mode here

Test - the plugin is in test mode and communicates with the sandbox.

Live - the plugin is in live mode and accepts real payments.

Checkout mode

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. After successful payment, the customer is redirected to the order confirmation page. Further settings may be necessary for this. (See Tab. 2)

Optional GTC-URL

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.

Optional Privacy-URL

If an optional data protection URL is stored, it is transferred to Nets Easy and set in the checkbox text.

Charge

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.

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.

Debug Frontend

Activate extended logs in the shop log for the frontend

Debug Backend

Activate extended logs in the shop log for the backend

Tab. 1

Option

Description

Option

Description

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. By default, the element "#complete-order-button" is always hidden. If your button ID is labeled differently, you can enter your own selector here.

Tab. 2

Shipping methods

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.

JTL-Wawi

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 Nets Easy as the payment method. Please note that the payment types must correspond to the "Displayed name" in the JTL shop.

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!

 

Manual

Shop

Frontend

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 currency is not supported, Nets Easy will not be offered as a payment method.

 

Backend

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.

Column

Description

Column

Description

Payment-Id

The payment ID of Netz Easy

Order no.

The JTL shop order no.

Total

Total amount of the order in the JTL shop

Reserved

Total amount of the reservation at Nets Easy

Charged

Total amount of the charge at Nets Easy

Refunded

Total amount of repayments at Nets Easy

State

Status Amounts Reserved, Charge and Refunded to each other

Last state

Status of the last action performed

Actions

Actions that can be applied to a payment

Tab. 2

Actions

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

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)

Wawi

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.

Full-Charge

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.

 

Cancel

  1. Go to the JTL-WAWI → F6 → Select order → right mouse button → Storno → Stornieren

  2. 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!

 

Customization

The payment method is displayed in the standard selection of payment methods in the JTL shop and has no customizable elements.

FAQ

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.

Amount/last state

State

Amount/last state

State

cancelled

cancelled

Charge equals zero

reserved

Reserved greater than charged amount

partial charge

Reserved equals charged amount

charged

Charged greater than refunded amount

partial refund

Charged equals refund amount

refunded

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:

Unauthorized

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.

Troubleshooting

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.

Messages

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.

Check logs

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:

Frontend

  • Outputs additional information of the notification endpoint.

  • Outputs the complete RetrievePaymentResponse.

  • Outputs additional information about the processing of the callbacks.

Backend

  • 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.

Browser log

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.

Shop log

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.

Webserver-Log

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.

Changelog

v1.0.0 (August 2022)

  • Initial Release

Support und Contact

goto Support und Contact