Documentation Barzahlen Plugin for OXID 4.7-4.9/5.0-5.2

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

1.2 Insertion into the file system

Unzip the downloaded archive into a folder of your choice. You will find the following folder structure, which is usual for OXID modules, in the subfolder src:

  • modules

Move the modules folder into the root directory of your shop system.

1.3 Adaptations for the database

Log in to the administration area of your shop system and select the item Service / Tools in the menu.

Select the button Search and open the file install.sql contained in the installation package. Then click on Start update.

2. Configuration

2.1 Activating the module

Open within the administration menu the area Extensions / Modules.

Select Barzahlen from the list of available modules. The area Main should open automatically. Click on to activate the payment module.

2.2 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?cl=bz_barzahlen_callback. 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?cl=bz_barzahlen_callback

2.3 Configuring the module

Select the Settings tab. Enter the data for shop ID, payment key and notification key which you received after your registration in the merchant area (https://partner.barzahlen.de). Activate the sandbox mode for now to test the payment module. Turn on debugging, if you want to have logged single connections in addition to error messages. Save your entries by clicking Save.

Open the area Shop settings and select the sub-item Payment methods. Then select Barzahlen from the list of available methods of payment. The basic settings for the area Master have already been set. This means that only purchases under 1,000 euros can be processed with Barzahlen.

Should you want to offer Barzahlen for another maximum value, enter this value and then confirm by clicking the button Save.

Click the button and then select, using drag-and-drop, the customer groups to whom you want to give the option of paying with Barzahlen.

Then select the tab Countries and click the button . Move Germany to the right side, to the assigned countries.

Next, assign the payment method Barzahlen to the desired shipping methods. To do this, click on Shop settings / Shipping methods in the administration menu.

Select one after the other all shipping methods that are to be offered together with Barzahlen. To do this, select the desired shipping method in the list and open the tag Payment methods. Then click the button . Then move Barzahlen to the right side.

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 index.php?cl=bz_barzahlen_callback. 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?cl=bz_barzahlen_callback

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

5.2.1 Overview

Navigate to the order overview in the shop backend (Manage orders / Orders). Select the order that interests you. The Barzahlen module extends the order overview with a tab that can be used to access all information on the current status of transactions. If your customer requires the payment slip again, you can have it re-sent to the stated email address by clicking the button .

5.2.2 Cancelling the payment slip

From plugin version 1.1.4, if an order is deleted or cancelled in the OXID administration area the related outstanding payment slip is automatically cancelled. If the order is only cancelled and therefore remains in the system, successful parallel cancellation of the payment slip is shown in the status.

In the case of early versions of the Barzahlen plugin, after cancellation of the order it is necessary to cancel the payment slip in the merchant section (https://partner.barzahlen.de).

5.2.3 Initiating refunds

You can carry out refunds conveniently in the shop backend. As soon as an order has been paid, a table with refund information appears in the overview. Simply enter the desired amount and confirm by clicking on Save. The maximum permissible amount is displayed on the right. This is obtained from the original amount less pending and completed refunds.

After the refund has been successfully received by Barzahlen, you receive confirmation and the amount appears in the overview. Here too you are able to re-send the disbursement slip if required.


Like the success message mentioned above, the system informs you of the result whenever new information is entered.

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

In order to deactivate the Barzahlen plugin as a payment method only temporarily, select Shop settings / Payment methods in the administration area. Then select the Barzahlen module from the list and remove the check in the checkbox Active.

7.2 Uninstalling

Information

Please note that you will not receive status changes for open transactions after uninstalling the module. However, these can be called up at any time in the merchant area (https://partner.barzahlen.de).

Deactivate the module as described above and then delete the files that you inserted into the shop system during preparation.

  • /log/barzahlen.log
  • /modules/bz_barzahlen/

8. Plugin Update

Information

From version 1.1.4 of the Barzahlen plugin you are automatically informed about 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 your OXID version from the website and simply overwrite the existing module files.

Log in to the administration area of your shop system and select the item Service / Tools in the menu.

Select the button Search and open the file update.sql contained in the installation package. Then click on Start update.

Then open the area Barzahlen / Settings and re-enter your shop ID, your payment key and the notification key. Then empty the folder /tmp in your shop directory and reload the administration area.

8.1 Update to version 1.1.0+

Open the area Shop settings in the shop backend and select the sub-item Payment methods. Then select Barzahlen from the list of available methods of payment.

Reduce the maximum value to 999.99 euros at the most and then confirm by clicking the button Save.

8.2 Update to version 1.1.1+

Delete the following files. These have been moved to the modules folder in the new version.

  • /admin/barzahlen_settings.php
  • /admin/barzahlen_transactions.php
  • /out/admin/de/barzahlen_lang.php
  • /out/admin/en/barzahlen_lang.php
  • /out/admin/tpl/barzahlen_settings.tpl
  • /out/admin/tpl/barzahlen_transactions.tpl
  • /out/[ihr_template]/de/barzahlen_lang.php
  • /out/[ihr_template]/en/barzahlen_lang.php
  • /views/barzahlen_callback.php

8.3 Update to version 1.1.3+

Delete the old module folder (/modules/barzahlen/) from your shop system. The new module folder is located at /modules/bz_barzahlen/.

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.