Public Release Note - PAYONE Service Connector 6

1 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.

1.1 Version Information and Dependencies

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

IntershopPAYONE Service Connector
7.10.31.x+ (Tomcat 9)6.0.0
PAYONE Connector version 6.0.0 features the same functionality as PAYONE Connector 5.4.8 to facilitate migration from ICM 7.10.30 - to 7.10.31+.

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

CartridgeDescriptionRequired
ac_payment_payoneIncludes all base functionality and business logic which is used.(tick)
as_responsive_payone

Enables the PAYONE payment connector for the following application types:

  • intershop.B2CResponsive
  • intershop.SMBResponsive

The cartridge is optional, can be downloaded separately from Intershop Product Calendar and may be included if the project uses the responsive starter store. Unzip the file to your multi-project folder next to your responsive source files. It could be skipped if the custom project does not support these application types or PAYONE is not required in these application types.

(error)
app_sf_responsive_payone

Includes some additional functionality which is relevant for the responsive storefront reference application only, e.g., the integration of the hosted payment pages of the credit card.

The cartridge is optional, can be downloaded separately from Intershop Product Calendar and may be included in case the project is based on the responsive storefront reference application. Unzip the file to your multi-project folder next to your responsive source files. The referenced cartridge app_sf_responsive may be renamed in the project and has to be referenced in the build.gradle file with the customized naming again.

(error)

The PAYONE Service Connector 6.0.+ is based on the Payment API 2.8.

The sources for as_responsive_payone and app_sf_responsive_payone can be downloaded here (use your repository login and password for authorization):

https://repository.intershop.de//releases/com.intershop.public.source/s_payment_payone/6.0.0/zips/s_payment_payone-zip-src-6.0.0.zip

1.2  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.

1.3 Supported Application Types

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

Application TypeApplication Type IDDescription
B2C WebShopintershop.B2CWebShopBusiness to Consumer Channel
SMB WebShopintershop.SMBWebShop

Business to Business Channel

Warning

Only applicable if the order approval is disabled.

Progressive Web App intershop.REST

Progressive Web App endpoint for B2C/B2B channel

Supported payment methods:

  • Credit Card
  • PayPal
  • paydirekt
  • Invoice
  • Cash In Advance
  • PostFinance E-Finance
  • PostFinance Card

2 Feature Overview

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

2.1 Payment Methods

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

Planned ReleasePayment Method TypeDetails
5.1PayPalPayPal
Online PaymentSOFORT Überweisung
5.2Credit CardCredit Card payment with:
  • Visa
  • Mastercard
  • American Express
  • Carte Bleue
  • Diners Club
  • Discover
  • JCB
  • Maestro International

This payment method uses Payone iFrames to enable compliance with PCI-DSS. It supports 3DS version 1.0 and 2.0.

Account Based PaymentCash in Advance
Direct Debit
Invoice
Online PaymentiDEAL
PostFinance E-Finance
eps
5.3Online PaymentPostFinance Card
5.4Online Paymentgiropay
5.4Account Based Paymentpaydirekt

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.

2.2 Payment Management Options

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

OperationDescription
CaptureRequest for settling the payment. This action is only available if the corresponding payment method's Capture Mode is set to manual.
CancelRequest for abandoning a payment settlement. This action is only available if the corresponding payment method's Capture Mode is set to manual.
RefundOption to return (parts of) the capture amount.

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

3 Setup


Note

Managing and deploying the PAYONE Service Connector requires a continuous integration environment set up and configuration as described in Cookbook - Setup CI Infrastructure.

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 CI Infrastructure for details.
    See Concept - Continuous Delivery Tools 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:

    intershopBuild.version
    com.intershop.services.payment_payone:ac_payment_payone = 6.0.0


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

Note

Please note that the adapter cartridge will only work with a storefront that is based on the inSPIRED demo shop. It will not work in the PrimeTech demo shop.

For details about managing assembly artifacts, see:

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:

PropertyDescriptionValue
intershop.payment.Payone_Cash_In_Advance.currenciesDefines which currencies are configurable for PAYONE Cash in Advance. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_CreditCard.currenciesDefines which currencies are configurable for PAYONE Credit Card. Default: all.comma-separated list, e.g., EUR, USD
intershop.payment.Payone_DirectDebit.currenciesDefines which currencies are configurable for PAYONE Direct Debit. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_Eps.currenciesDefines which currencies are configurable for PAYONE eps. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_IDeal.currenciesDefines which currencies are configurable for PAYONE iDEAL. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_Invoice.currenciesDefines which currencies are configurable for PAYONE Invoice. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_PayPal.currenciesDefines which currencies are configurable for PAYONE PayPal. Default: all.comma-separated list, e.g., EUR, USD
intershop.payment.Payone_PostFinance_EFinance.currenciesDefines which currencies are configurable for PAYONE PostFinance E-Finance. Default: CHF.comma-separated list, e.g., CHF
intershop.payment.Payone_PostFinance_Card.currenciesDefines which currencies are configurable for PAYONE PostFinance Card. Default: EUR & CHF.comma-separated list, e.g., EUR, CHF
intershop.payment.Payone_Sofort.currenciesDefines which currencies are configurable for PAYONE SOFORT Überweisung. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_Giropay.currenciesDefines which currencies are configurable for PAYONE giropay. Default: EUR.comma-separated list, e.g., EUR
intershop.payment.Payone_Paydirekt.currenciesDefines which currencies are configurable for PAYONE paydirekt. Default: EUR.comma-separated list, e.g., EUR

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)

Note

The PAYONE Service Connector requires additional post-deployment configuration steps. For details, refer to Configuration.

4 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.

ExplanationImage

PAYONE Merchant Interface: 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:
NameDescription
Merchant-IDYour merchant account's merchant ID as provided by PAYONE.
Portal-IDYour merchant account's portal ID as provided by PAYONE.
Sub-Account-IDYour merchant account's sub account ID as provided by PAYONE.
Portal-KeyYour merchant account's portal key as provided by PAYONE (unencrypted).
EnvironmentSwitch between productive and test environment (Test is set as default).
Select Live on the live system. Keep Test for the test environment.
Base URLPAYONE Gateway URL.
CaptureThis describes the capture mode (Manual, Auto). If Timed is used you must set a Capture Time in Hours.
For all online payment methods (giropay, SOFORT Überweisung, iDeal, eps, Post-Finance EFinance and Post-Finance Card) capture must be set to Auto.
Bank Account CheckIf checked, the bank account check is enabled. Available for Direct Debit.
Submit Order DetailsIf checked, product line items are transmitted to PAYONE.
Use PAYONE Mandate ManagementEnables the usage of PAYONE mandate management. Available for Direct Debit.
Download mandate as PDFEnables the download of PAYONE mandate as PDF. Available for Direct Debit.
Ask For CVCAsk for Card Security Code (CVC/CSC/CVV/CID). Available for Credit Card.
Minimum Validity of CardMinimum remaining validity of credit cards in months. Available for Credit Card.


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 (valid from 7.10.12) 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:

PropertyValuesDescription
payment.payone.creditcard.<field>.sizePositive numberDetermines the size of the input field. Default = 4
payment.payone.creditcard.<field>.maxlengthPositive numberDetermines the length of the input field. Default = 4
payment.payone.creditcard.<field>.widthStringDetermines the width of the iframe that holds the field. The unit of the width has to be specified the same way as it would be specified in a CSS style (e.g., 60px).
payment.payone.creditcard.defaultStyle.heightStringDetermines the height of the iframe that holds the field. The unit of the height has to be specified the same way as it would be specified in a CSS style, Default = 34px
payment.payone.creditcard.defaultStyle.widthStringDetermines the width of the iframe that holds the field. The unit of the width has to be specified the same way as it would be specified in a CSS style. Default = 250px
payment.payone.creditcard.defaultStyle.inputStringDefault CSS style to be used with text fields.
payment.payone.creditcard.defaultStyle.selectStringDefault CSS style to be used with select fields.

1 - <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.

PropertyDefault

intershop.payment.Payone_Sofort.countries

AT,DE,CH,NL

intershop.payment.Payone_Eps.countries

AT

intershop.payment.Payone_DirectDebit.countries

DE,AT

intershop.payment.Payone_IDeal.countries

NL

intershop.payment.Payone_PostFinance_EFinance.countries

CH

intershop.payment.Payone_PostFinance_Card.countries

CH

intershop.payment.Payone_Giropay.countries

DE

intershop.payment.Payone_Paydirekt.countries

DE

intershop.payment.Payone_PayPal.countries

*

intershop.payment.Payone_Invoice.countries

*

intershop.payment.Payone_Cash_In_Advance.countries

*
intershop.payment.Payone_CreditCard.countries*

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:

5 Data Handling

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



DescriptionPAYONE Payment Methods


InvoiceCash in AdvanceCredit CardDirect DebitEPSGiroPayPaypalSofortIdealPostFinance E-FinancePostFinance CardPaydirekt
AmountThe amount for the transaction

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Currency Currency code e.g. EUR/USD

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Customer details (e-mail, first name, last name)Customer e-mail, customer first name, and last name

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

reference (order id)Order reference generated by the merchant

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Address details (street, zip, city, country) Invoice and shipping address details provided by the user (optional and configurable in back office)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

de[line item details]Array of product attributes, e.g. product name, value, discount, gift card (optional and configurable in back office)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

(question)

bankgrouptypeIssuer of Online-Bank-Transfer

(error)

(error)

(error)

(error)

(tick)

(error)

(error)

(error)

(tick)

(error)

(error)

(error)

bankcountryCountry of the bank

(error)

(error)

(error)

(error)

(tick)

(error)

(error)

(tick)

(error)

(tick)

(tick)


Credit card details

Card number, CVC, expiry date

Sensitive data is handled via PayGate iframes only and is never stored at the merchant.

(error)

(error)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

languageLanguage indicator to specify the language that should be presented to the customer

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Account holder nameName of the account holder

(error)

(error)

(error)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

IBANInternational Bank Account Number

(error)

(error)

(error)

(tick)

(error)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

BICBank Identifier Code to be used for payment

(error)

(error)

(error)

(question)

(error)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

Browser informationBrowser details like javaEnabled, language, colorDepth, timezone, screenHeight, screenWidth, windowSize 

(error)

(error)

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

Direct debit typeOne time payment (single)
Stored account (first/recurring)

(error)

(error)

(error)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

(error)

 SymbolDescription

(tick)

Transmitted

(error)

Not Transmitted

(question)

Optional

6 Limitations

6.1 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.

6.2 Supported Countries and Currencies

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

Payment MethodSupported CountriesSupported Currencies
Direct DebitDE, ATEUR
epsATEUR
iDEALNLEUR
PostFinance E-FinanceCHCHF
PostFinance CardCHEUR, CHF
SOFORT ÜberweisungDE, AT, CH, NLEUR
Invoice*EUR
giropayDEEUR
paydirektDEEUR
PayPal**
Credit card**
Cash in Advance**

6.3 Restricted Capabilities

  • Cancel: No "cancel" capability for eps, iDEAL, PostFinance E-Finance, PostFinance Card and SOFORT Überweisung implemented.
  • Refund:  The "refund" business process works after a delay of 24 h minimum until the bank reported the status back to PAYONE. Since there is no possibility to retrieve this precondition from PAYONE, the refund cannot be disabled.

6.4 Length of E-Mail Addresses

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

6.5 Testing

The payment method Giropay cannot be tested using the PAYONE sandbox anymore. The feature in the sandbox has been deactivated by PAYONE by now.

7 Changelog

7.1 Version PAYONE/6.0.0

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

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets