Documentation Barzahlen Plugin for Magento

Content

1. Installation

1.1 Installation via Magento Connect

Information

Magento versions earlier than 1.5 require Connect 1.0 Extensions
Magento versions from 1.5 require Connect 2.0 Extensions

Open the Magento connect manager in the admin panel. You will find this under System / Magento connect. For security reasons you are requested to enter your user name and password again.

1.1.1 Automatic installation

Open the plugin page for Barzahlen on the Magento Connect website (http://www.magentocommerce.com/magento-connect/barzahlen-1.html) and have the extension key for your Magento version generated. Then insert the extension key in the Magento connect manager and click on Install.

The connect manager determines whether other extensions are required. As this is not the case, only the Barzahlen package is displayed, which you install by clicking on Proceed. After successful installation, return to the administration area to configure the payment module.

1.1.2 Downloaded plugin

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

Select the downloaded package via Search in the area Direct package file upload and then click on Upload. The module it then automatically loaded into your shop and installed. After successful installation, return to the administration area and configure the payment module.

Information

If, after installation, you have problems reaching the shop or the admin panel, check whether the file maintenance.flag is present in your shop directory and if so, delete it. The file prevents access to the shop during the loading or changing of extensions.

1.2 Manual insertion into the file system

Download the payment module for Magento in the integration area of Barzahlen (https://integration.barzahlen.de/en/shopsystems/magento). Unzip the downloaded archive into a folder of your choice.

Insert the subfolder app on your webserver into the folder of your shop system, which contains the same subfolder structure. In this way the necessary files are added to the system.

2. Configuration

2.1 Registering in partner area

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 index.php/barzahlen/ipn. 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/index.php/barzahlen/ipn

2.2 Configuring the module

Select the item System in the menu bar at the top and from there the sub-item Configuration. Then click on Payment methods in the area Sales in the menu on the left side.

Enter the data for the shop, payment key and notification key, which you received or was sent to you by email after you registered in the merchant area (https://partner.barzahlen.de). Leave the test mode switched on for the moment so you can test the module afterwards.

Currently only payments from Germany up to a total amount (goods value plus shipping costs) under € 1,000 can be made. These settings have already been set as standard.

Furthermore, you can determine the place where Barzahlen is to appear in the list of payment methods and if you would like to have additional data logged by the debug mode. Make sure that the payment module is activated. After you have made all settings, select the button at top right.

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 index.php/barzahlen/ipn. 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/index.php/barzahlen/ipn

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 the sending of all requests to the productive API, which saves the transmitted data and ensures processing of payments.

5.2 Managing payments

The payment slip is displayed to the customer immediately following the ordering process and at the same time the customer receives an email carrying the PDF document as an attachment from Barzahlen. If, nevertheless, your customer requests the payment slip again, you can initiate its resending in the order overview. First call up the list of all orders via Sales / Orders in the main menu bar. Select View in the line of the order concerned.

If the payment slip has not yet been settled at the store of one of our retail partners, you can resend it by clicking on .

5.2.1 pending

Every new order that is created has the status unpaid. After completion of the ordering process, 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 settled at the partner's store, Barzahlen contacts the IPN controller integrated in the payment module, provided that you have entered a notification URL in the merchant area.

The notification is validated and if checking is successful the order is given the status paid. The ordered merchandise has been paid for 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.1.9 of the Barzahlen module for Magneto (from version 1.5.1.0), the payment slip is automatically cancelled if you cancel an order in the Magento 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 under /var/log/barzahlen.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

7.1 Temporary deactivation

If you want to deactivate the Barzahlen module only temporarily, call up the configuration via System / Configuration in the menu bar at the top and click on Payment methods in the menu on the left side. Then select Barzahlen and select No for the field Activated in the drop-down menu.

Save your input by clicking on . This button is located at top right. Following deactivation, the Barzahlen payment module is no longer available to your customers, but your personal merchant data remains stored for later reactivation.

7.2 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 merchant area (https://partner.barzahlen.de).

If you have installed the Barzahlen module via the Magento connect manager, you can also perform uninstalling this way. Call up the Magento connect manager via System / Magento connect / Magento connect manager in the menu bar at the top. Enter your user name and password.

In the lower area you will see all installed extensions. Select the option Uninstall in the column Actions and then click on Commit changes. The module is now automatically removed.

If you have installed the payment module manually, you must also delete the following folders and files manually from your webserver in order to uninstall the module completely:

  • /app/code/community/ZerebroInternet/
  • /app/design/adminhtml/default/default/template/barzahlen/
  • /app/design/frontend/base/default/layout/barzahlen.xml
  • /app/design/frontend/base/default/template/barzahlen/
  • /app/etc/modules/ZerebroInternet_Barzahlen.xml
  • /app/locale/de_DE/ZerebroInternet_Barzahlen_Admin.csv
  • /app/locale/de_DE/ZerebroInternet_Barzahlen_Frontend.csv
  • /app/locale/en_US/ZerebroInternet_Barzahlen_Admin.csv
  • /app/locale/en_US/ZerebroInternet_Barzahlen_Frontend.csv
  • /var/log/barzahlen.log

8. Plugin Update

Information

From version 1.2.0 of the Barzahlen plugin you are automatically informed about updates at weekly intervals after logging in to the administration area.

To update the plugin to the latest version, first download the current version of the Barzahlen payment module. Open the Magento connect manager in the admin panel. You will find this under System / Magento connect. For security reasons you are requested to enter your user name and password again.

In the lower area you see all installed extensions together with their version number.

Automatic installation

Click the button located above the listed extensions on the right side of the title line. The Magento connect manager now checks all extensions for updates. Then select the latest plugin version and confirm your choice by clicking on Commit changes.

Downloaded plugin

Select the option Uninstall in the column Actions and then click on Commit changes. The module is now automatically removed.


After this, select the new, downloaded package via Search in the area Direct package file upload and then click on Upload. The module it then automatically loaded into your shop and installed. After successful installation, return to the administration area.


Information

If you have installed the module manually, unzip the downloaded archive and insert the content into the shop directory of your web server. When doing this, confirm overwriting of the old files. Then delete the cache via the admin menu (System / Cache management).

8.1 Update to version 1.1.0+

Select the item System in the menu bar at the top and from there the sub-item Configuration. Then click on Payment methods in the area Sales in the menu on the left side. Reduce the maximum amount to under 1,000 euros.


Select the button at top right.

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.