Plugin: PayPal

Version

5.5.0 or newer

Table of contents

General

A quick word before you start: As you have probably already noticed, there were some changes made to the composition of the PayPal plugin. The PayPal plugin you most likely know well, has been renamed to "PayPal Express". It will still provide all the basic PayPal features. However there is also a completely new plugin, integrating all of the PayPal payment options available into one plugin. It is simply called "PayPal" and here is how to use it.

We are super excited to announce, that for the first time we provide you with a singular approach that enables most of the popular online payment possibilities you have gotten to know as different iterations of PayPal in your very own shop. Importantly, we only changed the scope of the plugin. Of course PayPal remains a "priceless" asset, signifying it will be usable across all of your shops - needless to say: free of charge.

Installation

Installing the plugin is easier than ever. Just as the other plugins available in Shopware, you can do so by calling on the plugin manager. You will find the manager in the backend, via Configuration > Plugin manager. Simply select the Plugin labeled "PayPal", hit install and follow the instructions. If you have been using PayPal before, don't worry about your old plugins, they will be dealt with later (see the chapter on compatibility for more information). After successfully installing the PayPal plugin, you will find the two respective modules in Customers > Payments > PayPal.

Compatibility with older plugin versions

Using the all new PayPal plugin, you might wonder, what actually is going to happen to all the orders taken with PayPal in your shop before that. Of course, those will still be there after the installation. You will know them by the attached tag: "old". When you are able to find your previous orders in Customers > Payments > PayPal > Orders, you have successfully updated and migrated your PayPal plugin. You may now deinstall the older PayPal plugins freely.

Please be aware that you may encounter warnings and notifications on possible compatibility issues. This is because the new PayPal plugin introduces information on e.g. the transaction history which were not available in the older data set at all, but therefore creating slight incongruencies in the data base.

If you plan on migrating your previous PayPal orders, that is why you should make a backup and to be really sure: evaluate the migration process on a test system beforehand. Just in case anything happens, that is how you lower the risk of loosing huge chunks of your order history permanently.

Although you will be able to refund orders that were migrated to your new environment, you should expect not to be able to fully make use of the new payment history. Available will only be the currents status.

The current plugin version only supports transactions categorized as "sale". This parallels the previously know option "terminate payment immediately (sale)".

PayPal is not compatible with any of the old PayPal plugins. You cannot use the new PayPal alongside with its older iterations: "PayPal", "PayPal Plus" or "PayPal Installments". It is thus advised to at least deinstall older PayPal plugins and after successfully migrating order data from old to new plugin, remove the old plugins completely. Before finally erasing the old plugins, make sure you have all the data you would like to save, otherwise data loss is to be expected.

First Start

After you have successfully installed and integrated the new PayPal plugin, you can get going with your shop and PayPal together in a whole new and seamlessly integrated way. But first you have got to configure the plugin. Go to Customers > Payments > PayPal > Settings. This is where you can set up and configure your shop's PayPal integration.

Overview

The window comprises of four tabs, representing the four integral parts of the new plugin:

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

The very first tab, "General settings", differs slightly from the other three. In this tab you are presented with a couple of global options and settings to tweak with. In addition to that there are some options that don't have a global effect and to a degree resemble functionalities an experienced Shopware user might be familiar with, namely the classic PayPal payment functions.

Activation and shop selection

  • Shop selection (1): All of these settings can be applied specifically within each individual shop. This enables you to decide for different cases, shops or subshops, whether you want to provide certain features or not. This might be particularly helpful if, for example, certain features are not available in your jurisdiction.
  • Activate in this shop (2): This is a global setting, de-/activating PayPal payments in your shop, without messing with your plugin settings. Deactivating PayPal this way is thus an uncomplicated, easy-to-do process.

Configuring the API's settings

This is where you fill in your payment credentials.

  • Client ID (1): Put your shop's PayPal REST ID in here. Using this ID, the plugin will automatically register with PayPal.
  • Client secret (2): Put your shop's PayPal REST password in here. Using this ID, the plugin will automatically register with PayPal.
  • Activate Sandbox (3): Tick off this box, if you want to test the PayPal plugin's settings in your own shop. This way you can experiment in a safe test environment, where no real transactions are conducted. Note that you will need separate login credentials in order to use the sandbox.
  • Register webhook (4): This is where you can manually kick off registration of the webhook. More information on webhooks can be found in the section "Configuring webhooks".
  • validate API settings (5): This is where you check whether your API settings are correct. You will be notified of the result via growl message at the top right corner of your screen.

Configuring webhooks

It is crucial to configure a webhook, when you plan on using the PayPal plugin. Otherwise it won't be possible to change back recurring payment status changes. This is the case if e.g. a transaction was initally labeled "reserved", but is going to be set to "completed" in a foreseeable future. Normally the webhook is set up and transferred automatically. If, for some reason that does not work or you can think of other valid grounds for messing around with this, you can set up the webhook manually. To do so, please visit developer.paypal.com, head to your dashboard and look for My Apps and Credentials. Choose an applicable app from REST API apps and you will be taken to the webhook section. Click add webhook to - you guessed it - finally add the webhook.

Note that the webhook URL has to resemble the following format: 'https://example.com/PaypalUnifiedWebhook/execute'

This is a so called base domain potentially containing a shop extension. It resembles the notify URL, but has the term "webhook" included. Be sure to choose "all events" in the setting "event types" also.

That's it. Now that you're done configuring the webhook, you can begin and make full use of the PayPal plugin.

The PayPal you used to know

Obviously the new PayPal plugin provides you with all of the features already known from classic PayPal to integrate into your shop. Customers will now able to pay using their PayPal account and of course its buyer protection rule set. How to set up the basic PayPal functions will be explained hereunder.

Note that some of the options presented in the currently active tab have a global effect and will be affecting Shopware, even if only PayPal Plus or the Express Integration are active. PayPal is the basis for PayPal Plus and Paypal Express Checkout, so you should keep this fact in mind when altering the following settings.

Configuration

The settings described here can be found in the section "behaviour" on the tab "General settings", briefly introduced above. These settings affect all PayPal functionalities, PayPal Plus and the Express Checkout as well.

  • Brand name on PayPal page (1): Fill in your shop's name here. It will be complementary displayed below your shop's logo on the PayPal payment page. In addition to that it will be used in the cancel button's caption: "Cancel and back to 'YOUR SHOP'."
  • In-context mode (2): Activate this if you don't want the PayPal payment to take place on a blank page, but instead keeping your shop visible in the background. You'll find more information on that in the section "In-context mode".
  • PayPal landingpage (3): Choose whether the PayPal landingpage will display the registration form or a login screen.
    Note that the in-context mode only works for customers not yet logged in to your shop. Additionally PayPal Plus has to be active at the same time!
  • Logo in sidebar (4): If active, a PayPal logo will be displayed on the lefthand sidebar in your storefront.
  • Send order number to PayPal (5): If active, order numbers will be sent to PayPal alongside every order taken through the service.
  • Order number prefix (6): Only active if the previous option is true and order numbers already are transmitted. This furthermore enables you to define custom prefixes to go along with the order number. For a prefix it is possible to attach any kind of string, spaces are excluded from the rule. Commonly your shop's name would fit nicely here.
  • Free Returns (7): Set active to advertise the possibility of free returns powered by PayPal. This will also display an additional banner in your shop's sidebar.

Error handling

The PayPal plugin comes with handy possibilities on the topic of issue logging. Activate those in the section "error handling" on the tab "General settings".

There are two options available in this section.

  • Display errors (1): Activate, if you would generally like to issue and display error messages.
  • Logging (2): This option wields influence on the severity of error logging. There are three different quality levels available. Choose "normal" to only log errors. "extended" will include normal messages as well, the option "all" will also log standard events and warnings.

You will find the log files in your shop's folder under ".../var/log". For this plugin you will find the log entries in a file similarly named as this: "plugin_production-". Every day another logfile is created.

Appearance in your storefront

If you have installed and activated PayPal, customers will be presented with PayPal as a means of payment at the end of the order process.

The order confirmation page should appear as normal, after giving the approval customers are redirected to a PayPal page, where they will have to log in with PayPal to complete the transaction.

After that PayPal will confirm and finish the order and after the send the customer back to your shop. This is the page that will be displayed at that moment:

Here the order's transaction number, the one PayPal uses to track orders, can be found here. In conjunction with this number, the order will be displayed in the overview window in your backend. Look for the transaction number to identify orders and monitor their status, which at this point in time should read "Completed".

In-context mode

As already hinted at above, you may activate a different look for PayPal orders in your shop. The so called in-context mode doesn't refer the user to another page, but instead keeps your shop visible right below the checkout window. This way customer's won't ever really "leave" your shop during checkout with PayPal. Using the in-context mode makes the PayPal checkout take place in a windowed mode, keeping your shop visible, as a darkened shadow in the background.

The order confirmation page has also changed slightly. The button formerly stating "liable for payment order" is replaced by one simply labeled as PayPal.

Please bear in mind that you cannot use the in-context mode as long as the PayPal Plus part of the plugin is active! It however works fine with the "PayPal Express Checkout integration". Although that also means, a customer placing an order without logging in, will encounterthe in-context mode, but may never see it again, even if he comes back regularly, logging in using his valid account credentials and you are using PayPal Plus.

Order overview within the plugin

The PayPal plugin has, in addition to the order module that comes with "vanilla" Shopware, an own overview. Displayed here are all the orders placed using the plugin. You may find the overview by heading towards Customers > Payments > PayPal > Orders.

Within the plugin you will find the order overview. The overview contains all orders that were made utilizing PayPal services. It also holds information about the kind of PayPal service (Express, Plus, Installments) that has been used for the transaction. On the righthand side of the module window, the corresponding transaction information at that point provided by PayPal, are displayed. This section is structured again into three parts: "Orders", "PayPal transaction" and "Payment"

Express Checkout

The PayPal plugin combines known functionalities from all former PayPal plugins in just one bundle. Of course the PayPal Express Checkout is one of those. Using this particular payment method, customers are able to make a purchase in your shop without the need for a proper registration beforehand.

Configuration

Configuring the PayPal Express Checkout is easy and takes place in the PayPal settings page. Just switch tabs to "PayPal Express Checkout integration" and alter the following parameters to your liking.

  • Payment acquisition (1): Determine when payments are collected and the transaction is closed.
  • "Pay now" on detail page (2): Determine whether the PayPal Express Checkout button is displayed on the item details page.
  • "Pay now" on cart (3): Determine whether the PayPal Express Checkout button is displayed on the login page.
  • "Pay now" on login page (4): Determine whether the PayPal Express Checkout button is displayed on the login page.
  • Button color (5): The PayPal Express Checkout button comes in four different colour styles. Choose one of the available options: gold, blue, silver, black.
  • Button shape (6): Customize the shape of the Express Checkout button. Available options are "round" (rounded corners) or "rectangular" (sharp pointed corners).
  • Button size (7): Determine the size of the Express Checkout button. Available options are small, medium and large and responsive (actually the smallest one in most appearances).
  • Submit cart (8): Choose whether the exact positions of a purchase in your shop are transmitted to PayPal when using the service for means of payment. If you deactivate this option, PayPal won't be informed about the particular items puchased in the transaction, and solely receives the sum total of that order.

Appearance in the frontend

The order process using PayPal Express Checkout resembles the previously discussed process using classic PayPal. The main difference between both is that customers don't have to register and maintain an account on your shop page. Via the Express Checkout button customers can simply purchase items without having to register or login with your shop in the first place. Registration and login in your shop are not necessary as all relevant and required data is enquired by PayPal on their own page. However Shopware will automatically track this customer as "Accountless". The Express Checkout button can be displayed either in the shopping cart, on the login page or on the item details page:

"PayPal Checkout button" in the shopping cart:

"PayPal Checkout button" on login page:

"PayPal Checkout button" on detail page:

PayPal Plus

PayPal is the first available plugin for Shopware that includes four of the most popular payment methods of German customers in just one place. Besides standard PayPal transactions, you may now - with the help of PayPal - offer debit entries, credit card payment and invoicing.

Requirements

  • It is necessary to activate and unlock PayPal Plus functionalities for each individual retailer. If you haven't already, you can request access here

Please note that invoicing via PayPal has to be enabled separately, as well. PayPal Plus at the moment is only available for customers from Germany.

Configuration

Configuring the PayPal Plus functionalities is easily done via the PayPal settings page, and the tab "PayPal Plus integration".

 

  • Activate PayPal Plus (1): Activate or deactivate the PayPal Plus integration of the plugin.
  • Payment acquisition (2): Determine when payments are collected and the transaction process is completed.
  • Restyle payment selection (3): Choose whether you would like to integrate a payment selection page that either runs on PayPal or Shopware defaults. Differences and integral parts of this feature are described in the section Appearance in the frontend
  • Display other payment methods in iframe (4): Choose whether third party payment solutions should rather stay apart from or be shown on the payment wall iframe.
  • Overwrite payment method name (5): Change the caption of a single or several payment issues.
  • Complete payment method description (6): Alter the description included with the plugin.

Please bear in mind that, if the PayPal Plus integration is active, the in-context mode only works for users not registered and logged in to your shop (PayPal Express Checkout)!

Appearance in the frontend

The order process basically stays the same when using the new PayPal plugin. The additional payment methods PayPal, PayPal debit advice, PayPal credit card and PayPal invoicing are displayed in an iframe within the payment selection during checkout. This is, of course assuming the customer has chosen PayPal as a possible or even as his preferred payment method.

If a customer has already chosen PayPal as an active payment method, those options will be displayed in the iframe during checkout.

Beware: If PayPal Plus is active, the in-context mode is NOT available during checkout for known users of your shop. However, for new users (not logged in), PayPal Express Checkout will still work in-context.

Appearance of payment selection

We already hit this topic in the above section Configuration, the appearance of the PayPal Plus payment options can be adjusted in the settings module of the PayPal plugin. It is even possible to extend the iframe's style onto all other payment methods available in the selection. Do that by activating the option Restyle payment selection (1). The payment selection will then look like this:

Note that this has yet another effect. Activating the above mentioned option reveals an additional configuration option: Display other payments methods in iframe (2) Activating this option generally opens the PayPal iframe for the inclusion of all the other payment methods available in Shopware. However you will have to enable the transition into the iframe individually for each payment method. Head to Settings > Payment methods and check the box Display in PayPal Plus iframe (1) found in the tab Free text fields in order to include that individual payment method into the PayPal iframe. Repeat the preceding steps to include other payment methods as well.

There are payment methods that require additional information during checkout, e.g. SEPA debit credentials. In this case refrain from adding the method to the PayPal iframe, as the additionally required fields won't show in the iframe properly!

PayPal installments

The PayPal plugin includes the payment option "Installments powered by PayPal". This option enables you to offer the possibility of payment by individual installments, ideal for particularly large or costly orders.

Requirements

Just as before while configuring PayPal Plus, you will have to register "installments powered by PayPal" with PayPal development as described here.

 

Note that installments are exclusively available for customers from Germany!

To successfully use PayPal installments, there are some requirements to be fullfilled beforehand:

  • The total order value has to lie between 99€ and 5000€. A notification will be displayed on the details page of an item, stating the status of eligibility for installments.
  • Customers are registered with a German invoice adress as well as delivery adress.
  • The transaction's currency is EURO.
  • The transaction includes only the delivery of physical goods. Immaterial goods such as licences (e.g. Software, DLC and so on) are excluded from "installments powered by PayPal"!

To be sure: PayPal installments cannot be selected as standard payment method in the customer account. Customers are presented with "installments powered by PayPal" only during checkout if all requirements are fulfilled. You cannot select installments as a preset payment method in the backend, neither.

Configuration

PayPal installments is configured in the tab "PayPal installments integration" found in Customers > Payment methods > PayPal > Settings.

  • Activate PayPal installments (1): Globally (de-)activate installments.
  • Payment (2): Define when payments are collected and the transaction is completed.
  • Upstream-Presentment on detail page (3): Use this option to customize the items' details pages. There are three different designs available. More on that in the next section Upstream presentment.
  • Upstream-Presentment in shopping cart (4): Use this option to customize the appearance of the shopping cart. There are three different designs available. More on that in the next section Upstream presentment.
  • Display logo in sidebar (5): Activate to display the "installments powered by PayPal" logo in your shop's sidebar.

 

Upstream presentment in the frontend

In the configuration section you have already encountered the upstream presentment, which is used to advertise the payment via installments on your shop's detail pages and shopping cart.

In this section we will show you how the different upstream presentment options look in your shop.

You can select "none" here and no upstream presentment will be displayed. However there are two other options that affect the style of the presentment in your shop. These are "Simple" and "Cheapest rate".

Option 1: Simple

Choosing this option individually for either the details page and/or the shopping cart, will display a small hint including a link with further information on installments.

This is how this upstream presentment will look in the details page:

This is how this upstream presentment will look on the shopping cart:

Option 2: Cheapest rate

Choosing this option adds more PayPal content to your shop. There will be representative example of a payment with installments displayed during checkout. As before you can individually enable this for the shopping cart as well as for the detail pages. The example presented employs the option "Cheapest rate". This way your customers will have a snapshot view on a possibly attractive payment solution.

This is how this upstream presentment will look in the shopping cart:

This is how this upstream presentment will look on the details page:

There is an exemption in the appearance of the upstream presentment using the option "Cheapest rate". In case you want to offer 0%-financing, the upstream presentment will resemble the "Simple" option.

Further information in the upstream presentment

Whatever kind of upstream presentment you decide to use in your shop, there will be a link included labelled: "Information on possible installments". Clicking this link will open the following window:

On this page, powered by PayPal, there are more examples for possible payments using installments. The lender as displayed here, is derived from the basic information of your shop. It is made up from the data you have put into "firm" and "adress". You can edit those by navigating to Configuration > Basic settings > Shop settings > Basic information.

Order process

By the time you have configured the integration of PayPal installments, and customers fulfill the requirements as well, they will be able to use PayPal installments for payment in your shop. The payment selection page will then be supplemented with another paragraph:

Here possible examples for payment with installments can be looked up. Clicking "request payment with installments" will engage the financing and conclude the order.

Invoicing installments

If an order is taken using installments payment, some information are added to the usual invoice template. These information are financing costs and total additional costs of installments. Here is an example.