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:
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.
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.
This glossary describes the terms used in this document ( typewriter
style denotes terms that directly correspond with class/interface/method names):
Term | Description |
---|---|
PSP | Payment Service Provider |
PSC | Payment Service Connector |
Capability | A capability denotes a specific ability of a payment service |
S2S | Server-to-server |
Payment Method | A payment method describes the way money is transferred from one party to another |
Payment Instrument | A payment instrument is the object that holds the data representing the user's bank account. The data depend on the payment method used |
Payment | A payment is the actual object that facilitates a transaction via a specific payment method (using a payment instrument) |
PII | Payment Instrument Information |
PT | Payment Transaction |
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.
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.
Package | Description |
---|---|
com.intershop.api.annotation | Contains annotations used in the API |
com.intershop.api.data | Provides interfaces and classes for dealing with different data used in the service calls |
com.intershop.api.service.payment | Provides 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.
Capability | Description |
---|---|
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. |
OfflinePayment | Implement this marker interface if the payment processing is done offline. Examples for this capability are the payment methods cash on delivery and invoice. |
Validate | Implement the capability interface if you need feature methods to validate payment data entered by the user. |
Authorize | Implement 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. |
Capture | Implement the interface if the payment service supports capturing (parts of the) order amount. |
Cancel | Implement the interface if the service supports the cancelation of an authorized payment. |
Reduce | Implement the interface with the payment service if it supports the reduction of the previously authorized payment amount. |
Refund | Implement this interface (providing all functionality required) if a service supports refund of already captured money. |
LimitedTender | The 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 Note It is not intended to be implemented directly. Use one of its child interfaces instead. |
RedirectBeforeCheckout | This 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. |
FastCheckout | The 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. |
RedirectAfterCheckout | The 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.
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.
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.
During the checkout process there are two possible interactions with the payment provider:
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).
During the checkout process redirects to pages hosted by the PSP are supported. There are two types of redirects:
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.
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):
Step | Actor(s) | Action | Description |
---|---|---|---|
1. | Browser | Buyer selects payment method supporting redirection before checkout and continues checkout workflow. | Example: 3DSecure (VisaCard, MasterCard) |
2. | Intershop 7 | Payment 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:
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:
|
3. | Browser | Browser redirects buyer to a web page of the PSP. | Example: 3DSecure web site provided by VISA. |
4. | PSP | PSP 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. | PSP | PSP 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:
All other HTTP query parameters from PSP's redirect request are extracted in:
Note The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step. |
6. | PSC | Result 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 |
7. | Intershop 7 | Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5). | |
8. | Browser |
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):
Step | Actor(s) | Action | Description |
---|---|---|---|
1. | Browser | Buyer selects payment method supporting redirection before checkout and continues checkout workflow. | Example: 3DSecure (VisaCard, MasterCard) |
2. | Intershop 7 | Payment 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:
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:
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 |
3. | Browser | Browser redirects buyer to a web page of the PSP. | Example: 3DSecure web site provided by VISA. |
4. | PSP | PSP 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. | PSP | PSP 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. | PSC | PSC 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. | PSC | PSC 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:
All other HTTP query parameters from PSP's redirect request are extracted in:
Note The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step. |
8. | PSC | Result 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 |
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 |
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.
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):
Step | Actor(s) | Action | Description |
---|---|---|---|
1. | Browser | Buyer selects payment method supporting redirection after checkout, continues checkout workflow and finally submits the order. | Example: ISH OnlinePay |
2. | Intershop 7 | Payment 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:
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:
|
3. | Browser | Browser redirects buyer to a web page of the PSP. | Example: ISH OnlinePay authentication page |
4. | PSP | PSP 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. | PSP | PSP 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:
All other HTTP query parameters from PSP's redirect request are extracted in:
Note The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step. |
6. | PSC | Result 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 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 |
7. | Intershop 7 | Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5). | |
8. | Browser |
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):
Step | Actor(s) | Action | Description |
---|---|---|---|
1. | Browser | Buyer selects payment method supporting redirection after checkout, continues checkout workflow and finally submits the order. | Example: ISH OnlinePay |
2. | Intershop 7 | Payment 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:
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:
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 |
3. | Browser | Browser redirects buyer to a web page of the PSP. | Example: ISH OnlinePay authentication page |
4. | PSP | PSP 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. | PSP | PSP 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. | PSC | PSC 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. | PSC | PSC 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:
All other HTTP query parameters from PSP's redirect request are extracted in:
Note The Payment Framework does not interpret the result of PSP's payment processing in any manner in this step. |
8. | PSC | Result 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 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 |
9. | Intershop 7 | Intershop 7 payment Success/Failure/Cancel callback pipeline calls the target pipeline addressed by the jumpTarget (see step #5). | |
10. | Browser |
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.
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
.
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:
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:
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)
The Payment Framework defines these rules for the behavior:
amountForPayment
of the open tender payment method needs to be reduced in that case.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.
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.
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.
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:
tenderBalance
attribute) available for payment.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
.
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)
The Intershop standard implementation of this class returns limited tender payment transactions first and the open tender ones afterwards.
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:
isCapturingAuthorization() == false
)isCapturingAuthorization() == true
)PT_AUTHORIZATIONVOID_FAILED
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.
The following table provides a brief overview of the supported payment transaction states.
Status Name | Description |
---|---|
Created | The PaymentTransaction has been newly created and was not yet processed in any way. |
Authorized | The PaymentTransaction has been authorized. |
Partially Captured | The PaymentTransaction has been captured partly but not completely. |
Captured | The PaymentTransaction has been captured completely. |
Authorization Voided | The PaymentTransaction was either previously authorized and this status has now been voided (canceled), or an authorization attempt failed. |
Capture Voided | The 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. |
Marked | The PaymentTransaction has been marked for batch settlement. |
Settled | The PaymentTransaction which was previously marked for batch settlement has been confirmed as settled. |
Refunded | The PaymentTransaction has been partially or fully refunded. |
Authorization Void Failed | The PaymentTransaction cancelation (or reduction) was not successful. |
Refund failed | The PaymentTransaction refund has failed. |
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 | ![]() |
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.
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
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.
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:
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:
The consumer storefront provides the following integration points for payment services using Payment Instrument Information (PII):
These integrations are supported by the the REST API too.
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.
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.