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

• Cookbook - Payment
• Concept - Managed Service Framework
• Cookbook - Managed Service Framework
• Concept - Intershop Reference Payment Services
• Concept - Property Groups
• Cookbook - Property Groups
• ISML JavaScript Control - ISPropertyEditor

Glossary

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

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

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

Capabilities

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

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

calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result<CallbackResult>

Redirect 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 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):

calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result<CallbackResult>

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.

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

calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result< RedirectAfterCheckoutCallbackResult >

Redirect 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 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):

calculateRedirectURL(context:PaymentContext, payable:Payable, success:URI, failure:URI, cancel:URI):URI

onCallback(context:PaymentContext, payable:Payable, status:EnumRedirectResultStatus, parameters:PaymentParameters):Result< RedirectAfterCheckoutCallbackResult >

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.

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
		Created	Authorized	Partially Captured	Captured	Authorization Voided	Capture Voided	Refunded
Source State	Created
	Authorized
	Partially Captured
	Captured
	Refunded

Auto Capture

Auto Capture		Target State
		Created	Authorized	Partially Captured	Captured	Authorization Voided	Capture Voided	Refunded
Source State	Created
	Captured
	Refunded

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
			Pending	Not Pending
Source State (incl. Pending Flag)	Created	-
	Authorized	Pending
		Not Pending
	Partially Captured	Pending
		Not Pending
	Captured	Pending

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.

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:

Feature	Callback Only	Callback Before Notification	Notification Before Callback	Notification Only
Authorize (incl. RedirectBeforeCheckout / FastCheckout)			(S2S communication is always started on ICM side and this use case is pretty unlikely)	(S2S communication is always started on ICM side)
RedirectAfterCheckout			(Action started on ICM side, but user waits too long before returning to shop)	(Action started on ICM side, but user never returns to shop)
Capture			(S2S communication is always started on ICM side and this use cases are pretty unlikely)
Cancel
Reduce
Refund

Use cases marked in the table with 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

These integrations are supported by the the REST API too.

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.