Documentation Barzahlen Plugin for Gambio

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

Unzip the downloaded archive into a folder of your choice. The subfolder src contains several PHP and TXT files, fitted into a folder structure corresponding to the folder structure of the web shop.

  • admin
  • callback
  • includes
  • lang
  • logfiles
  • templates

1.2 Insertion into the file system

1.2.1 Inserting contents of the TXT files

The text documents contain source code parts that must be fitted into the existing core files in order to ensure trouble-free processing.

admin/start_php.txt

Insert the content into the file start.php in the admin directory of your shop, direct before the line "<?php include(DIR_WS_MODULES.FILENAME_SECURITY_CHECK); ?>".

<!--BOF - Barzahlen - 2013-05-17: Barzahlen Version Check-->
include(DIR_WS_MODULES . "barzahlen_version_check.php");
<!--EOF - Barzahlen - 2013-05-17: Barzahlen Version Check-->

include(DIR_WS_MODULES.FILENAME_SECURITY_CHECK);

template/[your_template]/module/checkout_success_html.txt

Make sure you select the current template of your shop. Insert the content into the file checkout_success.html, which is located in the subfolder module of your template, in the place where you want to display the Barzahlen information.

<!--BOF - Barzahlen - 2015-02-25: Barzahlen Checkout-Page-->
{if $BARZAHLEN_BLOCK}
{$BARZAHLEN_BLOCK}
{/if}
<!--EOF - Barzahlen - 2015-02-25: Barzahlen Checkout-Page-->
1.2.1.1 Gambio 1.0.15

checkout_success_php_gx1.txt

When using Gambio Version 1.0.15, insert the content into the file checkout_success.php in the root directory of your shop, after the line „$order_status = $orders['orders_status'];“. This step isn't necessary for Gambio GX2 shops.

$order_status = $orders['orders_status'];

//BOF - Barzahlen - 2015-02-25: Barzahlen Checkout Page (GAMBIO GX1 ONLY)
$payment_query = xtc_db_query("SELECT payment_method FROM ".TABLE_ORDERS." WHERE orders_id = '".$last_order."' LIMIT 1");
$payment = xtc_db_fetch_array($payment_query);

if($payment['payment_method'] === 'barzahlen') {
  if (isset($_SESSION['infotext-1'])) {
    $smarty->assign('BARZAHLEN_BLOCK',$_SESSION['infotext-1']);
    unset($_SESSION['infotext-1']);
  }
}
//EOF - Barzahlen - 2015-02-25: Barzahlen Checkout Page (GAMBIO GX1 ONLY)

1.2.2 Inserting PHP files and log file

Insert all the files not ending in .txt into the existing folder structure of your webshop.

1.3 Settings on the webserver

Make sure that the logfiles 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

Login in the administration area of your online shop and select Modules / Payment options in the menu bar.

Then click on Barzahlen to select it from the list of payment options. An infobox, in which the module is briefly explained, appears on the right side, as well as a button for installation.

Click this button and the module will be 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 callback/barzahlen/callback.php. 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/callback/barzahlen/callback.php

2.3 Configuring the module

Click the button Editing. Enter in the upper area the data for the shop ID, payment key and notification key that you received after registering in the merchant area (https://partner.barzahlen.de).

Enter the maximum amount up to which you want to accept orders with Barzahlen. Use a dot (".") as a separator between euros and cents. Please keep in mind that payments with Barzahlen must remain under 1,000 euros, which means that the maximum amount possible is 999.99 euros.

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 Configuration / Order statuses. Click the button Insert located under the table. State the titles of the new status in the desired languages and then confirm by clicking on Insert.

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, set the setting Activate Barzahlen module to True and select the button Update. Leave the test mode switched on for the moment so you can test the module afterwards.

Delete the modul information cache:

Toolbox -> Cache:

Delete cache for modul informationen -> Apply

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

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

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

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 Modules / Payment methods in the menu bar. Select the Barzahlen module and click the button Process. Disable the Barzahlen Payment Module and then save your setting by clicking on Update. You receive status changes for already created transactions (e.g. when a customer pays), even if the payment module is deactivated for new orders.

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 would like to uninstall Barzahlen, select the Barzahlen module in the same place (Modules / Payment options) and click the button Uninstall. This will result in the plugin being automatically uninstalled. Please note that uninstalling the module leads to loss of the settings you have made.

7.3 Complete deletion

To completely delete the module from your shop, first uninstall it. Then you must remove the following folders and files from the structure of your shop system:

  • /admin/includes/modules/barzahlen
  • /admin/includes/modules/barzahlen_version_check.php
  • /callback/barzahlen/
  • /includes/modules/payment/barzahlen.php
  • /includes/modules/payment/ca-bundle.crt
  • /lang/english/modules/payment/barzahlen.php
  • /lang/german/modules/payment/barzahlen.php
  • /logfiles/barzahlen.log

Furthermore, you can delete the table barzahlen_transactions from your shop database. Finally you should remove the added source code parts from the following files:

  • /admin/start.php
  • /checkout_success.php
  • /template/[your_template]/module/checkout_success.html

8. Plugin Update

Information

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

To update the plugin to a new version, first open the administration area of your online shop and select Modules / Payment options in the menu bar.

Select Barzahlen from the list then click the button . Orders placed with Barzahlen are retained and are also updated by notifications again after the update. Download the current version of the plugin and unzip it into a folder of your choice. Then perform installation of the plugin as described in the user manual. Make sure in particular that you update the source code parts described under Insert contents of the TXT files. When uploading, confirm overwriting of the old files.

Log in to the administration area of your online shop again and select Modules / Payment options in the menu bar. Then click on Barzahlen and click the button . Then proceed, as described in the chapter Configuration, with the performing of the settings.

8.1 Update to version 1.1.0+

If required, delete the old barzahlen.log file from the webshop directory /includes/modules/payment.

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.