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 pay upon invoice.

Installation

This extension can be found in our Shopware Store, the easiest way to find a specific plugin is the search-bar. Complete the order process and login to the backend of your store. Navigate to Configuration > Plugin manager > My purchases. You need to login and click the refresh button. Your new extension is now listed and can be installed. After installing the extension go to the menu entry installed and refresh. Activate the extension. Finally delete the cache under Settings > Cache/Performance > Clear Shop Cache and refresh the backend.

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)
• PayPal Pay Upon Invoice Integration
• PayPal Advanced Credit Debit Card Integration
   

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.

PayPal Merchant ID (3): The ID is necessary for the PayPal Pay Upon Invoice Integration and PayPal Advanced Credit Debit Card Integration. You can find the exact ID in your account.

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

Authorise (5): Here you will be redirected to PayPal's registration page to automatically receive Client ID, Client Secret and PayPal Merchant ID.

Test API settings (6): 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.

Register webhook (47: 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.

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:

Payment acquisition (1): 

• (CAPTURE) Complete payment immediately: Payment is automatically collected immediately
• (AUTHORIZE) Delayed payment collection: Payment is only authorized . The collection must be made separately.

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.

Order status for failed transactions (8): Here you can select which order status the order should have after a failed transaction.

Payment status for failed transactions (9): Here you can select which payment status the order should have after a failed transaction.

Oder number prefix (10): 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".

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.

The express function does not apply to ESD products. These can only be purchased with a customer 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:

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

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

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

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

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

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

Button shape (7): 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 (8): 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 (9): 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 (10): 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 pay upon invoice.

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 pay upon 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 pay upon invoice 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.

The PayPal bank details are automatically added via the PayPal_Unified_Instructions_Content element. Therefore no adjustment by you is necessary. Your customers will automatically receive the correct PayPal bank details after completing the order and when the invoice is sent.

PayPal Installments

In the tab PayPal Installments you can activate the banner for the installment payment. As soon as the banner is activated, the installment payment will be promoted via PayPal. This works only with your Live Client-ID (not with the Sandbox Client-ID). The banner will be displayed in different areas of the frontend, e.g. on the item detail page or in the shopping cart. 

Frontend view

It is necessary to accept the cookies of the "Technically Required" category in order to show the PayPal Installment banner. If the cookies were accepted in the past and PayPal Installment was activated later, the cookies must be accepted again so that the cookies for PayPal Installment are also set.

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.

PayPal Pay Upon Invoice Integration

Please note that your PayPal account must be authorised for this payment method to be available to your customers. You can authorise your account in the PayPal settings module.

You can use this function to activate PayPal Pay Upon Invoice for your shop.

Please check under Configuration > Payment methods that the payment method for PayPal pay upon invoice with the name SwagPaymentPayPalUnifiedPayUponInvoice is active if you want to offer purchase on account. Furthermore, under Configuration > Shipping costs > Payment methods, it is necessary to add the purchase on account as Allowed for all shipping methods for which the shop customer can pay by PayPal Pay Upon Invoice.

PayPal Advanced Credit Debit Card Integration

Please note that your PayPal account must be authorised for this payment method to be available to your customers. You can authorise your account in the PayPal settings module.

Here you can activate the advanced credit and debit card integration.

Frontend view

These two payment methods are now available in the frontend.

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.

Additional description from version 2.8.1

Under Configuration > Payment Methods you can add, edit, activate or deactivate the payment methods used in Shopware. More information about this option can be found here.

For PayPal there is an additional description for the frontend in the tab General, which contains Javascript with a link.

In version 2.8.1 we changed the text in the additional description for the PayPal payment method, because originally there was a JavaScript (for forwarding to PayPal) in it. Since this description text would be inserted by default in the order confirmation mail, this could lead to the fact that the confirmation mail was marked by some mail providers as spam/uncertainty and thus did not reach the end customer.

This JavaScript part has now been replaced in version 2.8.1 But to avoid overwriting your own texts, the text will remain when updating the plugin. Only if you completely reinstall the plugin, the new text will be used.

If you don't reinstall the plugin and simply run the update, you can also change the additional description manually. Add the following text to the additional description:

<!-- PayPal Logo --><a onclick="window.open(this.href, 'olcwhatispaypal','toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=yes, resizable=yes, width=400, height=500'); return false;" href="https://www.paypal.com/de/cgi-bin/webscr?cmd=xpt/cps/popup/OLCWhatIsPayPal-outside" target="_blank"><img src="
{link file='frontend/_public/src/img/sidebar-paypal-generic.png' fullPath}
" alt="Logo 'PayPal empfohlen'"></a><br><!-- PayPal Logo -->Bezahlung per PayPal - einfach, schnell und sicher.

Read invoice data

If an invoice purchase is made through PayPal, the associated invoice data is stored in the table swag_payment_paypal_unified_payment_instruction.
To make this information easier to read, it is also displayed in the backend. You can find it under Customers > Orders in the respective order details. There it is stored in the Communication tab in the Internal Communication field.

The JSON string looks something like this:

{"jsonDescription":"Pay Upon Invoice Payment Instructions","orderNumber":"20030","bankName":"Deutsche Bank","accountHolder":"PayPal Europe","iban":"DE12345678901234567890","bic":"DEUTABCDEFG","amount":"26.97","dueDate":"2021-02-19","reference":"8L723597GH9483894"}