Documentation Barzahlen Plugin for JTL Shop 4


1. Installation

If you have not yet downloaded the plugin, you can do this in the Barzahlen integration area (

Unzip the downloaded archive. In the subfolder src you will find the plugin folder barzahlen, which contains the file info.xml and the directory version. Copy the folder barzahlen into the subfolder includes/plugins/ of your shop system.

Then open the administration area of your online shop. Select Plugins / Plugin management in the menu bar.

Select Barzahlen from the list of available plugins.

Then click on . After successful installation the payment module appears in the list at the top.

2. Configuration

2.1 Registering in partner area

Sofern Sie sich bisher noch nicht im Barzahlen-Partnerbereich ( registriert haben, holen Sie dies bitte nun nach. Nachdem Sie das Registrierungsformular ausgefüllt und Ihre E-Mailadresse durch Klick auf den Bestätigungslink verifiziert haben, loggen Sie sich ein. Wählen Sie den Menüpunkt Einstellungen und dort den Unterpunkt Divisionen.

Auf dieser Seite finden Sie Division ID, API-Schlüssel sowie Benachrichtigungsschlüssel. Weiterhin können Sie an dieser Stelle die Benachrichtigungs-URL für Ihren Shop einstellen, um Statusänderungen bezüglich Transaktionen und Rückzahlungen an das Zahlungsmodul zu senden, damit diese automatisch in Ihren Shop eingetragen werden.


Die Callback-Klasse, welche Benachrichtigungen verarbeitet, wird durch den URL-Zusatz includes/modules/notify.php aufgerufen. Angenommen ihre Shop-URL wäre, dann tragen Sie im Feld Benachrichtigungs-URL folgendes ein, um Benachrichtigungen zu erhalten:

2.2 Configuring the module

In the menu, select Storefront > payment methods > Overview

Select Barzahlen from the list of payment methods and click on .

Enter the data for the shop ID, payment key and notification key, which you find in the merchant area (

Select an upper limit for the shopping cart value in the case of payments with Barzahlen. Keep in mind that only payments under 1,000 euros can be made with Barzahlen.

Finally, make sure that the test mode is activated so that you can test the payment module in the next step.

Save the settings by clicking on Save.

Then switch to the menu item Storefront > Purchase processing > Shipping methods.

Select one after the other all shipping methods that are to be offered together with Barzahlen. In addition, click the button Edit under the particular shipping method. Activate Barzahlen in the area Accepted methods of payment.

Then scroll to the end of the page and save the settings by clicking on Shipping method. Repeat this step for every shipping method for which Barzahlen is to be offered. After this the module is configured and ready for use.

3. Carrying out a test order

3.1 Excluded orders

Check whether the exclusion criteria of the payment plugin are set correctly by running through the following buying scenarios one after the other:

  • order with a goods value higher than / equal to 1,000 euros
  • order with a customer address outside Germany

Here Barzahlen should not appear in the set of payment options because with each of these conditions the payment slip request to the Barzahlen API would fail and the customer would be returned to the set of payment options with an error message. At this point the aim is to prevent trouble at the customer's end and possible termination of the purchase.

3.2 Trial order

Now place any product (goods value under 1,000 euros) in the shopping cart and go to the checkout. Confirm the delivery address (inside Germany) and the shipping method and proceed to the step Select method of payment. Select Barzahlen from the list of options and continue the ordering process. Under the explanatory text the logos of our partners are displayed, as shown in a simplified form in the following graphic.

Mit Abschluss der Bestellung bekommen Sie einen Zahlschein angezeigt, den Sie sich ausdrucken oder auf Ihr Handy schicken lassen können. Bezahlen Sie den Online-Einkauf mit Hilfe des Zahlscheins an der Kasse einer Barzahlen-Partnerfiliale.

Bezahlen Sie bei:


Purchases that are made in test mode with Barzahlen contain a transaction number and a barcode that are assigned by the Barzahlen server. The transmitted data is stored only temporarily for test purposes. Trial purchases that are made can later be cancelled without hesitation in your own system.

Confirm the information you have provided in order to complete the ordering process.


Please note that the SMS function is not available in test mode and that no additional email with the payment slip is sent to the test customer. Furthermore, the three nearest partner stores are not listed on the payment slip. All functions are automatically available in live operation.

3.3 Simulating payment

Log in to the Barzahlen merchant area ( and in the area transactions switch to Sandbox transactions.

You see a list of all the sandbox transactions that you have effected for test purposes via your shop system. On the right side you are able to mark the transactions as paid by clicking . A click on simulates expiry of the time limit for payment of a Barzahlen transaction and a click on cancels a transaction.

By way of trial, pay a transaction of your choice. The status of the transaction changes to paid and, provided the sandbox notification URL has been correctly set, the status of the order in your system changes.


The callback class, which processes notifications, is called by the URL suffix . Supposing your shop URL was, then you would enter in the Notification URL field the following in order to receive notifications:

4. Adapting the shop

In addition to the actual integration of the payment plugin there are other details that should be considered after successful integration in order to ensure trouble-free processing.

4.1 General business terms and data protection

Extend your general terms of business as well as data protection information with the addition of passages concerning Barzahlen as a payment provider. You will find ready-made texts here: General business terms & data protection

4.2 Logos

If you use logos of payment providers in the footer of your online shop or on the homepage so that customers can see at first glance how they can pay for the purchases made in your shop, you can find logos here in order to call attention to Barzahlen as an offered method of payment: Logos

4.3 Description of payment

Many online shops have an additional information page that provides customers with detailed information about shipping and payment methods. Under Standard texts we have prepared texts in different lengths for you.

4.4 Emails

The payment method used, alongside the ordered goods or services, should also be listed again in the confirmation email. Make sure that your email template does not contain a bank transfer request or something similar so as not to unsettle customers after the purchase. An example of a detailed description of a payment method in the confirmation email can be found under Standard texts.

4.5 Advertising materials

Additional advertising materials for newsletters, blogs or announcements in your online shop can be found under Banner.

5. Live operation

5.1 Switching to live operation

To enable orders to be billed via Barzahlen, re-open the configuration for the Barzahlen payment module in the administration area of your online shop. Then deactivate the test mode.

Then save the setting by clicking on Save. This results in the sending of all requests to the productive API, which saves the transmitted data and ensures processing of payments.

5.2 Managing payments

Syncronize your orders with the JTL WaWi.

5.2.1 pending

When created, every new order has the status pending. After the ordering process has been completed, the customer receives a payment slip, which he can use to pay at an offline partner's store.

5.2.2 paid

As soon as the payment slip has been scanned and used to pay at the partner's store, Barzahlen contacts the integrated IPN controller of the payment module, provided that you have entered a notification URL in the merchant area.

5.2.3 expired

If the customer does not pay for the order with the help of the payment slip within the predefined period of time, the payment module receives a corresponding notification. The order status is automatically set to expired.

5.2.4 Cancelling the payment slip

If a customer changes his mind and cancels the order before the payment period expires or if you spot a fake order, you should cancel the payment slip in the control center (

6. Error handling

6.1 Transmission error during placing of the order

During processing of the order, the Barzahlen module starts a second attempt if an incorrect response, or no response, is received from the server. If the second attempt is also not successful, the customer is returned to the list of payment method options and can select an alternative payment method there in order to complete the order.

In this case, the reason for the error is recorded in the error log are later provides you with information about the cause.

6.2 Error logging

All errors that occur are automatically stored, together with the time of occurrence and relevant data, by the module in the error file barzahlen.log. You can find this error file under jtllogs/.

6.3 First aid

In the following table you will find error messages that, in some cases, you can remedy very quickly and easily yourself.

"bad request" You are probably using an old version of the plugin. Update to the latest available version and test the plugin again.
"shop not found" The Barzahlen server was not able to assign the entered shop ID. Please check the entered shop ID.
"hash not recognized"
"hash comparison failed"
The sent hash could not be verified. Please check the entered shop ID and the payment key with the data that you find in the control center. (
"transaction not found"
"refund not found"
"order not found"
You receive one of these error messages if, during processing of a notification, the order, the transaction or the refund was not found in the system. Make sure that you have not already removed the desired entry.
"Warning: error_log(...) failed to open stream: Permission denied" The necessary file authorisations for the log directory have not been set correctly (777). Resolve the problem as described in the section Settings on the webserver in the chapter Preparation.

Should you receive other error messages or should the proposed steps towards a solution not remedy the situation, do not hesitate to contact the technical support team.

7. Uninstalling


Please note that after uninstalling the module you receive no status changes for open transactions. However, these can be called up at any time in the merchant area (

7.1 Temporary deactivation

Open the sub-item Plugins / Plugin management in the administration area of JTL Shop.

Then select the Barzahlen plugin and click on Deactivate.

7.2 Uninstalling

Open the sub-item Plugins / Plugin management in the administration area of JTL Shop.

Then select the Barzahlen plugin and click on Uninstall.

7.3 Complete deletion

Perform uninstalling as described in the previous point. Then delete the folder barzahlen from the shop system folder includes / plugins.

8. Plugin Update

Download the latest version of the Barzahlen payment plugin. Unzip the downloaded archive. In the subfolder src you will find the plugin folder barzahlen, which contains the file info.xml and the directory version. Copy the folder barzahlen into the subfolder includes/plugins/ of your shop system.

Then open the administration area of your online shop. Select Plugins / Plugin management in the menu bar. In the list of installed plugins your attention is drawn to the update.

Click on Update. The update is installed automatically.

Select the sub-item Payment methods > Overview from the Storefront.

Select Barzahlen from the list of payment methods and click on Set.

Check the settings and save them by clicking on Save.

9. Support

The Barzahlen team will be happy to deal with any questions you might have.

You can send us an email at or use the contact form. Your email will then be forwarded directly to the responsible employee in our ticket system, who will deal with your enquiry.