# Shopware 6 User Guide - English

## Requirements

* Shopware Version 6.4.8.x - 6.7.x.x
* Saferpay account with at least one eCommerce terminal
* Saferpay API Credentials (Customer-ID, Terminal-ID, JSON API Username and Password)
* Valid acceptance contracts for the payment methods to be used

## Installation and Activation

* Log in to the Shopware 6 backend.
* Navigate to: *Extensions*--> *My Extensions* --> *Apps* -->*Upload extension* and upload the plugin or install the plugin via your Shopware account
* Open the context menu via the "..."-button and click the button *Install*.
* Under *My extensions* --> *Apps* you can activate the plugin via the corresponding switch.

<figure><img src="/files/dkKY9X2MFejCSj6he9rG" alt=""><figcaption></figcaption></figure>

## Configuration

### General settings

* Click the button with the three dots (…) on the right side and select *Configure* to get to the plugin configuration.
* At **Operation Mode** select either "Live" or "Test", depending on which Saferpay environment you want to use (see [https://docs.saferpay.com/home/integration-guide/testing-and-go-live](https://fra01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.saferpay.com%2Fhome%2Fintegration-guide%2Ftesting-and-go-live\&data=05%7C01%7Cintegration.saferpay%40worldline.com%7C4b2ee8bc965a4cc3f7e908db56eeddd4%7Cfda9decfe89243ac9d9f1a493f9f98d0%7C0%7C0%7C638199356159277668%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C\&sdata=GLy0p%2F66vkWZw8NVDdR4jbM%2FslewaFsNl0X%2B%2FSvzeZc%3D\&reserved=0)).
* At **Merchant email addresses**, enter a comma-separated list of up to 10 email adresses that should receive a confirmation email after successful payment authorization.
* At **Payment Page-Configuration** you can specify the payment page configuration you want to use by entering the of the corresponding configuration (see [https://docs.saferpay.com/home/features/payment-page-configuration](https://fra01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.saferpay.com%2Fhome%2Ffeatures%2Fpayment-page-configuration\&data=05%7C01%7Cintegration.saferpay%40worldline.com%7C4b2ee8bc965a4cc3f7e908db56eeddd4%7Cfda9decfe89243ac9d9f1a493f9f98d0%7C0%7C0%7C638199356159277668%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C\&sdata=hywzxn%2F78JVHKCC%2B%2B6usIVlvcY5lDfJrfoioaKenncM%3D\&reserved=0)).
* The “**Save payment method**” option defines whether the payment information should be saved via Secure Card Data (for more information, see the “Save payment data” section)
* The “**Force 3-D Secure**” option is used to define whether a 3-D Secure challenge should be forced (see [https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/general-information/3d-secure#forcing-a-3ds-challenge](https://fra01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.saferpay.com%2Fhome%2Fintegration-guide%2Flicences-and-interfaces%2Fgeneral-information%2F3d-secure%23forcing-a-3ds-challenge\&data=05%7C02%7Cintegration.saferpay%40worldline.com%7C703951403ec04c2db2cd08dd0ecbbe49%7Cfda9decfe89243ac9d9f1a493f9f98d0%7C0%7C0%7C638682990439539341%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C\&sdata=KYH%2BXT64M%2FEUNdQgTv%2FSzVDdKFWZKhucOkX8U1%2BjxXo%3D\&reserved=0))
* At the configuration section **Payment API (JSON API) live credentials** you enter the data of your Saferpay live account (Customer-ID, Terminal-ID, JSON API Username, JSON API Password), which should be used if the operation mode "Live" is selected.
* At the configuration section **Payment API (JSON API) test credentials** you enter the data of your Saferpay test account (Customer-ID, Terminal-ID, JSON API Username, JSON API Password), which should be used if the operation mode "Test" is selected.
* In the “**Payment capture behavior**” configuration block, you can configure individually for each Saferpay payment method that supports manual payment capture whether the payment should be captured automatically (auto-capturing) or not (for more information, see the “Manual payment capture” section).

<figure><img src="/files/hM1KTImPyhIuVDRYAqMA" alt=""><figcaption></figcaption></figure>

### Saferpay Fields <a href="#zahlungsdaten-speichern" id="zahlungsdaten-speichern"></a>

Instead of redirecting the user to the Saferpay payment page to enter payment information during the payment process, [Saferpay Fields](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/saferpay-fields) allows payment information (e.g. credit card details) to be entered directly in the final checkout step.

This can be configured individually for each payment method. Please note that integration only works with payment methods supported by Saferpay; otherwise, payment via the payment page will be used as a fallback.

<figure><img src="/files/4IYNaeQ9aKkkChc08oPd" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/bKc0Jmt2uxjeWQMF1zkZ" alt=""><figcaption></figcaption></figure>

### Iframe integration

Instead of redirecting the user to Saferpay, payment processing can be embedded directly into the Shopware checkout process via [iframe integration](https://docs.saferpay.com/home/integration-guide/general-information/iframe-integration-and-css).

Iframe integration is supported for both Saferpay Fields and the payment page.

<figure><img src="/files/Ux9FCK7vav3tONP5Xldb" alt=""><figcaption></figcaption></figure>

### Save payment methods <a href="#zahlungsdaten-speichern" id="zahlungsdaten-speichern"></a>

Payment means can be saved via Secure Card Data (see <https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/secure-card-data>). The saved payment methods can be viewed and deleted in the Shopware customer account:

<figure><img src="/files/OqgIR0gokGWpgvQlE9RN" alt=""><figcaption></figcaption></figure>

If you use Saferpay Fields, customers can use the stored payment method(s) for their next purchase:

<figure><img src="/files/qoC8Gkq0418xXszqAcDd" alt=""><figcaption></figcaption></figure>

### Add payment methods

After you have made the general settings for the Saferpay plugin, you need to configure the payment methods you want to support:

* Go to *Settings--> Payment methods* in the Shopware 6 admin area.
* All payment methods supported by the Saferpay plugin will now appear here.
* Open the details of the payment methods you want to use.
* Activate the payment methods
* In the section **Custom fields** in the tab **Saferpay** you can use various fields to configure the payment method.
* At **Payment means** you can explicitly set which means of payment should be available on the Saferpay payment page when this payment type is selected in the storefront. Please note that the payment method must also be activated in the Saferpay terminal. If you leave this field empty, all payment methods available in the Saferpay terminal will be offered.
* If 3D-Secure ([https://docs.saferpay.com/home/integration-guide/3d-secure](https://fra01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.saferpay.com%2Fhome%2Fintegration-guide%2F3d-secure\&data=05%7C01%7Cluca.schweizer%40worldline.com%7C1d5e3c65cd304dd2ca2708db5c425329%7Cfda9decfe89243ac9d9f1a493f9f98d0%7C0%7C0%7C638205212162542061%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C\&sdata=q7IDjRTwWH%2FsiGpCur%2BBEB2MT6NC43AE7MfezJrO0VU%3D\&reserved=0)) is supported by the payment methods, you can set at **Liability shift behavior** whether the payment should be aborted if no liability shift is granted or whether the payment should be accepted anyway.
* **Storefront integration:** Instead of redirecting the user to the Saferpay *Payment Page* during the payment process to enter the payment information, [*Saferpay Fields*](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/saferpay-fields) allows the payment information to be entered directly in the final checkout step. Please note that *Saferpay Fields* only works with card payment methods, otherwise the payment is made via the payment page as a fallback. In addition, *Saferpay Fields* must be included in your Saferpay account/contract, otherwise only the payment page can be used.
* **Redirect URL handling**: description coming soon.
* At **Wallets** you can set which wallets should be available on the Saferpay Payment Page when this payment type is selected in the storefront. Again, the payment type must be enabled on the Saferpay terminal. If you leave this fields empty, no wallets will be offered
* Note that all configurations can be configured individually for each Shopware language. By default, all fields are empty for all NON-standard languages. If a field is empty in a NON-standard language, the value is taken from the standard language.

<figure><img src="/files/zJvGp6nrs56z9sfPzxX1" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/sHSEeeyivlzflllxXE3I" alt=""><figcaption></figcaption></figure>

### Setting up the Checkout Page

Last but not least, the payment methods must be assigned to the sales channels so that customers can select them in the checkout process. To do this, proceed as follows:

* Navigate to *Sales Channels* in the Shopware 6 admin area.
* Select the sales channel for which you want to activate the payment methods.
* In the section *Payment and shipping,* assign the Saferpay payment methods you want to use for this sales channel.

After assigning the payment methods to the sales channels, the corresponding Saferpay payment methods are available in the storefront.

<figure><img src="/files/qFgso6kEgm0fkbAiT67w" alt=""><figcaption></figcaption></figure>

## Refunds

To perform a refund via Saferpay, you can simply select the relevant items to be refunded in the Shopware administration. To do this, click on the "Refund via Saferpay" button (German: "Über Saferpay rückerstatten"). Please note that this button is only visible if the order was paid via Saferpay and has the payment status "Paid".

<figure><img src="/files/0oka7hesLAAoVVPXoTAQ" alt=""><figcaption></figcaption></figure>

In an overlay, you have the option of adjusting the quantities of the selected items that are to be refunded. Once you have made the desired adjustments, click on the "Refund" button (German: "Rückerstatten"). This will refund the corresponding amount via the payment method selected by the customer.

<figure><img src="/files/274wozDCVPfin1Adj4Ee" alt=""><figcaption></figcaption></figure>

After a successful refund, the payment status is updated to "Refunded" or "Partially refunded". You can also view the refund and the associated transaction ID in the new "Saferpay refunds" tab.

<figure><img src="/files/huPtzkzpJMgZNh2ltmWi" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Please note that currently only one refund can be issued per order. In addition, there is currently no automatic stock calculation. This must be done manually (see [https://docs.shopware.com/de/shopware-6-de/bestellungen/retouren-management](https://fra01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.shopware.com%2Fde%2Fshopware-6-de%2Fbestellungen%2Fretouren-management\&data=05%7C02%7Cintegration.saferpay%40worldline.com%7Cd4485ec1828e4003314d08dc6b6a0621%7Cfda9decfe89243ac9d9f1a493f9f98d0%7C0%7C0%7C638503350322048962%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C\&sdata=6IwN3yJVsKJlmIGO24Knq0%2F6UMQgjx3hhpermwHT%2B7E%3D\&reserved=0)).
{% endhint %}

Since plugin versions 1.8.0, 2.6.0 and 3.1.0, it has been possible to configure whether the order number or the order ID should be transmitted to Saferpay as a reference for refunds:

<figure><img src="/files/HOKQiZyVE3ETSEOgG3EV" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.saferpay.com/home/master/web-shop-plug-ins/shopware-6/shopware-6-user-guide-english.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.