Document Properties
Kbid2722B8
Last Modified23-Mar-2020
Added to KB17-Aug-2015
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
ProductICM 7.10

Concept - Payment Framework

1 Introduction

The payment framework, which consists of the cartridges api_service, bc_payment and bc_payment_service, has been introduced in order to facilitate the integration of external payment services. On the one hand, this framework provides an API (cartridge api_service) that allows to easily plug in new payment service implementations. On the other hand, the payment framework (cartridges bc_payment and bc_payment_service) works as an abstraction layer between the actual payment service implementations and the Intershop application. That is, application enhancements are not intended to refer directly to a payment service implementation, and payment service implementations are not intended to depend on any new application feature.

Although the API is independent, the recommended way to implement a custom payment service for Intershop 7 is to wrap it as a Managed Service. This is not necessarily a must. Though, payment services should generally be packaged in ac_<cartridge-name> cartridges.

A standard implementation based on the Managed Services Framework is shipped with IS7. Out of the box, the following payment methods (without third-party interaction) are currently supported:

  • Cash in advance
  • Cash on delivery
  • Direct debit transfer
  • Invoice

Please refer to Concept - Intershop Reference Payment Services for more details.

Additional payment methods, which use external payment services, are supported via dedicated add-on products.

Payment Framework

1.1 References

Download Diagrams

Since a couple of the diagrams are quite large and tricky to be displayed in the document, this document also provides a download zip-folder containing all the diagrams as *.png files.

1.2 Glossary

This glossary describes the terms used in this document ( typewriter style denotes terms that directly correspond with class/interface/method names):

TermDescription
PSPPayment Service Provider
PSCPayment Service Connector
CapabilityA capability denotes a specific ability of a payment service.
S2SServer-to-server
Payment MethodA payment method describes the way money is transferred from one party to another.
Payment InstrumentA payment instrument is the object that holds the data representing the users bank account. The data depend on the payment method used.
PaymentA payment is the actual object that facilitates a transaction via a specific payment method (using a payment instrument).

2 Payment Framework

As mentioned in the introduction, the framework consists of two parts: the internal business objects and the external API. Both will be described in detail in this chapter.

2.1 Payment Service API

The API builds the base for all payment service connectors. It is composed of simple interfaces which are independent of other Intershop frameworks. Furthermore, it is separately versioned and stable for extended periods. The most important artifact is the interface PaymentService all payment services have to implement. Each feature a payment service has to support can easily be added by implementing a so-called capability.

2.1.1 Packages

PackageDescription
com.intershop.api.annotationContains annotations used in the API.
com.intershop.api.dataProvides interfaces and classes for dealing with different data used in the service calls.
com.intershop.api.service.paymentProvides interfaces for implementing the payment connectors as well as the classes for dealing with service response.

Currently version 1 (subpackage v1) of the service API is in use.

2.1.2 Capabilities

Note

Some capabilities require the Intershop Commerce Suite patch 7.6.1 - e.g., FastCheckout.

Intershop strongly recommends to deploy this patch to make use of the new and improved Standard-Payment API.

CapabilityDescription
PaymentCapability

Parent interface of all payment service capabilities. A capability denotes a specific ability of a payment service.

Note

It is not intended to be implemented directly. Use one of its child interfaces instead.

OfflinePaymentImplement this marker interface if the payment processing is done offline. Good samples for this capability are the payment methods cash on delivery and invoice.
ValidateImplement the capability interface if you need feature methods to validate user entered payment data.
AuthorizeImplement the interface if a direct communication with the payment service provider for the payment authorization is needed. In case the payment service supports this type of authorization, it has to implement this interface.
CaptureImplement the interface if the payment service supports capturing (parts of the) order amount.
CancelImplement the interface if the service supports the cancelation of an authorized payment.
ReduceImplement the interface with the payment service if it supports the reduction of the previously authorized payment amount.
RefundImplement this interface (providing all functionality required) if a service supports refunding already captured money.
LimitedTenderThe interface marks a payment service so that it handles a limited tender payment instrument (e.g., gift cards). It provides all special functionality required to handle this kind of payment instrument.
RedirectingPayment

The interface RedirectingPayment is the base capability for the special form of payment services that require a redirect (before/after checkout/fast checkout) to the payment service provider.

Note

It is not intended to be implemented directly. Use one of its child interfaces instead.

RedirectBeforeCheckoutThis capability interface, derived from RedirectingPayment, marks its implementing service, so that it implements the Redirect Before Checkout handling. Since the redirect to the PSP is done before order creation, an additional authorization request after order creation is required. To ensure the implementing service provides the additionally needed functionality, the interface extends the Authorize interface.
FastCheckoutThe interface extends the capability RedirectBeforeCheckout and marks the implementing payment service so that it supports fast checkout. All data required for completing the order are delivered by the PSP. Similar to the RedirectBeforeCheckout the redirect is done before order creation and an extra direct authorization call is required.
RedirectAfterCheckoutThe RedirectAfterCheckout extends the RedirectingPayment capability. It is a marker interface for all payment services which implement the Redirect After Checkout communication workflow. It does not provide any own methods.
HostedPaymentPage

Implement the capability interface if you need to configure the integration of payment processing provided by the PSP depending on the current context.

Note

With no implementation there is still the possibility to use the ISML extension points in the inSPIRED storefront, but without direct access to some configuration values.

NotificationRouting

Implement the capability interface if you need better support for notifications.

If no implementation is provided, the standard notification handling (based on payment transaction state and history) is used.

Available with 7.10.16 or higher

All service calls return a Result object which holds the general response state, lists for collecting errors and warnings during the processing. Furthermore, it holds a capability-specific payload of the result. Besides common request-specific parameters (e.g., transaction ID) such a payload provides the possibility to add custom attributes.

2.1.3 Object Model

2.1.3.1 Services and Capabilities

Payment Service API Overview


2.1.3.2 Data

The Standard Payment API uses its own data structure independent of business objects (BOs). It is intended to decouple the services from the complex data structure used internally. The mapping from the BOs to the API data structure is done in the bc_payment_service cartridge.

Payment API Data Model

2.2 Payment Business Object Framework

The Business Object Framework for the Payment API uses the extension concept to support the flexibility the new fine-granular capabilities bring to the API.

2.2.1 Object Model

Payment Business Object API

3 Workflows and Interactions

During the checkout process there are two possible interactions with the payment provider:

  • Direct communication with the payment provider
  • Redirect to the payment provider (and return afterwards)

Checkout Process

3.1 Direct Communication

During checkout the authorization is done using a direct call to the payment provider. All other types of direct communication with the payment provider can be done in the order history. In general, these are Capture, Cancel, Reduce, Refund. It depends on the payment method and the supported types. Direct calls are always triggered by the merchant site (web shop, ERP System, merchants back office).

3.2 Redirect

During the checkout process redirects to pages hosted by the PSP are supported. There are two types of redirects:

  • Redirect Before Checkout
    • Required if the actual payment method selection occurs on pages of the payment provider
    • We obtain the possibility to something before we create the order, e.g.:
      • 3D-Secure check
      • Check of the creditworthiness
      • Retrieve customer addresses from the payment provider and store them at the basket (Fast Checkout only)
  • Authorization Redirect / Redirect After Checkout
    • Occurs after the checkout process
    • The payment data of the user is verified at the payment provider

3.2.1 Workflow Redirect Before Checkout

The capability interface RedirectBeforeCheckout, derived from RedirectingPayment, designates its implementing service, so that it implements the Redirect Before Checkout handling. Since the redirect to the PSP is done before order creation, an additional authorization request after order creation is required. The interface extends the Authorize interface to ensure that the implementing service provides the additionally needed functionality.

The processing flow for payment services implementing redirection depends on the fact whether the PSP finally calls callback pipelines with a HTTP POST request, including additional data in the request message's body. This might be data, in XML, JSON or an arbitrary format, PSP wants to transfer back to the PSC as a result to the redirect request. However, most PSPs only pass result data via HTTP request parameters to the PSC. To honor both scenarios, the Payment Framework supports two different process flows.

3.2.1.1 Redirect Without Payment Connector Callback Pipeline

In this case the PSP only passes result data via HTTP request parameters to the PSC. This means that PSC does not require a callback pipeline at all, because all request parameters are provided to the PSC by the Payment Framework. The following diagram illustrates the process flow exemplary for the success scenario (The failure and cancel scenarios are omitted for the sake of clarity, process flows are identically to the illustrated scenario):

payment_redirect_before_checkout_without_connector_callback_pipeline


StepActor(s)ActionDescription
1.BrowserBuyer selects payment method supporting redirection before checkout and continues checkout workflow.Example: 3DSecure (VisaCard, MasterCard)
2.Intershop 7Payment Framework requests PSC for getting the URL to the PSP.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectBeforeCheckout
calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

implemented by the PSC. This method assembles the URI to the PSP from the following input parameters:

  • URI for the Intershop 7 Callback On Redirect Before Checkout success pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished successfully.
  • URI for the Intershop 7 Callback On Redirect Before Checkout failure pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished with an error for any reason.
  • URI for the Intershop 7 Callback On Redirect Before Checkout cancel pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been canceled by the buyer.

Intershop 7 uses the returned URI to initiate redirection to PSP using the buyer's web browser. The following data have to be included by the PSC in the resulting redirect URI to PSP in the format of HTTP query parameters:

  • URI for the Intershop 7 Callback On Redirect Before Checkout success pipeline
  • URI for the Intershop 7 Callback On Redirect Before Checkout failure pipeline
  • URI for the Intershop 7 Callback On Redirect Before Checkout cancel pipeline
  • basketId - The ID uniquely identifies the Intershop 7 basket the payment is processed. (Necessary for later processing in step #5.)
  • paymentId - The ID uniquely identifies the Intershop 7 payment. (Necessary for later processing in step #5.)
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutPayment-FromRedirect. (Necessary for later processing in step #5.)
  • Other - PSC may add additional information for the PSP, e.g., card_type=vsa, card_number=4111111111111111 in case of 3DSecure
3.BrowserBrowser redirects buyer to a web page of the PSP.Example: 3DSecure web site provided by VISA.
4.PSPPSP collects required payment instrument data from the buyer.

This process may finish successfully or cause errors for any reason, e.g., in case of invalid data entered by the buyer. Furthermore, the buyer may cancel the process.

Example: Request user to enter personal 3DSecure verification code on PSP's Web site.

5.PSPPSP redirects buyer back to Intershop 7.

PSP redirects the buyer back to Intershop 7 shop site, by choosing one of the three callback pipelines, depending on the result of the payment processing in step #4.

The callback pipeline extracts the HTTP query parameter from PSP's redirect request (see step #2), whereas the following parameters are mandatory:

  • redirectResultStatus - Indicates the result of the payment processing; can be one of the following string values: SUCCESS, FAILURE, CANCEL.
  • basketId - The ID uniquely identifies the Intershop 7 basket the payment is processed.
  • paymentId - The ID uniquely identifies the Intershop 7 payment.
  • jumpTarget - The jump target, in fact the name of the pipeline and start node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutPayment-FromRedirect

All other HTTP query parameters from PSP's redirect request are extracted in:

  • parameters - Additional parameters the PSP wants to provide to PSC.

Note

The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step.

6.PSCResult of PSP's payment processing is processed by the PSC.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectBeforeCheckout
onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result<CallbackResult>

implemented by the PSC. PSC may analyze the result of PSP's payment processing based on the provided method parameters. The parameters' method parameter contains all HTTP query parameters included in the callback URI (see step #5).

Based on the information provided by method parameters, the PSC may analyze and further process the information of PSP's payment processing provided by the method parameters. In case information should be stored in the payment history, the returned CallbackResult provides the ability to store such information.

7.Intershop 7
Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5).
8.Browser

3.2.1.2 Redirect with Payment Connector Callback Pipeline

In this case the PSP passes additional result data via HTTP POST request to the PSC, the PCS may define its own callback pipelines. The following diagram illustrates the process flow exemplary for the success scenario (The failure and cancel scenarios are omitted for the sake of clarity, process flows are identically to the illustrated scenario):

payment_redirect_before_checkout_with_connector_pipeline

StepActor(s)ActionDescription
1.BrowserBuyer selects payment method supporting redirection before checkout and continues checkout workflow.Example: 3DSecure (VisaCard, MasterCard)
2.Intershop 7Payment Framework requests PSC for getting the URL to the PSP.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectBeforeCheckout
calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

implemented by the PSC. This method assembles the URI to the PSP from the following input parameters:

  • URI for the Intershop 7 Callback On Redirect Before Checkout success pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished successfully.
  • URI for the Intershop 7 Callback On Redirect Before Checkout failure pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished with an error for any reason.
  • URI for the Intershop 7 Callback On Redirect Before Checkout cancel pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been canceled by the buyer.

Intershop 7 uses the returned URI to initiate the redirection to PSP using the buyer's web browser. The following data have to be included by the PSC in the resulting redirect URI to PSP in the format of HTTP query parameters:

  • URI for the Callback On Redirect Before Checkout success pipeline of the PSC.
  • URI for the Callback On Redirect Before Checkout failure pipeline of the PSC.
  • URI for the Callback On Redirect Before Checkout cancel pipeline of the PSC.
  • basketId - The ID uniquely identifies the Intershop 7 basket the payment is processed. (Necessary for later processing in step #5.)
  • paymentId - The ID uniquely identifies the Intershop 7 payment. (Necessary for later processing in step #5.)
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutPayment-FromRedirect. (Necessary for later processing in step #5.)
  • Other - PSC may add additional information for the PSP, e.g., card_type=vsa, card_number=4111111111111111 in case of 3DSecure

Note

In this scenario PSC assembles the URI for requesting PSP by including its own success/failure/cancel callback URIs in the HTTP query parameters, because the PSP directly redirects to the callback pipelines of PSC after payment processing (see step #5). It is not specified how PSC deals with Intershop 7's Callback On Redirect Before Checkout pipelines provided as parameters in the course of above's calculateRedirectURL(...) method call. Furthermore, it is up to the PSC whether its callback pipelines call the Intershop 7 callback pipelines by an internal pipeline Call Node or by redirection via the browser.

3.BrowserBrowser redirects buyer to a web page of the PSP.Example: 3DSecure web site provided by VISA.
4.PSPPSP collects required payment instrument data from the buyer.

This process may finish successfully or cause errors for any reason, e.g., in case of invalid data entered by the buyer. Furthermore, the buyer may cancel the process.

Example: Request user to enter personal 3DSecure verification code on PSP's Web site.

5.PSPPSP redirects buyer back to the PSC.PSP redirects buyer back to PSC by choosing one of the three callback pipelines, depending on the result of the payment processing in step #4
6.PSCPSC processes data provided by PSP.The PSC may process form data attached at HTTP request by PSP, e.g., data in XML or JSON format.
7.PSCPSC redirects buyer back to Intershop 7.

PSC redirects buyer back to Intershop 7 by choosing one of the three callback pipelines, depending on the result of the payment processing in step #4 and #6.

The callback pipeline extracts the HTTP query parameter from PSP's redirect request (see step #2), whereas the following parameters are mandatory:

  • redirectResultStatus - Indicates the result of the payment processing; can be one of the following string values: SUCCESS, FAILURE, CANCEL.
  • basketId - The ID uniquely identifies the Intershop 7 basket the payment is processed.
  • paymentId - The ID uniquely identifies the Intershop 7 payment.
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutPayment-FromRedirect.

All other HTTP query parameters from PSP's redirect request are extracted in:

  • parameters - Additional parameters the PSP wants to provide to PSC.

Note

The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step.

8.PSCResult of PSP's payment processing is processed by the PSC.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectBeforeCheckout
onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result<CallbackResult>

implemented by the PSC. The PSC may analyze the result of PSP's payment processing based on the provided method parameters. The parameters' method parameter contains all HTTP query parameters included in the callback URI (see step #5).

Based on the information provided by the method parameters, the PSC may analyze and further process the information of PSP's payment processing provided by the method parameters. In case information should be stored in the payment history, the returned CallbackResult provides the ability to store such information.

9.Intershop 7
The Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5).
10.Browser

3.2.2 Workflow Redirect After Checkout

The RedirectAfterCheckout extends the RedirectingPayment capability. It is a marker interface for all payment services which implement the Redirect After Checkout communication workflow, which is also known as Redirect for Authorization. It provides one own method isCapturingAuthorization() which returns false by default. The redirect to the PSP is done for authorizing the payment during the order creation process.

The processing flow for payment services implementing redirection depends on the fact whether the PSP finally calls callback pipelines with a HTTP POST request, including additional data inthe request message's body. This might be data, in XML, JSON or an arbitrary format, PSP wants to transfer back to the PSC as a result to the redirect request. However, most PSPs only pass result data via HTTP request parameters to the PSC. To honor both scenarios, the Payment Framework supports two different process flows.

3.2.2.1 Redirect Without Payment Connector Callback Pipeline

Similar to the handling in the redirect before checkout workflow, the PSP only passes result data via HTTP request parameters to the PSC. This means that PSC does not require a callback pipeline at all, because all request parameters are provided to the PSC by the Payment Framework. The following diagram illustrates the process flow exemplary for the success scenario (The failure and cancel scenarios are omitted for the sake of clarity, process flows are identically to the illustrated scenario):

payment_redirect_after_checkout_without_callback_pipeline

Step
Actor(s)
Action
Description
1.BrowserBuyer selects payment method supporting redirection after checkout, continues checkout workflow and finally submits the order.Example: ISH OnlinePay
2.Intershop 7Payment Framework requests PSC for getting the URL to the PSP.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectAfterCheckout
calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

implemented by the PSC. This method assembles the URI to the PSP from the following input parameters:

  • URI for the Intershop 7 Callback On Redirect After Checkout success pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished successfully.
  • URI for the Intershop 7 Callback On Redirect After Checkout failure pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished with an error for any reason.
  • URI for the Intershop 7 Callback On Redirect After Checkout cancel pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been canceled by the buyer.

Intershop 7 uses the returned URI to initiate redirection to PSP using the buyer's web browser. The following data have to be included by the PSC in the resulting redirect URI to PSP in the format of HTTP query parameters:

  • URI for the Intershop 7 Callback On Redirect After Checkout success pipeline
  • URI for the Intershop 7 Callback On Redirect After Checkout failure pipeline
  • URI for the Intershop 7 Callback On Redirect After Checkout cancel pipeline
  • orderId - The ID uniquely identifies the Intershop 7 order the payment is processed. (Necessary for later processing in step #5.)
  • paymentId - The ID uniquely identifies the Intershop 7 payment. (Necessary for later processing in step #5.)
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutConfirmation-FromRedirect. (Necessary for later processing in step #5.)
  • Other - PSC may add additional information for the PSP, e.g., card_type=vsa, card_number=4111111111111111 in case of 3DSecure
3.BrowserBrowser redirects buyer to a web page of the PSP.Example: ISH OnlinePay authentication page
4.PSPPSP collects required payment instrument data from the buyer.

This process may finish successfully or cause errors for any reason, e.g., in case of invalid data entered by the buyer. Furthermore, the buyer may cancel the process.

Example: Request user to enter personal credentials on PSP's web site.

5.PSPPSP redirects buyer back to Intershop 7.

PSP redirects the buyer back to the Intershop 7 shop site by choosing one of the three callback pipelines, depending on the result of the payment processing in step #4.

The callback pipeline extracts the HTTP query parameter from PSP's redirect request (see step #2), whereas the following parameters are mandatory:

  • redirectResultStatus - Indicates the result of the payment processing; can be one of the following string values: SUCCESS, FAILURE, CANCEL.
  • orderId - The ID uniquely identifies the Intershop 7 order the payment is processed.
  • paymentId - The ID uniquely identifies the Intershop 7 payment.
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character) that continues the checkout flow, e.g., ViewCheckoutConfirmation-FromRedirect

All other HTTP query parameters from PSP's redirect request are extracted in:

  • parameters - Additional parameters the PSP wants to provide to PSC.

Note

The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step.

6.PSCResult of PSP's payment processing is processed by the PSC.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectAfterCheckout
onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result< RedirectAfterCheckoutCallbackResult >

implemented by the PSC. The PSC may analyze the result of PSP's payment processing based on the provided method parameters. The parameters' method parameter contains all HTTP query parameters included in the callback URI (see step #5).

Based on the information provided by method parameters, the PSC may analyze and further process the information of PSP's payment processing provided by the method parameters. In case information should be stored in the payment history, the returned RedirectAfterCheckoutCallbackResult  provides the ability to store such information.

If the PSP does not immediately return the final result of the authorization redirect, an asynchronous push notification is required to complete the transaction. In the meantime the transaction state has to be set to PENDING, which is triggered by setting the state of the  RedirectAfterCheckoutCallbackResult .

7.Intershop 7
Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5).
8.Browser

3.2.2.2 Redirect with Payment Connector Callback Pipeline

In case the PSP needs to pass additional result data via HTTP POST request to the PSC, the PCS may define its own callback pipelines. The following diagram illustrates the process flow exemplary for the success scenario (The failure and cancel scenarios are omitted for the sake of clarity, process flows are identically to the illustrated scenario):

payment_redirect_after_checkout_with_connector_pipeline

Step
Actor(s)
Action
Description
1.BrowserBuyer selects payment method supporting redirection after checkout, continues checkout workflow and finally submits the order.Example: ISH OnlinePay
2.Intershop 7Payment Framework requests PSC for getting the URL to the PSP.
The Payment Framework calls the method:
com.intershop.api.service.payment.v1.capability.RedirectAfterCheckout
calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

implemented by the PSC. This method assembles the URI to the PSP from the following input parameters:

  • URI for the Intershop 7 Callback On Redirect After Checkout success pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished successfully.
  • URI for the Intershop 7 Callback On Redirect After Checkout failure pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been finished with an error for any reason.
  • URI for the Intershop 7 Callback On Redirect After Checkout cancel pipeline - The Intershop 7 URI that PSP has to call if payment transaction processing has been canceled by the buyer.

Intershop 7 uses returned URI to initiate redirection to PSP using the buyer's web browser. The following data have to be included by the PSC in the resulting redirect URI to PSP in the format of HTTP query parameters:

  • URI for the Callback On Redirect After Checkout success pipeline of the PSC.
  • URI for the Callback On Redirect After Checkout failure pipeline of the PSC.
  • URI for the Callback On Redirect After Checkout cancel pipeline of the PSC.
  • orderId - The ID uniquely identifies the Intershop 7 order the payment is processed. (Necessary for later processing in step #5.)
  • paymentId - The ID uniquely identifies the Intershop 7 payment. (Necessary for later processing in step #5.)
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutConfirmation-FromRedirect. (Necessary for later processing in step #5.)
  • Other - PSC may add additional information for the PSP, e.g., card_type=vsa, card_number=4111111111111111 in case of 3DSecure

Note

In this scenario PSC assembles the URI for requesting PSP by including its own success/failure/cancel callback URIs in the HTTP query parameters, because the PSP directly redirects to the callback pipelines of PSC after payment processing (see step #5). It is not specified how PSC deals with Intershop 7's Callback On Redirect After Checkout pipelines provided as parameters in the course of above's calculateRedirectURL(...) method call. Furthermore, it is up to the PSC whether its callback pipelines call the Intershop 7 callback pipelines by an internal pipeline Call Node or by redirection via the browser. 

3.BrowserBrowser redirects buyer to a web page of the PSP.Example: ISH OnlinePay authentication page
4.PSPPSP collects required payment instrument data from the buyer.

This process may finish successfully or cause errors for any reason, e.g., in case of a failed authentication of the buyer. Furthermore, the buyer may cancel the process.

Example: Request user to enter personal credentials on PSP's web site and authorize the merchant to withdraw the order amount from the buyer's account.

5.PSPPSP redirects buyer back to the PSC.PSP redirects buyer back to PSC by choosing one of the three callback pipelines, depending on the result of the payment processing in step #4
6.PSCPSC processes data provided by PSP.The PSC may process form data attached at HTTP request by PSP, e.g., data in XML or JSON format.
7.PSCPSC redirects buyer back to Intershop 7.

PSC redirects buyer back to Intershop 7 by choosing one of the three callback pipelines, depending on the result of the payment processing in step #4 and #6.

The callback pipeline extracts the HTTP query parameter from PSP's redirect request (see step #2), whereas the following parameters are mandatory:

  • redirectResultStatus - Indicates the result of the payment processing; can be one of the following string values: SUCCESS, FAILURE, CANCEL.
  • orderId - The ID uniquely identifies the Intershop 7 order the payment is processed.
  • paymentId - The ID uniquely identifies the Intershop 7 payment.
  • jumpTarget - The jump target, in fact the name of the pipeline and Start Node (separated by a minor character), that continues the checkout flow, e.g., ViewCheckoutConfirmation-FromRedirect

All other HTTP query parameters from PSP's redirect request are extracted in:

  • parameters - Additional parameters the PSP wants to provide to PSC.

Note

The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step. 

8.PSCResult of PSP's payment processing is processed by the PSC.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectAfterCheckout
onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result< RedirectAfterCheckoutCallbackResult >

implemented by the PSC. The PSC may analyze the result of the PSP's payment processing based on the provided method parameters. The parameters' method parameter contains all HTTP query parameters included in the callback URI (see step #5).

Based on the information provided by method parameters, the PSC may analyze and further process the information of PSP's payment processing provided by the method parameters. In case information should be stored in the payment history, the returned RedirectAfterCheckoutCallbackResult provides the ability to store such information.

When the PSP does not immediately return the final result of the authorization redirect, an asynchronous push notification is required to complete the transaction. In the meantime the transaction state has to be set to PENDING which is triggered by setting the state of the  RedirectAfterCheckoutCallbackResult .

9.Intershop 7
Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5).
10.Browser

3.3 Templates

The payment service connector implementation does not need to provide templates because they are not usable in the REST API. Therefore the property groups can be used.

3.4 Support for Multiple Payment Instruments per Basket

A classification system for payment methods distinguishes between open and limited tender payment methods. So every payment method is either of type open or limited. Payment methods where payment instruments can only cover a limited amount of money are of type (limited). Gift cards are an example of such payment instruments. A gift card has a fixed amount that is available for payment purposes. Payment methods where payment instruments can theoretically cover unlimited money amounts are of type (open). Invoice and credit card are examples of this type of payment method.

The payment framework treats a payment method as limited tender when it implements the capability LimitedTender.

3.4.1 Currently Supported Combinations of Payment Methods

The framework supports the usage of multiple payment methods in a checkout process. However, there are some restrictions. The basket supports multiple limited tender payment methods and up to one open tender payment method. The usage of more than one open tender payment service is not supported.

3.4.2 Why is Only One Open Tender Payment Method per Basket Allowed?

The reason for this is the difficulty that would arise when supporting the redirect features for multiple open tender payment methods. Imagine multiple payment methods that do a redirect during checkout. The customer gets confused, the implementation and error handling gets really complex.

3.4.3 How Are Multiple Limited Tender Payment Methods Supported?

These limited tender payment methods are restricted in their support of payment framework features. The redirect feature for limited tender payment services is not supported. Hence, the web store can support multiple payment services of this type.

3.5 Strategies to Handle the Processing of Multiple Payment Instruments

The support of multiple payment instruments per basket and the introduction of open and limited tenders increase the complexity of the payment process. Various aspects during the process can be handled in different ways and there will always be a situation where a behavior is desired that nobody has thought of yet. Here are some questions that demonstrate the problem:

  • Which payment services are allowed to be added to the basket?
  • How is the splitting of the full basket amount among multiple payment instruments handled?
  • What happens if payment instruments are added or removed?
  • In which order does the payment processing take place?
  • What happens if the payment processing was only partly successful?

The answers to these questions depend on the requirements of the specific project. Every project is different, so the payment framework allows customization according to the project-specific requirements. Different technical solutions can be applied here.

One solution is the provider functionality. Every cartridge has a file <cartridge>/javasource/resources/<cartridge>/naming/providers.properties where names are assigned to classes. These classes are registered at the NamingMgr and can be retrieved using the configured name. If there are two cartridges registering classes with the same name, the cartridge assignment order to the site decides which implementation to use. The last cartridge wins. To use a different implementation for a project, just override the strategy with another class in the providers.properties file.

The other solution is a rule-based framework (in this case for the basket calculation) where the standard rules can be exchanged by project-specific rules.

The following sections describe how the questions posed are solved:

3.5.1 Which Payment Services Are Allowed to Be Added to the Basket?

In general multiple payment instruments can be added to the basket, but the types of payment instruments that can be added are quite restricted. Which payment instruments can be used can only be decided by the service implementing a certain method. Things that can be taken into account are the payment instruments already added to the basket and the content of the line items.The Payment Service has a method to be implemented by the connector:

  • Result<ApplicabilityResult> getApplicability(Payable payable)
    This method is called in order to check if the payment service is allowed to be added to the basket in the form of a payment instrument. The parameter gives the service access to possible relevant data, e.g., the list of all line items, the current basket amount as well as user and address data.

The Payment Framework defines these rules to the behavior:

  • It allows one open tender per basket only.
  • Multiple payment methods of type limited tender are allowed.
  • Single open tender payment methods can be combined with limited tender payment methods.
  • It is allowed to have limited tender payment methods only assigned to the basket.
  • When there is an open tender assigned to the basket (so basket is already covered), it is always possible to add a limited tender payment method.
    The amountForPayment of the open tender payment method needs to be reduced in that case.
  • When the basket is already covered, it is not possible to add an open tender payment method.

3.5.2 How Is Splitting the Full Basket Amount Among Multiple Payment Instruments Handled?

When more than one payment instrument is used to cover the basket amount, the question arises which payment instrument covers which share of the full amount. So how to distribute (split) the basket amount among the payment instruments? This can be accomplished by a rule of the basket calculation framework. The rule is DistributeBasketTotalAmountRule. The rule is executed whenever the basket calculation process takes place. It determines the amounts for each payment instrument. These amounts might be refined by the next rule that handles payment costs and payment taxes, but the basic distribution of the full basket amount happens in this specific rule.

The Implementation of the DistributeBasketTotalAmountRule has the following properties and behavior:

  • Limited tenders should be fully used for payment, the rule always tries to use the maximum amount (stored in tenderBalance attribute) available for payment.
    That is why it handles limited tender PIIs first.
  • If the basket is not covered yet, the remaining amount will be assigned to an open tender payment instrument (if existing).

3.5.3 What Happens if Payment Instruments Are Added or Removed?

Whenever a payment instrument is added or removed, the basket calculation is processed. So the amounts to be covered by the currently assigned payment instruments are recalculated here. It is possible that as a result of the basket calculation process a payment instrument has the zero amount assigned for payment. In this case, the payment instrument will be removed from the basket. This is accomplished by the basket calculation rule DeleteObsoletePIIs.

3.5.4 In Which Order Does the Payment Processing Take Place?

Multiple payment instruments can require an authorization during the checkout process. The order in which these authorizations take place is determined using the PaymentAuthorizationStrategy class.

This provider class has the following interface:

  • List<PaymentTransaction> determineAuthorizationSequence(Order order)
    This method has to return a list of payment transactions. The order within that list determines the order of processing when doing authorization.

The Intershop standard implementation of this class returns limited tender payment transactions first and the open tender ones afterwards.

3.5.5 What Happens if the Payment Processing Was Only Partially Successful?

Having multiple payment instruments per basket that require authorization makes the error handling much more difficult. Imagine that some payment transaction objects have been authorized successfully but the authorization process of the next payment transaction object fails. What is Intershop's authorization error handling when multiple payment transactions have to be supported?

The simple case is that there is only one payment transaction that requires authorization. In this case the behavior is the same as in Enfinity 6.4, that means a rollback of the order creation process happens. So no order object will remain, the customer will see the appropriate authorization error message on the order review page.

The complex case is that one or more payment transactions have been authorized successfully, but a later authorization fails. In this case a more complex error handling kicks in. First of all, the order will be persisted. The order status will be set to CANCELED. The order must be kept as a reference point for the payment transactions and their payment history objects. The inventory service needs to roll back any reservations. The authorization error of the PT that caused the failing authorization will be displayed.

The following steps will be carried out:

  • Reverse the authorization/capture of the payment transactions (PTs) that have already been successfully processed.
    • If the PT did an authorization only (isCapturingAuthorization() == false)
      • Check if the Cancel functionality is supported. If so, the authorization will be canceled.
      • If there was no Cancel supported or if canceling the authorization failed, it is checked if the Reduce functionality is supported. If so, we reduce the amount to zero.
    • If it was a capturing authorization (isCapturingAuthorization() == true)
      • Check if the Refund functionality is supported. If so, we refund the amount that was captured.
    • If it is not possible to reverse the authorization/capture, either because of non-supported functionality or because of an error during the processing, set a specific error status of the payment transaction.
      • Failed cancel/reduce: PT_AUTHORIZATIONVOID_FAILED
      • Failed refund: PT_REFUND_FAILED

The order status is set to CANCELED in the beginning and remains in that status if all Cancel, Reduce or Refund operations of all payment transactions succeed. If one of these operations fails, the order status will be set to MANUAL_INTERVENTION_NEEDED. It indicates that the shop owner has to manually handle the payment status of at least one payment transaction of the order.

3.6 Hosted Payment Pages

Most credit card implementations require the integration of a payment processing functionality to fulfill the PCI DSS requirements. Mostly these integrations need to be configured and need access to some data for the payment process. In order to provide overview pipelines (inSPIRED) or REST (PWA) to them, the payment framework needs to be extended. The capability HostedPaymentPage provides three functions for requesting content from the ICM server. Since 2 of them have a default implementation, only one has to be implemented. In case the PSC implements the capability, the REST Framework uses the new functionality to collect all the content and to provide the data to the client when payment data are requested. The result of the getContent(PaymentContext, Payable) is of type Map<String, Object> to not limit the handling to much. The implementer only has to keep in mind that the values must be marshal-able so that they can be sent to the client (via REST).

The capability can then be accessed in the storefront (ISML extension in inSPIRED or own component in PWA) for configuring the PSP provided functions.

Be careful with the data made available over the interface. They are publicly accessible. We strongly recommend providing data (e.g. public keys and styling for configuration) sparsely.

3.7 Notifications

3.7.1 Standard Notification Handling

By default ICM decides based on the information stored in the payment history and the set pending flag if a notification from the PSP is accepted or not. This approach has its limitations, since it cannot handle

  • notification arriving before the callback is completed
  • payment transactions started in PSP backoffice or ERP.

3.7.2 Notification Routing via Capability

In case the default notification handling is not suitable for a specific PSP, the PSC has to take over and to decide on the available data which notification is accepted and which capability has to process the data. The following table gives an overview of use cases:

FeatureCallback OnlyCallback Before NotificationNotification Before CallbackNotification Only

Authorize

(incl. RedirectBeforeCheckout / FastCheckout)

(tick)(tick)

(error)

(S2S communication is always started on ICM side and this use case is pretty unlikely)

(error)

(S2S communication is always started on ICM side)

RedirectAfterCheckout(tick)(tick)(tick)
(Action started on ICM side, but user waits too long before returning to shop)

(tick)

(Action started on ICM side, but user never returns to shop)

Capture(tick)(tick)

(error)

(S2S communication is always started on ICM side and this use cases are pretty unlikely)

(tick)
Cancel(tick)(tick)(tick)
Reduce(tick)(tick)(tick)
Refund(tick)(tick)(tick)

Use cases marked in the table with (error) are out of scope and not officially supported.

If a PSC implements it, it is in charge of verifying the validity of the incoming notification and and resolving the capability (Authorize, Capture, ...) to be called for processing the data. After the analysis of the notification request the Payment Framework takes over and calls the implementation of the returned capability class in case the call is considered as valid.

During the processing the Framework tries to detect already processed transitions and duplicate notifications. The algorithm works with the data in the payment transaction and the result from the callback/notification. To securely detect if a payment transaction was already performed (Use case: duplicate notifications), the result object should be as complete as possible. The fields for old/new status and old/new amounts are used to identify them. (The serviceTransactionID of the PSP is not always sufficient here.) Of course the framework cannot know anything about never received notifications. To avoid invalid states, the current status has to be retrieved from the leading system (PSP). A trigger for such a status sync could be a notification.

4 Integration Into Intershop 7

4.1 Commerce Management (Back Office) Handling

4.1.1 Payment Configuration

In the Intershop Commerce Management application the available payment services are manageable in the services section. They are grouped into sub item payment methods. The general configuration options which are independent of a specific service include for example:

  • User-defined sorting
  • General activation
  • Currency-specific activation
  • Definition of a payment currency
  • Definition of details like payment costs, user group assignments
  • Payment service configuration like merchant ID

4.1.2 Payment History

The payment history can be called after clicking the link History in the tab Payment of an order.

One of the shown options may be available, depending on the actual service implementation:

  • Display the payment history as stored in the database
  • General: payment actions as supported by the payment service, like capturing, refunding, reduce, etc.
  • Payment-service-specific: information gathered online as supported by the payment service

4.2 Storefront Integration

The consumer storefront provides the following integration points for payment services using Payment Instrument Information (PII):

  • PII management in "My Account"
  • Checkout "Step 3 -Payment Selection"
    • Edit PII during this step
    • Obtain PII data from the payment provider (see Checkout workflow and possible interactions with payment providers)
  • Checkout "Step 4 - Review"
    • PII view in the checkout
  • Redirects:
    • Possible redirect from checkout step
    • Possible redirect after submitting the order

5 Limitation and Known Issues

5.1 Usage of Property Groups

Payment services support the usage of several property groups. However, they do not support the usage of the same propertygroup(s). This is a known issue and will be fixed in a future version.

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