WebSphere Commerce – Payment System Overview

The goal with the following discussion is to give the reader a high-level understanding of how the Payment System works and how it can be configured.

Overview of the Payment System

Payment processing in WebSphere Commerce has three distinct events which correspond to the stages of the order life cycle. When an order reaches a certain stage the related event will trigger a specific payment process. This process is highly customizable and can be tailored to specific business needs. See Figure 1 for a high-level overview of the flow. There are three main components of the payment subsystem in WCS:

Figure 1: Overview of the components of the Payment System.

• Payments Rules Engine: Determines which Payment Actions to take and raises an event for them. It uses a set of XML configuration files in order to create the event with the appropriate actions
• Payment Plug-in Controller:
• Creates a Financial Transaction that is used to track the progress of the payment process. The transaction data is stored in PPCPAYTRAN database table
• Determine which plug-in to use. It uses a set of XML configuration files to do that
  Sends the Financial Transaction to the Payment Plug-in to process
• Persists data in database
• Payment Plug-in: A self-contained software component that serves as a proxy for a payment back-end system. It is a stateless session bean that needs to implement methods that correspond to the Payment Actions that the plug-in must handle. Exactly which actions the plug-in must handle depends on the Payment Methods utilizing the plug-in, along with the needs of the business. A plug-in is responsible for the following:
• Receive data about a Financial Transaction and send a request to the Payment Service Provider to process
• Receive a response from the Payment Service Provider and decide which data should be stored
• Populate the Financial Transaction with response data and return to the Payment Plug-in Controller

A simplified description of flow between the components of the Payment System can be described as follows:

1. Trigger for order processing (fx. customer selects a Payment Method and places order which will trigger the Prime Payment event for the order)
2. The Payment Rules Engine raises an event (fx. to make an Approve action)
3. The event is sent to the Payment Plug-in Controller (execution of an appropriate method on the controller, fx. Approve()).
4. The Payment Plug-in Controller processes the event and creates a Financial Transaction that describes it. It also determines which Payment Plug-in to use
5. The Financial Transaction is sent to the payment plug-in (execution of an appropriate method on the plug-in, fx. Approve())
6. The Payment Plug-in interacts with the Payment Service Provider to perform the payment

Concepts

A description of the concepts and terms that we use in this post:

• Payment System: Everything in WCS related with processing a payment of an order
• Payment Event: There are three distinct payment events that correspond to stages in the order life cycle
• Payment Method (and return method): Is the means by which a payment (or refund) is made (fx. credit card, PayPal, gift certificates etc.). They are managed in the POLICY database table
• Payment Instruction: Is an instance of a payment method with the details necessary to perform the payment (fx. credit card number)
• Financial Transaction: Is an object that corresponds to a Payment Action. The payment plug-in uses this object to process the Payment Event
• Payment Action: Is one of the predefined actions that can be taken during the processing of a payment (fx. approve)
• Payment Service Provider is the (third-party) back-end system that will process handle the actual payment processing

Events and actions

When a customer completes an order, a Payment Method must be chosen. The available Payment Methods are managed in the POLICY database table. The information in this table will help the Payment Rules Engine determine which configuration files to use when processing a payment with the selected Payment Method. These configurations will depend on what kind of payment is being processed and the needs of the business. We will describe the files in detail later in the post.

There is a set of predefined Payment Actions that can be taken during the processing of a payment. Which action(s) will be taken during each Payment Event is determined by the Payment Rules Engine from the set of XML configuration files related with the Payment Method. Multiple actions can be executed during a single event. The precise working of an action is implemented in the Payment plug-in associated with the Payment Method. The Payment Plug-in Controller is in charge of executing and receiving the response from the Payment Plug-in. Table 1 lists the three distinct Payment Events and how they relate to the order life cycle and Table 2 lists the Payment Actions that can be executed.

Table 1: The different stages of an order and how they relate to payment processing. The Task Command column specifies the command that is executed during the specified Payment Event.

Fase del ciclo de vida de la orden Comando de tarea del evento de pago
Order life cycle phase PrimePaymentCmd
Release to Fulfillment Reserve Payment ReservePaymentCmd
Shipment Confirmation

Table 2: The different actions that can be taken during payment processing and a description of the purpose of each

Payment Action Description
Approve Verify that the customer is allowed to make the purchase
Deposit Capture a payment for an order
ApproveAndDeposit Verify that the customer is allowed to make the purchase and then capture a payment for the order
ReverseApproval Voids an approval
Credit Issues a refund to return money to customer
Error Generate an error message to indicate that an exception has occurred
ConsumeAmount Update payment related information (without causing any direct payment action with a back-end system)

Configurations

The configuration files for the Payment System are split up into two sub folder which can be found at workspace_dir/WC/xml/config/payments/

Edp configurations

Configuration files used to determine what actions to take and how to process the payment. These configuration files can be split into different groups (folders). Out of the box, we have only have one group, default. Each group contains the following configuration files:

• PaymentMappings.xml: Defines the payment method (from the policy name in database) and which payment rules and configurations to use.
• PaymentMethodConfigurations.xml: Defines various configurations that can be used with a payment method
• PaymentRules.xml: Defines rules that determine what happens during each Payment Event
• RefundMappings.xml: Defines which configuration to use for the refund
• RefundMethodConfigurations.xml: Defines various configurations that can be used with a refund method

Furthermore, for each payment configuration that is defined in PaymentMethodConfigurations.xml, we have a folder with the same name. This folder contains a set of configuration files that will define which actions to take depending on the state of the payment and which payment rule is being used.

Ppc configurations

Configuration files used by the Payment Plug-in Controller to determine the appropriate Payment Plug-in. Contains the following configuration files:

• PaymentSystemPluginMapping.xml: Defines payment systems which keep track of which payment plug-in to use and define certain configurations to use

Further, for each plug-in that is defined in PaymentSystemPluginMapping.xml, we have a folder with the same name that contains up to two XML files. It will contain a file called PluginDeployment.xml that will, as the name suggests, contain information about how to deploy the plug-in in question. The other, optional file, which contains information about which additional parameters are passed to the plug-in, depending on which Payment Method is using it.

Figure 2: Overview of the different configuration files related with the Payment System and how they interconnect

Conclusion

We have discussed the WebSphere Commerce Payment System and given an overview of how it works and how different components are connected together. In particular, we have discussed the different configuration files related with the Payment System. More details on any of the discussed concepts can be found, along with tutorials, on the IBM Knowledge Center.

Rúnar Sverrisson

Developer at Orienteed.