Introduction

Welcome to the Intershop Commerce Management PAYONE Service Connector. The Service Connector adds PAYONE payment methods to your Intershop Commerce Management (ICM) installation.

This document provides important product information, including version information and dependencies. It also outlines the basic setup and configuration steps.

Version Information and Dependencies

This delivery and the accompanying documentation are valid for the following combinations of software versions:

The next table provides information about the cartridges included in the package. Not all of these cartridges are required.

The PAYONE Service Connector 6.x is based on the Payment API 3.4.

The source for as_responsive_payone and app_sf_responsive_payone is available here

<YOUR_REPOSITORY>/releases/com.intershop.public.source/s_payment_payone/<CONNECTOR_VERSION>/zips/s_payment_payone-zip-src-<CONNECTOR_VERSION>.zip

 Preconditions

• The PAYONE Service Connector requires an installed Intershop Commerce Management system. See version numbers above.

• Using the PAYONE Service Connector requires a dedicated payment provider contract with vendor PAYONE.
  Make sure to contact PAYONE to negotiate and sign your payment provider contract.

Supported Application Types

The PAYONE Service Connector can be used for the following application types:

Feature Overview

This section summarizes important features delivered with the PAYONE Service Connector.

Payment Methods

The PAYONE Service Connector adds the following payment methods to your Intershop Commerce Management system:

Intershop's customers can safely use Intershop Commerce Management in PCI certified environments without impacting their certification status. Furthermore, Intershop Commerce Management provides features and configurability needed to implement all the requirements of the PCI Compliance program.

Payment Management Options

The following table lists all options that are available for payment transactions.

There are certain limitations regarding the implemented capabilities, see Restricted Capabilities.

Setup

Precondition

The package is available via Intershop's Public Repository (Artifactory). The following preconditions are required:

• A set up and configured CI environment
  See Cookbook - Setup of CI Infrastructure for details.
  See Concept - Continuous Delivery Tools (valid to 7.10) for basic information about continuous integration.

• A running installation of ICM 7.10.31 or later that matches the system requirements

• Knowledge of how to add the delivered artifacts to the continuous integration environment

• Knowledge of how to deploy to a test or production environment

Setting Up the Assembly

To add the PAYONE Service Connector into your Intershop Commerce Management system, you may either incorporate the cartridge into an already existing assembly or create a new assembly inheriting from an ICM-based assembly. For details about the latter, see Recipe: Create a New Assembly Inheriting From an Existing Assembly. For incorporating the cartridge into an already existing assembly, perform the following steps:

1. Add the following in the build.gradle file of the assembly:

   build.gradle file

   ...
    
   cartridges {
           def storefrontCartridges = [
               'app_sf_responsive',
               'app_sf_responsive_cm',
               'app_sf_responsive_b2c',
               'app_sf_responsive_smb',
               'as_responsive',
               'app_sf_responsive_b2b',
               'app_sf_responsive_costcenter',
               'as_responsive_b2b',
   // this are the two cartridges, which we delivered in source code and you have to add these files to your responsive source project
               'as_responsive_payone',
               'app_sf_responsive_payone'
              ]
           include(*(storefrontCartridges.collect { project(":$it") }), in:[development, test, production])
     
   ...
    
           def payonePaymentProvider = [
               'ac_payment_payone', 
           ]
           include (*(payonePaymentProvider.collect {"com.intershop.services.payment_payone:$it"}), in: [development, test, production])    
     
           order = listFromAssembly(baseAssembly) + payonePaymentProvider 
       }
   ...
   assemblyBuild {
       database {
           inherit(<yourAssembly>)
           initCartridges = []
       }
   }
   ...
   configurations.all {
       exclude group: 'com.sun.xml.bind', module: 'jaxb-impl'
   }
   
   
   

2. Adapt the app_sf_responsive_payone/build.gradle file in the following way:

   app_sf_responsive_payone/build.gradle file

   apply plugin: 'static-cartridge'
    
   intershop
   {
          displayName = 'Adapter - Payment PAYONE - Business Extensions'
   }
    
   dependencies
   {
   //   compile project(':ac_payment_payone') --> will be replaced by
        compile group: 'com.intershop.services.payment_payone', name: 'ac_payment_payone'
   
      compile group: 'com.intershop.platform', name: 'businessobject'
   ...
      compile group: 'com.intershop.business', name: 'bc_payment'
    
   // compile group: 'com.intershop.responsive', name: 'app_sf_responsive' --> will be replaced by
      compile project(':app_sf_responsive')
     
   ...
   }
   
   

3. Adjust the file as_responsive_payone/build.gradle in a similar way:

   as_responsive_payone/build.gradle file

   ...
   dependencies {
    //   compile project(':ac_payment_payone') --> will be replaced by
        compile group: 'com.intershop.services.payment_payone', name: 'ac_payment_payone'
       compile project(':app_sf_responsive_payone')
   }
   ...

4. Insert the following lines into the file intershopBuild.version to consume the desired version (e.g. 6.1.1).
   Example:

   intershopBuild.version

   com.intershop.services.payment_payone:ac_payment_payone = 6.1.1

   For details about adding components to an assembly, see Recipe: Add Cartridges to an Assembly.

For details about managing assembly artifacts, see:

• Concept - Gradle Assembly Tools

• Reference - Gradle Assembly Tools

• Cookbook - Gradle Assembly Tools

Defining File-Based Configuration

Before deploying the new assembly to a test or production environment, you may have to adjust some file-based configurations required by the PAYONE Service Connector.

The PAYONE Service Connector requires the following settings:

This setting can be overridden within <IS_SHARE>/system/config/cartridges/ac_payment_payone.properties, see Recipe: Change Deployed File Content With Filters.

For details about adding new configuration files, see Recipe: Deploy Custom Files.

Deploying the Assembly

After creating and appropriately configuring the assembly, you must deploy it to the intended target environment.

For details about deploying an assembly see Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade). 

Configuration

Adjusting Firewall Settings

Adjust your firewall settings to allow bidirectional HTTP and HTTPS traffic between Intershop Commerce Management and:

1. api.pay1.de/post-gateway/

2. secure.pay1.de/client-api/

Make sure that the ViewPayone pipeline is accessible from the available PAYONE IP addresses only.

Applying UI-Based Configuration

The PAYONE Service Connector requires some post-deployment configurations in Organization Management and Commerce Management.

Please consult the PAYONE documentation for information on how to set up your payment portal.

Configuring the PAYONE Shop Portal

Aside from the standard PAYONE shop portal configuration that is described in the PAYONE documentation, you should also configure the TransactionStatus URL.

Explanation	Image
PAYONE Merchant Interface (PMI): https://login.pay1.de/ 1. Enter username. 2. Enter password. 3. Click Login.
4. Click Configuration. 5. Click Payment Portals. 6. Select your portal and click Edit.
7. Click Extended. 8. Enter a valid Success URL. 9. Enter a valid Back URL. 10. Enter a valid TransactionStatus URL. (Set the TransactionStatus URL to point to the ViewPayone-Notify pipeline. Assuming there is no URL rewriting, it should look similar to this: 'https://<host>:<port>/INTERSHOP/web/WFS/<site>/<locale>/-/<currency>/ViewPayone-Notify'. ) 11. Click Save.

Enabling and Configuring a Payment Service 

Check the Recipe - Enable a Payment Service in the Cookbook - Payment to get detailed instructions about enabling and configuring a payment service.

Payment-Method-Specific Settings:

You can see the required PAYONE values by going to the API-Parameter tab of your PAYONE shop portal.

File-Based Configuration

A part of the payment method configuration is not meant to be changed in the Commerce Management application and is available through server properties. These properties are read using the configuration framework and as such can be overridden for an application type. For more information on the configuration framework, check the Concept - Configuration (7.10.12 to 7.10.41-LTS) and Cookbook - Configuration.

Credit Card iFrame Styles

For the configuration of the styles the credit card payment method can be adjusted with the following properties:

¹ - <field> identifies which PAYONE credit card field is affected by the property. Supported values are cardtypes, cardnumber, cardcvc2, cardexpiremonth, cardexpireyear, e.g., payment.payone.creditcard.cardcvc2.width.

Supported Countries

For each payment method a list of supported countries can be defined. A comma-separated list of ISO 3166 ALPHA 2 country codes (also see PAYONE API documentation) is valid. The value '*' can be used if there is no restriction.

See Supported Countries and Currencies for further information about payment method specifics.

Localization

The PAYONE Service Connector provides English and German localization for payment-specific input field labels, error messages, etc.

You can find the existing localization files here: <IS.INSTANCE.SHARE>/system/cartridges/ac_payment_payone/release/localizations.

For details about localization, see:

• Concept - Localization

• Cookbook - Localization

Data Handling

The following table describes transmitted data by the PAYONE Service Connector from ICM to PAYONE during the payment process:

Limitations

Gross Price and Taxation Calculation

The PAYONE payment service requires a gross-based price and tax calculation. That is, the price type and the price display must be set to gross, and a gross-based taxation service must be enabled.

Supported Countries and Currencies

Most of the payment methods included in this package are specific for certain countries or currencies.

Restricted Capabilities

Cancel: No "cancel" capability for eps, iDEAL, PostFinance E-Finance, PostFinance Card and SOFORT Überweisung implemented.

Length of E-Mail Addresses

The length of e-mail addresses is limited to 256 characters on PAYONE side. Only 254 of these characters are usable because the at sign (@) is being replaced by escape characters.

Changelog

Version PAYONE/6.2.1

• Change: E-mail validation is adapted to accepted values by PAYONE (e-mail addresses can have up to 254 characters and are validated against RFC 5322).

Version PAYONE/6.2.0

• Change: PAYONE iDEAL no longer uses bank group selection (buyers have to select the bank on the page to which they are redirected).

Version PAYONE/6.1.1

• New Feature: PWA support for PAYONE Sofort, EPS, and iDEAL

• Change: In ICM, you could set a value for the minimum card validity in months for PAYONE Credit Card Payment Service. However, this currently has no effect.
  Therefore, this configuration option has been removed for the time being to avoid confusion.

• Fix: Configuration properties for supported countries are also read when the payment methods default is "all countries".

Version PAYONE/6.0.4

• Fix: Sensitive banking data are no longer logged in log files

• User Story: Reduce usage of error logs

• Fix: Possible NullPointerException fixed, which may occur when no invoice address is assigned while the eligible payment methods are evaluated

Version PAYONE/6.0.0

• User Story: Upgrade PAYONE Connector to Tomcat-9-based ICM (≥7.10.31)

• User Story: Enable PAYONE Credit Card for PWA storefront

• Fix: Handling 'PAID' notifications for Cash In Advance