Concept - Payment Framework

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 delivered with IS7. Out of the box, the following payment methods (without any 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.

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 downloadable zip-folder containing all the diagrams as *.png files.

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 user's 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)
PIIPayment Instrument Information
PTPayment Transaction

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.

Payment Service API

The API builds the basis 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 that a payment service has to support can easily be added by implementing a so-called capability.

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.

Capabilities

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. Examples for this capability are the payment methods cash on delivery and invoice.
ValidateImplement the capability interface if you need feature methods to validate payment data entered by the user.
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 refund of 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 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

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

Available with 7.10.16 or higher
NotificationRouting
Implement the capability interface if you need enhanced 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.

Object Model

Services and Capabilities


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

Object Model


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)

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, merchant's back office).

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

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 process flow for payment services implementing redirection depends on the fact whether the PSP finally calls the callback 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 various scenarios, the Payment Framework supports different process flows.

They also depend on what kind of storefront is in use. The Payment Framework is completely data driven and supports both, REST-based clients as well as a Responsive Storefront (using pipelines).

Redirect Using REST API

In this scenario the REST client (e.g., PWA) is in charge of preparing the data in a way that they can be handed over to ICM in a PATCH request onto the used payment. The following diagram illustrates the process flow exemplarily for the success scenario (the failure and cancel scenarios are omitted for the sake of clarity, process flows are identical to the illustrated scenario):

StepActor(s)ActionDescription
1.BrowserBuyer selects payment method supporting redirection before checkout and continues checkout workflow.Example: 3DSecure (VisaCard, MasterCard)
2.

REST client

(PWA)

The REST client prepares the payment method data and assigns them to the basket.

The REST client does the request

PUT /baskets/{BasketKey}/payments/{BasketPaymentKey}

to assign the payment. When the payload contains all information needed for creating the redirect URL, the process continues as described in the following steps. Otherwise, the basket validation may report back a missing redirect, when it is executed next time.

3.ICMPayment Framework requests PSC for getting the URL to the PSP.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectBeforeCheckout
createRedirectURL(context:PaymentContext, payable:Payable, success:URI, cancel:URI, failure:URI):Result<RedirectURLCreationResult>

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

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

ICM 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 success Callback On Redirect Before Checkout
  • URI for the cancel Callback On Redirect Before Checkout
  • URI for the failure Callback On Redirect Before Checkout
  • basketId - The ID uniquely identifies the Intershop 7 basket the payment is processed for. (Necessary for later processing in step #7.)
  • paymentId - The ID uniquely identifies the Intershop 7 payment. (Necessary for later processing in step #7.)
  • Other - PSC may add additional information for the PSP, e.g., card_type=vsa, card_number=4111111111111111 in case of 3DSecure
4BrowserBrowser redirects buyer to a web page of the PSP.Example: 3DSecure web site provided by VISA.
5.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.

6.PSPPSP redirects buyer back to the REST client.

PSP redirects the buyer back to the shop site by choosing one of the three callbacks, depending on the result of the payment processing in step #5

7.REST client (PWA)The REST client extracts the parameter from PSP's redirect request.

The REST client extracts the parameter from PSP's redirect request (see step #3), 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 for.
  • paymentId - The ID uniquely identifies the Intershop 7 payment.

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

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

The extracted data are transferred to ICM via a PATCH request

PATCH /baskets/{BasketKey}/payments/{BasketPaymentKey}

so they can be used to perform the payment authorization when the order is submitted later.

Note

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

8.ICMResult 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. Based on the parameters provided in the method call, the PSC continues the processing. The parameters' method parameter contains all HTTP query parameters included in the callback URI (see step #7). In case information should be stored in the payment history, the returned CallbackResult provides the ability to store such information.

The outcome is wrapped and returned to the REST client.

9.REST client (PWA)
The REST client continues the process flow depending on the Success/Failure/Cancel outcome.
10.Browser

Redirect Using RSS Without Payment Connector Callback

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 exemplarily for the success scenario:



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
createRedirectURL(context:PaymentContext, payable:Payable, success:URI, cancel:URI, failure:URI):Result<RedirectURLCreationResult>

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 for. (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 for.
  • 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 analyzes 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). 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

Redirect Using RSS with Payment Connector Callback Pipeline

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

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
createRedirectURL(context:PaymentContext, payable:Payable, success:URI, cancel:URI, failure:URI):Result<RedirectURLCreationResult>

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 for. (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 for.
  • 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. PSC analyzes 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). In case information should be stored in the payment history, the returned CallbackResult provides the ability to do so.

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

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 process flow for payment services implementing redirection depends on the fact whether the PSP finally calls the callback 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 various scenarios, the Payment Framework supports different process flows.

They also depend on what kind of storefront is in use. The Payment Framework is completely data driven and supports both, REST-based clients as well as a Responsive Storefront (using pipelines).

Redirect Using REST API

As in the redirect before checkout, the REST client (e.g., PWA) is in charge of preparing the data in a way that they can be handed over to ICM in a PATCH request onto the used payment. The following diagram illustrates the process flow exemplarily for the success scenario (the failure and cancel scenarios are omitted for the sake of clarity, process flows are identical to the illustrated scenario):

StepActor(s)ActionDescription
1.BrowserBuyer selects payment method supporting redirection after checkout, continues checkout workflow, and finally submits the order.Example: ISH OnlinePay
2.REST client (PWA)The REST client prepares and submits the order data (incl. redirect URIs).

The REST client does the request

POST /orders

to assign the payment. When the payload contains all information needed for creating the redirect URL, the process continues as described in the following steps. Otherwise, the order creation is interrupted and reports a missing redirect. In such a case the process can be continued by PATCH on that order request which provides the required parameter.

3.ICMPayment Framework requests PSC for getting the URL to the PSP.

The Payment Framework calls the method:

com.intershop.api.service.payment.v1.capability.RedirectAfterCheckout
createRedirectURL(context:PaymentContext, payable:Payable, success:URI, cancel:URI, failure:URI):Result<RedirectURLCreationResult>

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

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

ICM 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 for. (Necessary for later processing in step #7.)
  • paymentId - The ID uniquely identifies the Intershop 7 payment. (Necessary for later processing in step #7.)
  • Other - PSC may add additional information for the PSP.
4.BrowserBrowser redirects buyer to a web page of the PSP.Example: ISH OnlinePay authentication page
5.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.

6.PSPPSP redirects buyer back to the shop.

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

7.REST client (PWA)

The REST client extracts the parameter from PSP's redirect request (see step #3), 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 for.
  • paymentId - The ID uniquely identifies the Intershop 7 payment.

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

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

The extracted data are transferred to ICM to complete the payment authorization.

PATCH /orders/{OrderKey}

Note

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

8.ICMResult 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. Based on the parameters provided in the method call, the PSC analyzes the result and continues the processing. The parameters' method parameter contains all data included in the callback (see step #7). 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.

The outcome is wrapped and returned to the REST client.

9.REST client (PWA)
The REST client continues the process flow depending on the Success/Failure/Cancel outcome.
10.Browser

Redirect Using RSS Without Payment Connector Callback Pipeline

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

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
createRedirectURL(context:PaymentContext, payable:Payable, success:URI, cancel:URI, failure:URI):Result<RedirectURLCreationResult>

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 for. (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
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 for.
  • 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. PSC analyzes 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). In case information should be stored in the payment history, the returned RedirectAfterCheckoutCallbackResult provides the ability to do so.

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

Redirect Using RSS with Payment Connector Callback Pipeline

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

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
createRedirectURL(context:PaymentContext, payable:Payable, success:URI, cancel:URI, failure:URI):Result<RedirectURLCreationResult>

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 for. (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

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 for.
  • 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. PSC analyzes 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). 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

Templates

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

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 a limited tender when it implements the capability LimitedTender.

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:

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. Criteria 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 for 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.
So 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.

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

The reason for this is the difficulty that arises 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.

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.

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. Distributing (splitting) the basket amount among the payment instruments 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 Payment Instrument Information (PII) first.
  • If the basket is not covered yet, the remaining amount will be assigned to an open tender payment instrument (if existing).

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. As a result of the basket calculation process it is possible that 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.

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

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 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 takes effect. 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 payment transaction 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.

Payment Transaction States

Supported States

The following table provides a brief overview of the supported payment transaction states.
Status NameDescription
CreatedThe PaymentTransaction has been newly created and was not yet processed in any way.
AuthorizedThe PaymentTransaction has been authorized.
Partially CapturedThe PaymentTransaction has been captured partly but not completely.
CapturedThe PaymentTransaction has been captured completely.
Authorization VoidedThe PaymentTransaction was either previously authorized and this status has now been voided (canceled), or an authorization attempt failed.
Capture VoidedThe PaymentTransaction was previously captured and this status has now been voided or there were several attempts to capture it, all of which failed and the system does not try any longer.This is a final state.By default this status is only used when an authorization with AutoCapture is set to failed via notification.
MarkedThe PaymentTransaction has been marked for batch settlement.
SettledThe PaymentTransaction which was previously marked for batch settlement has been confirmed as settled.
RefundedThe PaymentTransaction has been partially or fully refunded.
Authorization Void FailedThe PaymentTransaction cancelation (or reduction) was not successful.
Refund failedThe PaymentTransaction refund has failed.

State Transitions

The transitions between the states are supervised by the payment framework. The allowed state transitions are visualized by the diagram and table below. Please keep in mind that the diagram ignores pending states.Manual Capture

Manual Capture
Target State
CreatedAuthorizedPartially CapturedCapturedAuthorization VoidedCapture VoidedRefunded
Source StateCreated(tick)(tick)

(tick)

Authorized
(tick)(tick)(tick)


Partially Captured

(tick)(tick)


Captured





(tick)
Refunded





(tick)
Auto Capture

Auto Capture
Target State
CreatedAuthorizedPartially CapturedCapturedAuthorization VoidedCapture VoidedRefunded
Source StateCreated(tick)

(tick)
(tick)
Captured





(tick)
Refunded





(tick)
The allowed transitions also depend on the pending flag. That means, when the source state is not pending, the new (target) state can be either pending or not. On the other side, when the current status is pending, the new target cannot be pending when it is in a different state.The number of possible combination is huge and cannot be shown completely. But for illustration, here a small example of allowed source states (incl. pending flag) for the target state CAPTURED:

Pending Flag of Target State: Captured
PendingNot Pending
Source State (incl. Pending Flag)Created-(tick)(tick)
AuthorizedPending


Not Pending(tick)(tick)
Partially CapturedPending


Not Pending(tick)(tick)
CapturedPending
(tick)

Hosted Payment Pages

Most credit card implementations require the integration of a payment processing functionality to fulfill the PCI DSS requirements. Usually these integrations have to be configured and require 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 two 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 ready for use 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.

Notifications

Standard Notification Handling

By default ICM decides if a notification from the PSP is accepted or not based on the information stored in the payment history and the set pending flag. This approach has its limitations, since it cannot handle
  • notification arriving before the callback is completed
  • payment transactions started in PSP back office or ERP

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

Integration Into Intershop 7

Commerce Management (Back Office) Handling

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 History

The payment history can be called after clicking the link History in the tab Payment of an order.One of the displayed 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

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
All relevant data for payment handling are provided over the REST API, too, so the REST client can support similar integrations.

Limitation and Known Issues

Usage of Property Groups

Payment services support the usage of several property groups. However, they do not support the usage of the same property group(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.
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.