Documentation Barzahlen Plugin for Shopware

Content

1. Installation

1.1 Download

If you have not yet downloaded the plugin, you can do this in the Barzahlen integration area (https://integration.barzahlen.de/en/shopsystems/shopware).

Unzip the downloaded archive into a folder of your choice. From the subfolder src load the folders engine and files into the root directory of your Shopware system.

1.2 Direct upload

Alternatively, download the module for direct uploading and upload the archive under the menu item Plugin manager in the administration area. Open this area and click the button Add plugin manually. Then select the archive file and click on Upload plugin.

1.3 Settings on the webserver

Make sure that the files/log subfolder in your shop directory has the authorisation 777. To change the authorisations or receive more exact information, right-click on the folder in your FTP program and select File authorisations.

If the setting has not already been made, change the authorisations to 777.

2. Configuration

2.1 Activating the module

Log in to the administration area of your online shop and select Configuration / Plugin manager in the menu bar.

Select the sub-item Installed from the area Management on the left side.

Then click on , in the Barzahlen line in order to install the plugin. After successful installation you can carry out the configuration.

2.2 Registering in Control Center

If you have not yet registered in the Barzahlen partner area (https://controlcenter.barzahlen.de/), please do this now. After you have filled out the registration form and verified your email address by clicking on the confirmation link, log in. Select the tab Divisions in Settings.

On the displayed page you will find the Division ID, the API key and the notification key. Here you can also set the notification URL for your shop in order to send status changes regarding transactions and refunds to the payment module so that these are automatically entered into your shop.

Information

The callback class, which processes notifications, is called by the URL suffix payment_barzahlen/notify. Supposing your shop URL was http://www.example-shop.com/, then you would enter in the Notification URL field the following in order to receive notifications: http://www.example-shop.com/payment_barzahlen/notify

2.3 Configuring the module

Enter the data for the shop ID, payment key and notification key, which you received or had sent to you by email after registering in the Control Center (https://controlcenter.barzahlen.de). Leave the test mode switched on for the moment so you can test the module afterwards. At the end of the setting column you can enable extended logging. If problems occur, this setting can help you localise them more quickly.

After you have made all settings, click the button Activate.

Finally, click the button Save to store your input in the system.

The payment module is now 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:

Information

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.

Information

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 (https://controlcenter.barzahlen.de/) 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.

Information

The callback class, which processes notifications, is called by the URL suffix payment_barzahlen/notify. Supposing your shop URL was http://www.example-shop.com/, then you would enter in the Notification URL field the following in order to receive notifications: http://www.example-shop.com/payment_barzahlen/notify

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 Update. This results in all requests being sent to the productive API, which saves the transmitted data and ensures processing of payments.

5.2 Managing payments

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.

The notification is validated and if comparison is successful the order is given the status paid. The ordered merchandise is paid and can be shipped.

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 (https://controlcenter.barzahlen.de).

From version 1.0.4 of the Barzahlen module for Shopware (from version 4.0.0), the payment slip is automatically cancelled if you cancel an order in the Shopware administration area.

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 in the subfolder /files/log.

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"
or
"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. (https://controlcenter.barzahlen.de)
"transaction not found"
or
"refund not found"
or
"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

Information

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 Control Center (https://controlcenter.barzahlen.de).

7.1 Temporary deactivation

To deactivate the Barzahlen plugin as a payment method only temporarily, select Configuration / Plugin manager in the menu bar. Select the button Edit in the Barzahlen line. Click the button Deactivate and save your changes by clicking the button Save.

7.2 Uninstalling

If you want to uninstall Barzahlen, select the Barzahlen module in the same place (Settings / Plugin manager) and click the button Uninstall. This will result in automatic uninstalling of the plugin. Please note that uninstalling the plugin leads to the loss of the settings that have been made.

7.3 Complete deletion

To completely delete the module from your shop, first uninstall it. Afterwards, you can remove the plugin by clicking the trash-symbol.
Alternatively, you can remove the plugin manually. To do so, remove the following folders and files from the structure of your shop system:

  • /engine/Shopware/Plugins/Local/Frontend/ZerebroInternetPaymentBarzahlen/
  • /files/log/barzahlen.log

8. Plugin Update

Information

From version 1.0.4 (1.0.2 with Shopware 3.5.6) of the Barzahlen plugin, you are automatically informed of updates at weekly intervals after logging in to the administration area.

To update the payment module of Barzahlen to a new version, proceed as follows: Download the current plugin for Shopware from the website (https://integration.barzahlen.de/en/shopsystems/shopware). Unzip the downloaded archive into a folder of your choice. The subfolder src contains the module files, which are fitted into a folder structure corresponding to the folder structure of the web shop on your web server.

  • engine
  • files

Move the folder modules to the root directory of your shop system. Confirm overwriting of the old files. Finally, empty the cache of your online shop.

8.1 Update to version 1.0.2+

If you have performed the preceding installation manually (without downloading from the Shopware extension store), please check whether the folder containing the module has the name "ZerintPaymentBarzahlen" or "ZerintPaymentBarzahlenSW3" before updating. You will find this folder under /engine/Shopware/Plugins/Local/Frontend.

Should the folder have the name "ZerebroInternetPaymentBarzahlen", please uninstall the plugin and the delete the folder. After this, install the latest version of the plugin in your shop according to the user manual. For correct assignment of orders, the database may then have to be adapted, as the orders can still run under the old payment method ID.

Note the number of the unnamed payment method and then open the area Settings / Payment methods via the menu. Here you will see the new value for Barzahlen.

Execute the following SQL command with the appropriate substitutions on your database.

UPDATE `s_order` SET `paymentID` = 'newValue' WHERE `paymentID` = 'oldValue';

After this the orders are correctly assigned again.

9. Support

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

You can send us an email at support@barzahlen.de 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.