Skip to content

ARVATO ONLINE RETURN CENTER

Version 2.1

This document describes the necessary steps for embedding the Arvato Online Returns Center web component in your web application.

1. TECHNOLOGY

The Frontend is a web component (see https://developer.mozilla.org/en-US/docs/Web/Web_Components for more information) bundled with all aspects like HTML, JS, CSS and fonts in a single file.

The web component is fully responsive, and the size of the web component is not configurable.

2. BROWSER SUPPORT

Browser Version
Chrome >=85
Safari >=14
Firefox >=75
Edge >=103

The widget is also embedded in the browser history, so the user is able to navigate back in the return process via browser navigation.

2.1 Samsung Internet's dark mode is not supported:

Currently, there is no way for developers to provide any custom logic from their end that can bypass Samsung Internet’s dark mode.

For now, if you want your users to use your preferred color scheme, please direct them to navigate to Settings → Labs → and Select “Use website dark theme”. This action will do one of the following:

  • If the website supports dark mode, it will be applied (Samsung Internet’s algorithm is not enabled).
  • If the website does not support dark mode, then it will be seen in light mode.

3. EMBEDDING THE WIDGET

First, create an empty landing page in your shop e.g. at /returns

The following code-snippet brings the functionality of the return-service where you want the return center to be displayed. This will automatically load our JS snippet and default CSS then render the plugin into the defined DOM node:

Test/INTG

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<html lang="de">
  <head>
    <script
      src="https://returns.cxc-intg.arvato-scs.digital/<CLIENT>/bundle.js"
      type="module"
    ></script>
  </head>

  <body>
    <arvato-returns-widget lang="de" country="DE"></arvato-returns-widget>
  </body>
</html>

Live/PROD

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<html lang="de">
  <head>
    <script
      src="https://returns.cxc.arvato-scs.digital/<CLIENT>/bundle.js"
      type="module"
    ></script>
  </head>

  <body>
    <arvato-returns-widget lang="de" country="DE"></arvato-returns-widget>
  </body>
</html>

In case of using a special font: the loading of the font must occur outside the web component. The name of the font-family must match with the predefined name.

3.1 Content Security Policy

If your platform already uses Content Security Policy (CSP), additional rules need to be added. If your platform does not use CSP, these changes are not technically necessary.

Some fonts and images are loaded by the widget via data URLs (data:). For that reason you have to adjust the Content Security Policy (CSP) of your web application to allow fonts (font-src) and images (img-src) to be loaded by data URLs.

This can be achieved by providing the corresponding HTTP header:

1
Content-Security-Policy: font-src data: ; img-src data: ;

(if already present it is enough to add the 'data:' source) or by inserting the corresponding HTML meta tags:

1
2
<meta http-equiv="Content-Security-Policy" content="font-src data:;" />
<meta http-equiv="Content-Security-Policy" content="img-src data:;" />

4. CONFIGURE CARRIER LABEL OPENING METHOD

When the user decides to print the carrier label at home and wants to open it, the ORC offers two options for opening and presenting the document to the user:

labelopenmethod description
newtab the web component will open the document in a new tab, which will trigger the browser's document viewer
event an openlabel event will be thrown, which will contain the label data alongside some meta information

The default method for opening the carrier label is opening it in a new browser tab.

You can choose the desired opening method by passing the corresponding value as an attribute to the web component.:

1
2
<!-- possible values: 'newtab' | 'event' - Default: 'newtab' -->
<arvato-returns-widget labelopenmethod="event"></arvato-returns-widget>

4.1 Open Carrier Label via Event

When you choose the opening method event an event is thrown, whenever the user expresses the intent to open the received carrier label (e.g. by clicking on the PDF icon).

The event contains the label data as a base64 encoded string alongside with some meta data:

1
2
3
4
5
6
7
8
new CustomEvent("openlabel", {
  detail: {
    rmaId: string, // the unique ID of the RMA
    mimeType: string, // following the IETF's RFC 6838 standard, e.g. 'application/pdf'
    carrier: string, // e.g. 'DHL', please contact for a list of possible values
    labelData: string, // Base64 encoded representation of the carrier label
  },
});

Usage:

1
2
3
4
5
6
instore.addEventListener("openlabel", (event) => {
  const labelData = event.detail.labelData;
  const rmaId = event.detail.rmaId;
  const carrier = event.detail.carrier;
  const mimeType = event.detail.mimeType;
});

5. SKIP INITIAL LOGIN SCREEN

The initial login screen is skippable by providing the necessary fields as GET-parameters to the widget or as parameter to the widget itself. This way, the user does not have to re-enter “orderid”, “email” etc. and is forwarded to the summary of returnable products instead.

If the orders parameters are known (e.g. in an order confirmation e-mail or in the customer’s order history) you can attach BASE64 encoded parameters to the landing page’s URL, e.g. the landing page is available via shop.tld/return:

1
2
shop.tld/return/?orderid=MTIzNTEyNDE1&
email=dGVzdEB0ZXN0LmNvbQ==

“orderid” and “email” are essential authentication factors and must be used for a prefilled link or to authenticate via landing page. There is also the zipcode as additional factor for authentication available. Once configured, the system validates that the additional factor is both provided and matches the order before allowing the customer to see the order.

5.2 Widget Parameters

The parameters for authentication can although set to the widget directly. If the parameters are provided as prefilled link and to the widget, the widget parameters will be prefered and the url parameters are ignored.

1
2
3
4
5
6
7
8
9
<arvato-returns-widget
  lang="de"
  country="DE"
  city="Berlin"
  orderid="00112233"
  zipcode="45047"
  email="maustermann@musterhaus.com"
>
</arvato-returns-widget>

In addition to the parameters for the authentication, there is also the autoscroll parameter. The default value of this parameter is true, so that the widget is displayed at the top of the window. If this behavior is not desired, set the value to false. The automatic scrolling is then switched off, as you can see in the example below:

1
<arvato-returns-widget autoscroll="false"></arvato-returns-widget>

5.3 Referrer URL

When the user aborts the return process, you can set a URL to let the browser navigate back to. The parameter is called referrerUrl and can be set in combination with either prefill setup.

1
2
3
4
5
6
<arvato-returns-widget
  referrerUrl="https://example.com/user-portal"
  lang="de"
  country="DE"
>
</arvato-returns-widget>

6. MULTI-LANGUAGE SUPPORT

The Arvato Return Center can be translated in every language. As standard we deliver German and English texts. Further texts can be implemented easily by delivering the corresponding translations.

The default-language is predefined in the web component and depends on the individual custom needs. It's possible to set the language and country individual for the shop customer by adding a property to the return-widget:

1
<arvato-returns-widget lang="de" country="DE"> </arvato-returns-widget>

The frontend itself uses the customers browser language to display the right translations, when no language or country is specified, the fallback language in case of the browser language is not available is English.

7. EVENTS

The web component is capable to throw events, so the parent component can listen to that events and handle it individually. Following events are thrown from the embedded component and can be fetched:

Event Description Payload
openinfo After click on a separate, client-specific configured button that is shown permanently at the bottom of the return process.
openlabel Has to be enabled via: the labelopenmethod attribute set to event. Gets thrown when the user expresses the intent to open the carrier label. { rmaId, mimeType, carrier, labelData }
Copyright 2025 Arvato SE