Plugin: PayPal

Version

5.6.4 or newer

Table of contents

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:


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


        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:
         

        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.

        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.

        Was this article helpful?