Public Release Note - PAYONE Service Connector 2.3

 

1 Introduction

Welcome to the Intershop 7 PAYONE Service Connector. The Service Connector adds PAYONE payment methods to your Intershop 7 installation.

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

1.1 Preconditions

  • The PAYONE Service Connector requires an installed Intershop 7 system. See version numbers below.
  • Using the PAYONE Service Connector requires a dedicated payment provider contract with the vendor PAYONE. Make sure to contact PAYONE to negotiate and sign your payment provider contract.

1.2 Version Information and Dependencies

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

IntershopPAYONE Service Connector
7.4 CI2.3.6

The PAYONE Service Connector includes the following cartridge:

  • ac_payment_payone

1.3 Supported Application Types

The PayPalPLUS Connector may be used out of the box for the following application types:

Application TypeApplication Type IDDescription
B2C WebShop

intershop.B2CWebShop

Business to Consumer Channel

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 7 system:

Payment Method TypeDetails
Credit CardCredit card payment with:
  • Visa
  • Mastercard
  • American Express
  • Carte Bleue
  • Diners Club
  • Discover
  • JCB
  • Maestro International

This payment method type can be configured to use PAYONE iframes in order to comply with PCI-DSS.

PayPalPayPal
PaydirektPaydirekt
Klarna InvoiceKlarna
Account Based PaymentCash in advance
Cash on delivery
Direct debit
Invoice
Online Paymenteps
giropay
iDEAL
PostFinance Card
PostFinance E-Finance
SOFORT Überweisung

Intershop's customers can safely useIntershop 7 in PCI certified environments without impacting their certification status. Furthermore,Intershop 7 provides features and configuration needed to implement all 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".
ReduceOption to lower the capture amount. 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.

2.3 Creditworthiness Check

When paying with a credit card, a customer may have to enter the 3D Secure code during the checkout. To control this, the attribute CreditworthinessCheck can be added to the cart, with one of the following values:

  • skip - do not do a creditworthiness check. The parameter ecommercemode=internet is sent to PAYONE.
  • force - force the creditworthiness check. The parameter ecommercemode=3dsecure is sent to PAYONE.
  • auto - Payone decides whether or not a creditworthiness check is necessary. The parameter ecommercemode is not sent to PAYONE.

The attribute no3DSecure that was used in previous versions is not longer supported.

3 Setup

Note

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

3.1 Precondition

The package is available via Intershop's Public Nexus.

  • A set up and configured CI environment
    See Cookbook - Setup CI Infrastructure for details.
    See Concept - Continuous Delivery Tools for basic information about Continous Integration.
  • A running Intershop 7.4.6 CI installation 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

3.2 Set Up the Assembly

To add the PAYONE Service Connector into your Intershop 7 system, you may either

  • Incorporate the cartridge into an already existing assembly.

    In the build.gradle file of the assembly add:

cartridges {
        def payonePaymentProvider = [
            'ac_payment_payone'
        ]
        include (*(payonePaymentProvider.collect {"com.intershop.services:$it:2.3.6"}), in: [development, test, production])    
 
        order = listFromAssembly(baseAssembly) + payonePaymentProvider
    }
...

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

 

For details about managing assembly artifacts, see:

3.3 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_CREDITCARD.currenciesDefines which currencies are configurable for PAYONE Credit Card. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_SOFORT.currenciesDefines which currencies are configurable for PAYONE SOFORT Überweisung. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_GIROPAY.currenciesDefines which currencies are configurable for PAYONE giropay. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_EPS.currenciesDefines which currencies are configurable for PAYONE eps. 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: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_POSTFINANCECARD.currenciesDefines which currencies are configurable for Payone PostFinance Card. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_IDEAL.currenciesDefines which currencies are configurable for Payone iDEAL. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_PAYPAL.currenciesDefines which currencies are configurable for Payone PayPal. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_INVOICE.currenciesDefines which currencies are configurable for Payone Invoice. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_CASH_IN_ADVANCE.currenciesDefines which currencies are configurable for Payone Cash in Advance. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_CASH_ON_DELIVERY.currenciesDefines which currencies are configurable for Payone Cash on Delivery. Default: all.comma separated list, e.g. EUR, USD
intershop.payment.PAYONE_PAYDIREKT.currenciesDefines which currencies are configurable for Payone Cash on Delivery. Default: allcomma separated list, e.g. EUR, USD
intershop.cartridges.ac_payment_payone.payment.cia.enabledcountriesDefines for which countries Payone Cash in Advance is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.cod.enabledcountriesDefines for which countries Payone Cash on Delivery is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.creditcard.enabledcountriesDefines for which countries Payone Credit Card is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.efinance.enabledcountriesDefines for which countries Payone PostFinance E-Finance is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.eps.enabledcountriesDefines for which countries Payone eps is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.giropay.enabledcountriesDefines for which countries Payone giropay is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.ideal.enabledcountriesDefines for which countries Payone iDEAL is enabled. Default: NL.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.invoice.enabledcountriesDefines for which countries Payone Invoice is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.paypal.enabledcountriesDefines for which countries Payone PayPal is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.pfcard.enabledcountriesDefines for which countries Payone PostFinance Card is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.sofort.enabledcountriesDefines for which countries Payone SOFORT Überweisung is enabled. Default: all.comma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.bankaccount.countriesDefines which countries are selectable for refund in the backoffice. Default: DE, AT, NL, FR, CHcomma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.klarna.invoice.enabledlanguagesDefines which language codes are enabled Payone Klarna Invoice.Together with the respective index from intershop.cartridges.ac_payment_payone.payment.klarna.invoice.enabledcountries, Klarna supported locales are build for countries. Default: DE, DA, FI, DE, NL, NB, SVcomma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.klarna.invoice.confirmcountriesDefines which countries need confirmation of Terms&Conditions for Payone Klarna Invoice. Default: DE, ATcomma separated list, e.g. DE, AT
intershop.cartridges.ac_payment_payone.payment.klarna.invoice.field.{fieldname}

Defines for which countries is visible the given parameter for Payone Klarna Invoice.

Default: intershop.cartridges.ac_payment_payone.payment.klarna.invoice.field.gender=DE, AT, NL intershop.cartridges.ac_payment_payone.payment.klarna.invoice.field.birthday=DE, AT, NL, SE intershop.cartridges.ac_payment_payone.payment.klarna.invoice.field.personalnumber=DK, FI, NO, SE

comma separated list, e.g. DE, AT

According to Recipe: Change Deployed File Content With Filters this setting has to be overridden within <IS_SHARE>/system/config/cartridges/ac_payment_payone.properties.

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

3.4 Deploying 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

4.1 Adjusting Firewall Settings

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

  1. api.pay1.de/post-gateway/
  2. secure.pay1.de/client-api/

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

4.2 Applying UI-Based Configuration

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

Please consult the PAYONE documentation on how to setup your payment portal.

4.2.1 Configuring the PAYONE Shop Portal

In addition to the standard PAYONE shop portal configuration, which is described in the PAYONE documentation, you must also configure the TransactionStatus URL.

  1. Log in to the PAYONE system.
  2. Click Configuration in the navigation menu.
  3. Click Payment Portals, then click the edit link next to your shop payment portal.
  4. Open the Extended tab.
  5. Set the TransactionStatus URL to point to the ViewPayone-Notify pipeline. Assuming there is no URL rewriting, it should look similar to 'https://<host>:<port>/INTERSHOP/web/WFS/<site>/<locale>/-/<currency>/ViewPayone-Notify'.
    Success URL and Back URL may remain empty.

4.2.2 Assigning Payment Methods to a Sales Organization

  1. Log in to Organization Management.
  2. Navigate to Sales Organizations and click the name of the organization you want to edit.
  3. Open the Payment tab.
  4. Select the checkboxes of the new payment methods you intend to enable for the current sales organization.
  5. Click Apply to save your settings.

4.2.3 Assigning Payment Methods to a Channel

 

Note

Assigning payment methods to a channel requires the access privilege "Payment Manager" for this channel.

 

  1. Log in to Commerce Management.
  2. Navigate to Organization | Channels and click the name of the channel you want to edit.
  3. Open the Payment tab.
  4. Select the checkboxes of the new payment methods you intend to enable for the current channel.
  5. Click Apply to save your settings.

4.2.4 Configuring the Payment Methods

 

Note

Configuring payment methods in a sales channel requires the access privilege "Payment Manager" for this channel.

 

  1. Log in to Commerce Management.
  2. Select the sales channel from the context selection box.
    Please note that administrating sales channels of a partner organization requires to log in to the partner organization's Commerce Management.
  3. Navigate to Orders | Payment Methods and click the name of the payment method you want to configure.
  4. Open the Applications tab.
  5. Select the checkboxes of all applications for which the payment method should be enabled.
  6. Click Enable to save your settings.
  7. Open the Customer Segments tab.
  8. Choose for which customers the payment method should be enabled.
  9. Click Apply to save your settings.
  10. If you have chosen Selected Customer Segments, click New to assign the desired customer segments.
  11. Open the Preferences tab
  12. Select the currency-dependent availability and the payment currency.
  13. Set the 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).
    Productive ModeSwitch between productive and test environment (unchecked, set as default).
    OR
    Check this checkbox on the live system. Leave unchecked for 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".
    Storefront NameThis name is displayed in the storefront.
    Submit Order DetailsIf checked, product line items are transmitted to PAYONE.


    You can view the needed PAYONE values on the API Parameter tab of your PAYONE shop portal.

  14. Click Apply to save your settings.

4.2.5 Configuring Credit Card Payment Method Properties

Some of the configuration of the credit card payment method 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 available Concept - Configuration (valid to 7.10.11) and Cookbook - Configuration.

PropertyValuesDescription
payment.payone.creditcard.serviceparam.DisplayType[iFrame, AJAX]Affects how credit card information is handled during checkout. In both cases the credit card data is submitted to PAYONE and is not kept by the Intershop system.
If iFrame is set, then the credit card fields will be provided by PAYONE as iframes. This is the default value. If AJAX is set then the credit card fields are provided by the Intershop system. Submitting the form will send the data to PAYONE via AJAX.
Below properties are only valid when iFrame is configured as display type.
payment.payone.creditcard.serviceparam.<field>1.Type[Select, Tel, Text, Password]Determines what type of input field should be provided by PAYONE for a particular credit card field.
payment.payone.creditcard.serviceparam.<field>.LengthPositive numberDetermines the length of the input field.
payment.payone.creditcard.serviceparam.<field>.MaxCharactersPositive numberDetermines the maximum number of characters allowed in the input field.
payment.payone.creditcard.serviceparam.<field>.iframe.WidthStringDetermines the width of the iframe that holds the field. The unit of the width has to be specified the same way it would be specified in a CSS style (e.g., 100px).
payment.payone.creditcard.serviceparam.<field>.iframe.HeightStringDetermines the height of the iframe that holds the field. The unit of the height has to be specified the same way it would be specified in a CSS style (e.g., 100px).
payment.payone.creditcard.serviceparam.<field>.StyleStringSpecifies a custom CSS style that should be used with the field.
payment.payone.creditcard.serviceparam.DefaultTextInputStyleStringDefault CSS style to be used with text fields.
payment.payone.creditcard.serviceparam.DefaultSelectInputStyleStringDefault CSS style to be used with select fields.
payment.payone.creditcard.serviceparam.DefaultWidthStringDefault width for the iframes that hold the credit card fields. The unit of the width has to be specified the same way it would be specified in a CSS style (e.g., 100px).
payment.payone.creditcard.serviceparam.DefaultHeightStringDefault height for the iframes that hold the credit card fields. The unit of the height has to be specified the same way it would be specified in a CSS style (e.g., 100px).
payment.payone.creditcard.serviceparam.ErrorMessagesPlaceholderIDBooleanDetermines whether errors will be displayed in specific element on the page. If the configuration is not set, the developer is responsible to handle error messages, otherwise upon failing verification check on PAYONE error that happened will be show at the element.

1 - <field> identifies which PAYONE credit card field is affected by the property. Supported values include cardtypes, cardnumber, cvc2, validmonth, validyear. For example, payment.payone.creditcard.serviceparam.cardnumber.Type.

4.3 Localization

The PAYONE Service connector provides English and German localization files 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 Limitations

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

5.2 Supported Countries and Currencies

Most of the payment methods provided with this package are specific for certain countries or currencies.

6 Known Issues

No known issues.

7 Changelog

7.1 Version PAYONE/2.3.6

  • Fix: PAYONE-126 - Payone uses internal IP when there is a load balancer

7.2 Version PAYONE/2.3.5

  • New Feature: [PAYONE-111] - Enhance credit card iframe integration of PAYONE (IS 7.4 CI)
  • New Feature: [PAYONE-99] - Accept SEPA mandate on order submission
  • Fix:  PAYONE-28 - Payone - Credit Card - Card type is missing

7.3 Version PAYONE/2.3.2

  • New Feature: PAYONE-82 - Migrate Paydirekt to IS 7.4.6
  • New Feature: [ISPAY-321, ISPAY-322, ISPAY-323] - Added SEPA mandate management
  • New Feature: [ISPAY-61] - PAYONE: Integrate Klarna "pay by invoice"

  • Fix: [ISPAY-924] - PAYONE Connector cannot be identified by PAYONE
  • Fix: ISPAY-827 - Some functional problems and missing features
    • New issue: some templates are not downward compatible - Fixed: add changed templates information in changedTemplates.patch-file showing what changes were made to the templates between version2.2and version2.3of PAYONE Connector
    • New issue: no signs of new iframes for credit card (PCI requirement) - Fixed: add to documentation that, for PCI-DSS compliance, aniframesshould be used. Nevertheless, default isAjax.
    • Regression: Payment with iDeal is not possible anymore (authentication failed for faulty or missing country error) - Fixed: issued by Capital Letter for parameterCountryandIp. Now the parametercountryandip are with lower letters.
    • Regression: Payment with iDeal with bank Frieslandbank not work - Fixed: Fixed by removingFRIESLAND_BANKgroup key frompayoneiDealBankGroupTypes.properties. However, in theiDealwebsite,Frieslandbankis not listed anymore (https://availability.ideal.nl/).

    • Regression: new content is shown directly beside the display name and below the description / form (all payment methods) - Fixed: removed unneeded description.

7.4 Version PAYONE/2.3.0.0

  • New Feature: [ISPAY-671] - Adapt Credit Card for PCI-DSS-compliance ()
  • New Feature: Adapted demand of creditworthiness check (parameter "ecommercemode")

8 Interaction Design

IS_7_IAD_Payone_3.pdf

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
Support Tickets