Document Tree
Document Properties
Kbid
312U98
Last Modified
04-Dec-2024
Added to KB
10-Oct-2024
Public Access
Everyone
Status
Online
Doc Type
Release Notes
Product
  • PAYONE
  • ICM 12
Related Product
Home ⋮ Knowledge Base ⋮ 312U98
Share this document
Public Release Note - PAYONE Service Connector 8

Table of Contents


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 release and the accompanying documentation are valid for the following combinations of software versions:

IntershopPAYONE Service Connector
ICM 12.08.0.0

PAYONE Connector version 8.0.0 provides the same functionality as PAYONE Connector 7.0.1 for the supported payment methods to facilitate the migration from ICM 11 to 12.

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)

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

 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:

Application TypeApplication Type IDDescription
Progressive Web App intershop.REST

Progressive Web App endpoint for B2C/B2B channel

Supported payment methods:

  • Credit Card
  • PayPal
  • Invoice
  • PostFinance Card
  • SOFORT Banking
  • iDEAL

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:

Payment Method TypeDetails
PayPalPayPal
Online PaymentSOFORT Überweisung
Credit 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 PaymentInvoice
Online PaymentiDEAL
PostFinance Card

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.

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.


Setup

The customization image for the PAYONE Extension is available in the Intershop public repository.

Helm Declaration of Extension for Deployment

Add customization to helm values:

icm-as:
	customizations:
		payone:
			repository: intershophub/icm-as-customization-payone:<TAG>
...
	environment:
		CARTRIDGE_LIST: "ft_icm_as ft_payone"

Using Docker Compose to Start the Server with the Extension Image

Before starting ICM with the PAYONE extension, ensure that all required services, the MSSQL database, and the web server are running.

Modify the compose file to specify which cartridges the ICM should load. This is done by setting the CARTRIDGE_LIST environment variable on the application server:
version: "3.8"
services:
	customize-payone:
		image: icm-as-customization-payone:<TAG>
		volumes:
			- customizations:/customizations
...
	appserver:
		depends_on:
		- customize-payone
...
		environment:
			# ... more environment variables ...
			# Example cartridge list. Please adapt to your requirements.
			CARTRIDGE_LIST: "ft_icm_as ft_payone"
...


When the application server is started, a DBPreparation process will run to configure the PAYONE payment services. Once this process is complete, you can log in to the back office. Under Services, the PAYONE payment services should be available for use.

To use the PAYONE payment services, configure the PAYONE payment service with the required credentials, PSP communication URLs, and other configuration parameters.

Customize the Connector

To customize the PAYONE Connector, it is necessary to create a customization project for the payment connector.

To add the customization image for the PAYONE Connector to your project, add it to the dependencies of your customization.
To achieve this, perform the following steps:

  1. Register the customization image in your main build.gradle.kts:

    val icmDockerRegistry = "docker.tools.intershop.com/icm/intershophub"
// specified in gradle.properties
val payoneConnectorVersion: String by project

intershop {
	projectConfig {
		modules {
			// ... other modules ...

			register("payone") {
				dependency.set("com.intershop.services.payment_payone:payone:${payoneConnectorVersion}")
				image.set("${icmDockerRegistry}/icm-as-customization-payone:${payoneConnectorVersion}")
				testImage.set("${icmDockerRegistry}/icm-as-customization-payone:${payoneConnectorVersion}")
			}
		}
	}
}

subprojects {
	// ... other settings ...

	plugins.withType<JavaPlugin> {
		dependencies {
			// ... other dependencies ...

			cartridge(platform("com.intershop.services.payment_payone:versions:${payoneConnectorVersion}"))
			implementation(platform("com.intershop.services.payment_payone:versions:${payoneConnectorVersion}"))
		}
	}
}

  2. Add dependencies to the PAYONE feature to your project's feature definition (e.g., ft_myproject/build.gradle.kts):

    dependencies {
	// base on ICM AS
	cartridgeRuntime ("com.intershop.icm:ft_icm_as")

	// ... more dependencies ...

	// PAYONE Connector
	cartridgeRuntime ("com.intershop.services.payment_payone:ft_payone")
}

    To include the PAYONE feature, add your project's feature definition cartridge to your development configuration within your main build.gradle.kts. If you need additional feature cartridges for local development, you can add them here as well.

    intershop_docker {
	// ... other configuration ...
	developmentConfig {
		appserverAsContainer = true
		cartridgeList.set(setOf("ft_myproject"))
		testCartridgeList.set(setOf("ft_mytest"))
	}
}

  3. Define payoneConnectorVersion in your gradle.properties:

    ...
payoneConnectorVersion = <TAG>
...
  4. Start your application server in development mode:

    • Use Gradle to manage the server instance by using the command gradlew startAS

    • Run gradlew tasks to see available tasks or check for further options.



For more information on managing the artifacts, refer to:

Configuration

Transaction Status Notifications

The PAYONE platform uses an asynchronous way to notify the ICM of changes to a transaction. We call these "notifications".

A REST endpoint to where PAYONE should send the notifications to is provided by the connector. Its default location is https://<host>:<port>/INTERSHOP/rest/WFS/<Site>/-/payment/payone/notifications

This URL must be set as the TransactionStatus URL in the PAYONE Shop Portal (see following section).

All incoming notifications are checked for authenticity to prevent fraudulent requests. This includes checking the source IP and user agent of the notification requests. By default, notifications are expected to be sent as HTTPS POST request from an IP address starting with 185.60.20 and user agent "PAYONE FinanceGate". Both values can be configured using the following keys:

Configuration KeyDescriptionDefault Value
intershop.payment.payone.notification.ip_prefixIP address prefix of incoming notification request.185.60.20
intershop.payment.payone.notification.user_agentUser agent of incoming notification request.PAYONE FinanceGate

If an incoming notification is rejected, a corresponding WARN message is logged.


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 Notifications REST endpoint (https://<host>:<port>/INTERSHOP/rest/WFS/<Site>/-/payment/payone/notifications) is accessible from the configured PAYONE Notification IP address (default: 185.60.20.0/24) 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

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

ExplanationImage

PAYONE Merchant Interface (PMI): https://login.pay1.de/

1. Log in with your username and password.

A secure code will be sent to your e-mail address.

2. Insert the security code from the e-mail and complete the login.

3. Click Configuration.

4. Click Payment Portals.

5. Select your portal and click Edit.

6. Click Extended.

7. Enter a valid Success URL.

8. Enter a valid Back URL.

9. Enter a valid TransactionStatus URL.

(Set the TransactionStatus URL to point to the notification resource.
Assuming there is no URL rewriting, it should look similar to this: https://<host>:<port>/INTERSHOP/rest/WFS/<Site>/-/payment/payone/notifications.)

10. If not present yet, generate a key.

11. Click Save.

The two URLs (success, back) are fallbacks in case the three return URLs are not provided in the requests when the payment is created. ICM always sets these values and the URLs set in the PMI are not used. However, they must be valid to meet PAYONE's requirements.

Enabling and Configuring a Payment Service

Check Recipe - Enable a Payment Service in Cookbook - Payment for detailed instructions on 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 (SOFORT Überweisung, iDeal and Post-Finance Card) capture must be set to Auto.
Bank Account CheckIf checked, the bank account check is enabled. This is currently not used by any of our supported payment methods.
Submit Order DetailsIf checked, product line items are transmitted to PAYONE.
Use PAYONE Mandate ManagementEnables the usage of PAYONE mandate management. This is currently not used by any of our supported payment methods.
Download mandate as PDFEnables the download of PAYONE mandate as PDF. This is currently not used by any of our supported payment methods.
Ask For CVCAsk for Card Security Code (CVC/CSC/CVV/CID). Available for Credit Card.


You can see the required PAYONE values below 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. They can be overwritten within your custom cartridges <cartridge_name>/src/main/resources/cartridges/<cartridge_name>.properties or by specifying properties files under <cartridge_name>/src/main/resources/resources/<cartridge_name>/config.

For more information on the configuration framework, check Concept - Configuration and Cookbook - Configuration.

Supported Currencies

The PAYONE Service Connector requires the following settings for the currencies you want to support:

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_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_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


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.

<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

A list of supported countries can be defined for each payment method. 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_IDeal.countries

NL

intershop.payment.Payone_PostFinance_Card.countries

CH

intershop.payment.Payone_PayPal.countries

*

intershop.payment.Payone_Invoice.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 overwrite the existing localizations in the back office within your custom cartridge.

For details about localization, see:

Data Handling

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


DescriptionPAYONE Payment Methods


InvoiceCredit CardPaypalSofortIdealPostFinance Card
AmountThe amount for the transaction

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Currency Currency code e.g. EUR/USD

(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)

reference (order id)Order reference generated by the merchant

(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)

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)

bankgrouptypeIssuer of online bank transfer

(error)

(error)

(error)

(error)

(tick)

(error)

bankcountryCountry of the bank

(error)

(error)

(error)

(tick)

(error)

(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)

(tick)

(error)

(error)

(error)

(error)

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

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Browser informationBrowser details such as javaEnabled, language, colorDepth, timezone, screenHeight, screenWidth, windowSize 

(error)

(tick)

(error)

(error)

(error)

(error)

 SymbolDescription

(tick)

Transmitted

(error)

Not Transmitted

(question)

Optional

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.

Payment MethodSupported CountriesSupported Currencies
iDEALNLEUR
PostFinance CardCHEUR, CHF
SOFORT ÜberweisungDE, AT, CH, NLEUR
Invoice*EUR
PayPal**
Credit card**

Restricted Capabilities

  • Cancel: No "cancel" capability for iDEAL, PostFinance Card and SOFORT Überweisung implemented.

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.

Changelog

Version PAYONE/8.0.0

  • Migrated the connector to an ICM 12 customization (JDK 21, jakarta packaging)
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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.