Documentation Barzahlen Plugin for xt:Commerce 4

Content

1. Installation

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

Unzip the downloaded archive into a folder of your choice. The subfolder src contains the following folders, which you can simply load into your shop system:

  • plugins
  • templates
  • xtAdmin

2. Configuration

2.1 Activating the module

Log in to the administration area of your online shop and select Contents / Plugin / Uninstalled plugins in the side menu bar.

Select the Barzahlen plugin on the right side. Should the plugin not appear on the first page of the list, you can call up another page with plugins at the bottom edge of the screen.

Click the button located at the end of the line and confirm the following query with Yes in order to install the plugin. Installation is performed automatically and ends with output of the installation log.

Close the dialogue by clicking on . To activate the plugin, select the item Installed plugins located directly above the item Uninstalled plugins in the menu on the left side. Select the Barzahlen plugin from the module class payment.

Click the button to activate the plugin. Confirm the dialogue. The Barzahlen plugin is now installed.

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?page=callback&page_action=zi_barzahlen . 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?page=callback&page_action=zi_barzahlen

2.3 Configuring the module

Select the folder Setting and from there the sub-item Payment method in the left menu. At this point the status of the plugin is still inactive (red indicator lamp). Before activating the payment module, you should adapt the settings to your shop.

To do this, click on the processing button . This opens an overview with all available settings. The area Main store is relevant to the functioning of the module.

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

Proceed in the lower area by assigning the different Barzahlen statuses there an order status. The selected statuses are automatically assigned to orders if the status of the Barzahlen transaction changes in any way.

Information

You can define additional order statuses under Settings / System statuses / Order statuses. When doing this, make sure that the order statuses are also visible for both customers and admin. This ensures that the order status is displayed both for customers in their own profile, and for yourself.

After you have made all settings, place a checkmark behind Status (above the area Main Store) and select the button Save. Alternatively, you can select the payment module from the list after saving and integrate it into your shop via Activate selection.

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?page=callback&page_action=zi_barzahlen . 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?page=callback&page_action=zi_barzahlen

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 Overview

You can find an overview of all Barzahlen transactions in the submenu Order / Customers / Barzahlen in the administration area.

Here all transactions are listed with their ID, order numbers, amount and currency. In addition, a refund to the customer can be initiated here after the return of goods. Furthermore, you can resend the payment slip for an open order to customers if necessary by clicking on the resend symbol . If a customer cancels an order, you should also cancel the outstanding payment slip by clicking on . The cancellation function is available from version 1.1.4 and can be accessed via the merchant area (https://partner.barzahlen.de) before then.

5.2.2 Authorising refund transactions

You can perform refunds conveniently in the shop backend. Click on in the line of the transaction whose (partial) refund you would like to initiate. You are taken to the overview of all refunds concerning the desired transaction.

To add a new refund, click and enter the desired amount. Make sure that the total of the individual refund amounts does not exceed the original amount (goods value plus shipping costs).

Save your input and reload the table by clicking on . After the table has been updated the refund order appears. At the same time the status of the order is changed. With every status change for the refund, the status of the order changes automatically. This time too, you are able to resend the disbursement slip to customers. To do this, click on . Please note that customers already automatically receive a disbursement slip by email upon requesting a refund.

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

Transmission errors are automatically saved in the system log by the module in order to make it easier to determine and correct the error source. Errors in the case of notifications are saved in the IPN log. You can call up the error logs via the menu path System / Logfiles / System log or System / Logfiles / IPN log.

A list with all error messages opens in the main window. Every entry contains information on the time of the error, name of the module concerned, and an identification number. In the case of errors during the ordering process, the order number is entered for ID If a refund was not possible, the system enters the identification number of the transaction for which a refund should be paid.

Click on to get more detailed information on an error message.

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

To deactivate the Barzahlen plugin as a payment method only temporarily, select Settings / Payment method in the left menu.

Select Barzahlen and then click on . This does not result in the loss of your settings and you can re-activate the payment module at any time with a few clicks.

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

If you would like to uninstall Barzahlen, select in the same place (Settings / Payment method) or under Contents / Plugin / Installed plugins and confirm in response to the prompt. This will result in automatic uninstalling of the plugin. Please note that uninstalling the plugin results in the loss of all settings that have been made.

7.3 Complete deletion

To delete the module completely from your shop, first perform uninstalling. Then delete the subfolder zi_barzahlen from the folder /plugins as well as the file zi.resend.php from the folder /xtAdmin.

8. Plugin Update

Information

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

To install a more current version of the plugin you must first uninstall the old version. Select Contents / Plugin / Installed plugins in the side menu and then click on in the line with the Barzahlen module and confirm in response to the prompt. This will result in automatic uninstalling of the plugin. Then download the latest version of the plugin and perform installation and configuration as described above. Your transactions together with refunds are retained.

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.