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

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.

Installation / Update

System requirements

• JTL-Shop 5.0.0 and its requirements

Other requirements

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

Open

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.

Logo

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://).

Plugin-Settings

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.

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

Open

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

This message is displayed if the payment has been terminated or cancelled in the meantime.

This message is displayed when the charge could not be made. The payment was cancelled against Nets Easy. Check the shop log.

This message is displayed when the API client is initialized with invalid configuration. Check the shop log.

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.

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.

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.

Changelog

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.4 (unreleased)

v1.0.3 (February 2023)

• Fix Bestellungen werden nach erfolgreicher Zahlung nicht angelegt!

v1.0.2 (January 2023)

• Update Exsid

v1.0.1 (November 2022)

• Kompatibilität mit JTL-Shop 5.2

• Fix Embedded Checkout Link

v1.0.0 (August 2022)

• Initial Release

Support und Contact

goto Support und Contact