Plugin: PayPal

General Information

The PayPal plug-in enables you to offer direct online payment (optionally through Express Checkout) as well as payment by installments and purchase on account.

Installation 

The installation of the plug-in is done, as usual from Shopware, through the Plugin Manager, which can be reached in the backend of your shop under Configuration > Plugin Manager. 
After installing the PayPal plug-in, you will find the modules Orders and Settings belonging to the plug-in in the backend under Customers > Payments > PayPal.
 

Compatibility to previous PayPal plug-ins

The plug-in PayPal offers you the possibility to transfer old orders to the new order overview module. This way all your PayPal orders will be displayed in the order overview of the new plug-in and you can part with the old PayPal plug-ins.

The orders that were processed with the old PayPal or PayPal Plus Plug-in will then appear in the new order overview and will be assigned to the correct payment method. As you can see, migrated orders are added with the addition "(old)". In addition, you will find a note about this compatibility mode in the order details, as not all information is displayed, e.g. for an order that was processed via the PayPal Plug-in. This includes e.g. the transaction history.

To take over your orders, you must first uninstall the previous PayPal plug-ins. Then you can open the order overview: All previous orders are now already stored, no further steps are necessary to transfer them.

Please verify the steps on a test system and make a backup, prior to changing the live system.
This will give you a easy overview what to expect and a way to roll back the system.

Accepted orders can be refunded as usual, but the payment process only shows the most current state will be displayed.

Only transactions of type "Sale" are supported. In the settings of the previous PayPal Plug-in, this corresponds to the option "Complete payment immediately (Sale)" for payment completion.

The current PayPal Plug-in is not compatible with any of the previous PayPal Plug-ins! It can therefore not be used with PayPal Express, PayPal Plus or PayPal Installment Payment in parallel. So please make sure to uninstall these plug-ins first when using the current PayPal Plug-in. Please make sure that all orders have been accepted before you delete the old PayPal plug-ins completely. This way you can avoid possible data loss.

Initial setup

After you have installed the plug-in, you can configure it in the PayPal module under settings.

Overview

The configuration module of the PayPal plug-in is divided into four areas, each of which can be accessed using the tab at the top of the window:

• General settings (1)
• PayPal Express Checkout integration (2)
• PayPal Plus integration (3)
• PayPal Installments integration (4)
   

In the tab General Settings you can set the API settings for PayPal in addition to the general settings for the behaviour and error handling of the plug-in.

Activation and shop selection

The PayPal settings can be configured for each shop using the drop-down menu Select Shop (1) in the upper right corner. So you have the possibility to define different settings for sub shops and language shops.
To use PayPal in your shop, you have to activate PayPal with the checkbox Enable for this shop (2).

Configuration of the API settings

In the next step you have to enter your PayPal access data received from PayPal.

Client-ID (1): Here you enter the PayPal REST-ID This is used by the plugin to authenticate itself with the PayPal API.

Client-Secret (2): At this point you enter the REST-API client secret, which the plug-in also uses to authenticate with the PayPal API.

Enable sandbox (3): Check this box if you just want to test the PayPal integration. Please note that the sandbox environment has its own access data.

Register webhook (4): The registration of the webhook can be triggered manually at this point.
Normally, the webhook is automatically transmitted and set up. More information can be found in the next section.

Test API settings (5): With the help of this button you can test the access data you have entered. The result of the test will be displayed directly in the backend by a message at the top of the screen.

Configuration of the Webhooks

If the webhook is not automatically transmitted and set up in your system, you can also register it manually. To do so, please go to the website developer.paypal.com and log in with your PayPal account. There you will find the menu item "My Apps & Credentials" in the "Dashboard" area. If you select your app from the REST API apps stored there, you will be taken to the Webhooks area. To add the Webhook, click on "Add Webhook".

The Webhook URL must have the following format:https://example.com/PaypalUnifiedWebhook/execute
This is your domain with shop addition, if available. This URL corresponds to the Notify-URL, but differs in the addition "webhook". Regarding the spelling, you can use both "CamelCase" and "snake_case". With the setting "Event Types", "All Events" must also be activated.

Classic PayPal

By entering the API data and activation in the tab Basic Settings, you use the classic PayPal for your shop. Thus your customers are able to pay for their orders with their PayPal account.

Please note that some settings in the tab Basic Settings do not only apply to the classic PayPal, but also to PayPal Plus or Express Checkout, if they are activated. 

Configuration

Under Behaviour in the tab Basic Settings you configure the following settings:

Merchant location (1): Here you select the merchant location. Depending on this, different functions will be made available to you.

Brand name on PayPal page (2): The text stored here will be displayed as brand name on the PayPal payment page.

In-context mode (3): Activate this option to keep the payment process via PayPal in the background and not in a separate window. You can find more information in the section In-Context Mode. Please note that the in-context mode cannot be used if PayPal Plus is activated!

Submit cart (4): Activate this option to transfer the shopping cart to PayPal

PayPal landing page (5): Here you can choose whether the PayPal landing page should display the registration form or the login screen.

Logo in sidebar (6): If you activate this option, the PayPal logo will be displayed in the sidebar of your storefront.

Please note that the following requirements must be met to display your logo on the PayPal site:

• The image must be accessible externally.
• The picture must be accessible under HTTPS
• The image must be one of the following file types: .gif, .jpg, or .png

Send order number to PayPal (7): Activate this option if you want to send the order number to PayPal after completion.

Oder number prefix (8): Here you can determine which text is appended to the original order number, e.g. myShopSW20001. This option is only available if you have activated the previous option "Transfer order number to PayPal".

Free returns (9): With this option you can promote free returns via PayPal. If you already offer free returns in your online shop, you do not need to activate this option.

Instalments banner (10): Check this box if you want to advertise the new installment payment via PayPal. This only works with your Live Client ID (not with the sandbox Client ID). The banner will be displayed in different areas of the frontend after activation, e.g. on the item details page or in the shopping cart.

The display of the banner* in the frontend, which can be clicked:

* Please note that it's only available in German

After clicking on the banner*, the calculation of the rates is displayed*:

* Please note that it's only available in German

In order for your customers to be able to use the new installment payment in your shop, they must select the payment method PayPal in the checkout and log in with their PayPal account. Your customers can then check whether the payment method Installment Payment is displayed.

You can find further information about PayPal installment payment at PayPal.

Error handling

The PayPal plug-in enables you to display error messages and activate logging with the error handling.

Display errors (1): Activating this option causes the communication error message to be displayed in the shop.

Logging (2): At this point you define how strict this logging may be. You have the choice to log only errors (option "Normal") or to log all types of errors (option "Advanced"). All types means in this context that normal events and warnings will be logged in addition to errors.

You can find the log files of your Shopware installation in the directory /var/log. For this plugin the log entries are stored in the file that starts with "plugin_production-". Every day a new log file is created.

Frontend view

If you have activated PayPal, your customers will find the following payment method in the order process:

The order completion page remains as usual from Shopware. However, the customer is redirected to PayPal after his click. Here the customer can then log in with his PayPal account.

After the customer has registered and confirmed the order by PayPal, the order is completed. The customer then sees the following page:

Here the customer can find the transaction number (1) of his order, which PayPal can use to identify his order. Accordingly, the order appears with this number and the payment status "Fully paid" (1) in the order overview in the backend of your shop:
 

In-context mode

The in-context mode can be activated with respect to the classic PayPal and also with the express order process. In this case, the ordering process differs a little from the classic way: Instead of being redirected to the PayPal pages, the PayPal page opens in a small window without the customer leaving the shop. Instead, your shop page is darkened and the PayPal page is displayed in a separate window.

The order confirmation page is also slightly different. The "Order by Paying" button is replaced by a PayPal button if the customer has chosen PayPal as payment method.

When activating PayPal Plus, please keep in mind that the In-context mode cannot be used completely in this case! However, the Express integration is not affected by this restriction. This means that the customer can use the In-context mode via the Express Checkout (no customer login in the shop), but not if the customer wants to use the normal order process as a regularly logged in customer.

Order overview

The PayPal plug-in offers a display in the standard order module as well as a separate overview of the orders processed by the plug-in. You can find this order overview under Customers > Payments > PayPal > Orders. Here you can see which orders were made with which PayPal type (Standard, Express, Plus, Installment).

In the right half of the window you can see the data PayPal has for the respective transaction. They are structured into the areas Order, PayPal transaction and Payment history.

Express Checkout

The plug-in offers the possibility of express checkout. This way your customer does not have to register in the shop for his order, the order will be processed only by his PayPal account.

Configuration

The configuration of the Express Checkout can be found in the separate tab PayPal Express Checkout Integration in the plugin settings. Below are the configuration options:

Payment acquisition (1): This is where you specify when the payment is collected - i.e. when it is completed.

'Pay now' on detail page (2): Here you can specify whether the PayPal Express button is displayed on the item details page.

'Pay now' on cart (3): Here you specify whether the PayPal Express Button should be shown in the shopping cart.

'Pay now' on Off-Canvas/modal cart (4): If you activate this option, the Express Checkout button will be displayed in the Off-Canvas/Modal shopping cart.

'Pay now' on login page (5): Here you can determine whether the PayPal Express button is offered on the login page.

'Pay now' on listing pages(6): If you enable this option, the Express Checkout button will be displayed on listing pages.

Button colour (7): This option offers you some colours in which the PayPal Express Button can be displayed. Gold, blue, silver, and black are offered.

Button shape (8): Here you set the shape of the PayPal Express Button. You can choose between round and square and set the shape of the PayPal Express Button.  You can choose between round and square.

Button size (9): This option allows you to specify how large the PayPal Express Button should be displayed. You can choose from small, medium, large, and Responsive.

Submit cart (10): Here you can choose whether the customer's shopping cart, i.e. the exact positions of the order, may be transferred to PayPal. If this option is deactivated, only the total amount is transferred.

Button locale (11): In this field you can enter different shop languages for the Express Checkout Button. If the field is empty, the shop language is used. You can find a list of available language codes on the PayPal page or by clicking on the link in the plugin.

Frontend view

The ordering process using PayPal Express is similar to the classic PayPal order process. The difference is that your customer does not need to create an account in your store to place an order. Instead, they can log in directly to PayPal with a button and complete the order. This PayPal Express button can be located in the shopping cart on the login page and on the item details page, depending on the configuration.

The Express button in the off-canvas shopping cart looks like this

When your customer edits his shopping cart, the view looks like this:
 

If your customer wants to register during the order process, an Express button can also be used:

Finally, the article itself can be ordered directly over PayPal by clicking on the express button on its detail page:

PayPal Plus

The PayPal plug-in includes a direct integration of PayPal Plus: You can offer your customers the four most popular payment methods used by German consumers from one source. Besides the classic PayPal, your customers can choose between SEPA direct debit, credit card and purchase on account.

Requirements

The product "PayPal Plus" must be activated individually for each merchant. If you have not already done so, apply for the activation here.
Please note that you have to unlock the purchase by invoice separately as well.
PayPal Plus is currently only available for retailers in Germany.

Configuration

You can configure PayPal Plus in the plug-in settings in the tab PayPal Plus Integration. The following configuration options are available:

Activate PayPal Plus (1): Check the box to activate the PayPal Plus integration for your selected shop.

Payment acquisition (2): This is where you specify when the payment is collected - i.e. when it is completed.

Restyle payment selection (3): At this option you can determine whether you want the payment method selection to be in Shopware- or PayPal-typical design. This is explained in detail in the section Appearance of the payment method selection.

Display other payments methods in iFrame (4): If you activate this option, third-party payment methods are displayed in the Payment Wall iFrame. Select the payment methods you want to display there under Configuration > Payment Methods > Free text fields > Display in PayPal Plus iFrame.

Payment method name (5): Here you can enter a different payment method name for the frontend, if desired.

Complete payment method description (6): Here you can add the payment type description in the front end. The description is displayed in the payment type selection, for example, in the account under the payment type description.

Frontend view

The order process can be carried out as usual if you want to use the payment options of PayPal Plus. PayPal, direct debit, credit card and purchase on account via iFrame are displayed in the payment method selection in the checkout. The prerequisite for this is that the customer has selected PayPal as the payment method in his account.

If the customer has already set PayPal as the active payment method, the iFrame is also displayed on the checkout confirmation page.

Unfortunately, if PayPal Plus is activated, order completion through the in-context mode is not available.

Appearance of the payment method selection

As mentioned in the configuration section, the appearance of the PayPal Plus payment method selection in the PayPal plugin can be customized. More specifically, it is possible to apply the styling of the PayPal Plus payment method iFrame to the entire payment method selection. If you activate the setting redesign payment method selection (3), the payment method selection is displayed as follows:

If this option is active, a further configuration option is shown: Show other payment types in the iFrame (4).
If you choose this option, the standard payment methods available in Shopware, as well as third-party payment methods, can be within the iFrame of the PayPal Plus payment methods, if set up accordingly. To do this, you must check the Display in PayPal Plus iFrame box in the Free text fields tab of the desired payment methods under Settings > Payment Methods:
 

In the frontend it looks like this:

There are payment methods which require additional fields directly in the payment method selection (e.g. the data details for SEPA direct debit). In this case this payment method is not compatible with the setting display other payment methods in iFrame. If such a payment type is integrated into the iFrame, its additional fields are not displayed and payments are therefore no longer possible.

Customizing the document template

If you offer PayPal Plus in your shop, the non standard footer is used, but the PayPal_Unified_Instructions_Footer, which has to be adapted first.

You can customize this under Basic settings > Shop settings > PDF document creation. Select the document Invoice and open the element PayPal_Unified_Instructions_Footer on the right side in the area Elements via the drop down menu. 
An editor will open, where you can customize the content of the footer. 
 

Payment in instalments powered by PayPal

The PayPal plug-in offers you a straight integration of "Installment payment powered by PayPal". This gives you the possibility to offer the customers of your shop the handling of larger purchases via installment financing.

Please note that "Installment payment powered by PayPal" is a product which is currently no longer available for new PayPal activations.
If you would like to offer the installment payment in your shop, you can do so via the successor product "PayPal Installment Payment". The new installment payment can be advertised in your shop with a banner. You will find the option for this in the basic settings.

Please deactivate the installment payment powered by PayPal in the tab PayPal Installment Payment Integration as soon as you have been switched over to the new procedure by PayPal.

Requirements

• The product "Instalment payment powered by PayPal" must be activated individually for each merchant, similar to PayPal Plus. You can do this here.
• Payment by instalments can currently only be offered for your customers from Germany.
• The currency is the Euro.

In addition, the customer is only shown installment payment as a payment type if various conditions are met:

• PayPal installment payment is available from a shopping cart of 99 Euro. The maximum shopping cart value is 5.000 Euro.
• The customer has a billing and delivery address in Germany.

Note: PayPal installment payment is not selectable by default in the account. This payment method is only offered to your customer in the checkout and only if the above mentioned conditions are met. Also, PayPal Installment can never be set as the default payment method.

Configuration

You can configure PayPal Installment Payment in the settings in the tab PayPal installments integration. The following options are available to you:

Activate PayPal installments (1): Activate this option if you want to make PayPal installments available in your shop.

Payment acquisition (2): This is where you specify when the payment is collected - i.e. when it is completed.

Upstream presentment on detail page (3): Use this option to customize the appearance of the article's detail page. You have three options for the design (None, Simple, Best Rate) to choose from. See the upstream presentation section for more information.

Upstream presentment on chart page (4):  At this point you can influence the display of the Upstream Presentation in the shopping cart with the same three options. See the upstream presentation section for more information.

Show logo in sidebar (5): If you activate this option, the "Installments by PayPal" logo will be included in the sidebar.

Upstream presentment in the frontend

As mentioned in the configuration section, you can advertise the installments payment method using Upstream Presentment in your shop. The corresponding settings can be set in the configuration for the detail page and the shopping cart. In addition to the option of choosing "None" to waive the Upstream-Presentment, you can choose between the options "Simple" and "Best Rate".

Simple" option

If you choose the simple option, a small hint with a link to further information is displayed on the detail or shopping cart page.

On the article detail page this is implemented as follows:

In the shopping cart the note looks like this:

Most favourable rate" option

If the option most favourable rate is selected, the customer is directly shown a representative example of instalment financing. The most favourable installment is chosen as the starting point. In this way, the customer can get a first impression of a possible financing type.

Here you can see the presentation of the option most favourable rate on the detail page:

In the shopping cart the option is displayed as follows:

Further information in the upstream presentment

In both display modes, a link with the text Information on possible rates is offered, which opens the following window:

Further information and additional examples of payment by instalments are provided here. The information on the lender in the Upstream Presentment is taken from the fields Company and Address of your shop's master data, which you can find and edit under Configuration > Basic settings > Shop Settings > Basic information.

Order process

If you have configured the integration and the customer's order meets the requirements, your customers can use installment payment as a new payment method:

When the payment method is selected, the following section is added to the shopping cart:

First examples of possible rates can be seen here. With a click on "Apply for credit" the financing can be processed and the order can be completed.
 

invoice for payment by instalments

When the customer places an order for payment by instalments, some information is added to the invoice. This includes details of the financing costs and the resulting total costs. This is reflected in the invoice as follows:

Tips and tricks

Hide "Direct to PayPal" button

If you would like to hide the PayPal Express button for certain items, you can do so with an individual solution. Here we show you a possible solution that you can implement in your shop.

This solution currently works up to and including version 2.6.5 of the PayPal extension.

Both the Bare Theme and the Responsive Theme are standard templates that should never be changed, as changes are overwritten during an update. Therefore you must always derive correctly in your own theme.

Make a backup before the execution, so that you can restore it if in doubt. Please note that these are adjustments of Shopware and therefore the content of this tutorial is not officially supported!

1. In the first step, you should create and assign a new theme, which inherits from the currently used theme in the Theme Manager.
In this example we derive the theme directly from the Responsive Theme and call it "overwritepaypal".

2. Then you create a new article free text field with the column type checkbox.
Here we have named the article text field "disablepaypal".

3. Now edit the theme.php in your previously created theme (here under /themes/frontend/overwritepaypal) and write the following into it:

protected $injectBeforePlugins = false;

It should look something like this:

class Theme extends \Shopware\Components\Theme 
{ 
... 

protected $injectBeforePlugins = false; 

... 
   } 
}

4. Then you create the file buy.tpl in the directory /frontend/detail of your previously created theme (in our example under /themes/frontend/overwritepaypal/frontend/detail/buy.tpl) with the following content

{extends file="parent:frontend/detail/buy.tpl"} 

    {block name='frontend_detail_buy_button_paypal_unified_installments'} 
        {if !($sArticle.sConfigurator && !$activeConfiguratorSelection) && $paypalUnifiedEcDetailActive && !$sArticle.disablepaypal} 
            {include file='frontend/paypal_unified/express_checkout/button_detail.tpl'} 
        {/if} 
    {/block}

Then you have to empty the cache in the Cache Module. The PayPal button is now hidden for all articles or variants with the attribute "disablepaypal".

To make sure that the PayPal Express Button is also hidden in the Offcanvas shopping cart, you have to make further adjustments in your theme.

To do this, create the file ajax_cart.tpl in the /frontend/checkout directory of your previously created theme with the following content:

{extends file="parent:frontend/checkout/ajax_cart.tpl"} 

    {block name='frontend_checkout_ajax_cart_button_container_inner_paypal_unified_ec_button'} 
       {foreach $sBasket.content as $item} 
          {if $item.additional_details.disablepaypal} 
              {assign var="disablepaypal" value="1"} 
          {/if} 
    {/foreach} 
    {if $paypalUnifiedEcOffCanvasActive && $paypalUnifiedUseInContext !== null && !$disablepaypal} 
           {include file='frontend/paypal_unified/express_checkout/button_cart.tpl' paypalEcAjaxCart = true} 
    {/if} 
{/block}

To hide the button in the shopping cart, the file cart.tpl must be created in the same directory of your theme. Fill it with the following content:

{extends file="parent:frontend/checkout/cart.tpl"}
 
    {block name='frontend_checkout_cart_table_actions_paypal_unified_ec_button'} 
       {foreach $sBasket.content as $item} 
          {if $item.additional_details.disablepaypal} 
             {assign var="disablepaypal" value="1"} 
          {/if} 
       {/foreach} 
    {if $paypalUnifiedEcOffCanvasActive && $paypalUnifiedUseInContext !== null && !$disablepaypal} 
        {include file='frontend/paypal_unified/express_checkout/button_cart.tpl' paypalEcAjaxCart = true} 
    {/if} 
{/block}

After making the changes you have to empty the cache in the Cache Module again.