In this post we are going to discuss WebSphere Commerce (WCS) Payment Methods and Payment Plug-ins. We will go through how an Affirm payment can be implemented in WCS as an example of implementing a new Payment Method. The goal with the following discussion is to give the reader a fundamental understanding of how to implement a Payment Method in WebSphere Commerce and in particular of the concept of a Payment Plug-in.

See WebSphere Commerce – Payment System Overview for an overview of the WCS Payment System and see the IBM Knowledge Center for further details on WCS and its components.

Implement a new Payment Method

A Payment Method in WCS is the means by which a payment will be processed, for example a specific brand of a credit card or PayPal. A functional Payment Method consists of several different things that must all play nicely together. Some custom choices can me made during the development of a new Payment Method, but in general the following is needed:

  • Add a new policy to the database which represents the Payment Method
  • Create a .jsp file which displays the UI elements needed during checkout and implement other front-end changes
  • XML configuration files: The payment configuration files must be correctly configured
  • Create a new Payment Plug-in (or add handling for the new Payment Method to an existing one and customize the plug-in logic)

The needs of the business and the type of payment being implemented must affect the design of processing flow for the payment. Implementing a new Payment Method can be a highly individualized process with plenty of customization or it can rely heavily on out-of-the-box processes. 

Payment Plug-in

Payment Plug-in is 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 actions that the plug-in must handle. Which actions the plug-in must handle depends on the Payment Methods utilizing the plug-in, along with the needs of the business. Before implementing a new Payment Method we must analyze which actions it must support and design the logic of the Payment Plug-in it utilized accordingly. The types of actions that can be executed by a plug-in are as follows:

  • Payment approval (or authorization)
  • Payment deposit (or capture)
  • Credit (or refund)
  • Reversals for the above transactions

Creating a Payment Plug-in can be split into three distinct phases:

  • Create a new EJB project for the Payment Plug-in and make it available to WCS
  • Implement the business logic of the plug-in. That means to implement all the methods required by the Payment Methods that will use the plug-in
  • Create and configure the XML files for the plug-in (PluginDeployment.xml and PaymentSystemPluginMapping.xml)

Affirm implementation

Here want to take an example of how an Affirm payment can be made through a Payment Service Provider (in this case, Cybersource). Details on how to integrate with Affirm can be found here. We follow the steps listed above to configure the Affirm payment method. The first part of the payment flow (the Prime Payment Event) is executed as described in Figure 1. We use the provided API from Cybersource to do all external service calls.

Figure 1. Simplified overview of the Affirm checkout process (Prime Payment Event).

We use two WCS commands during the processing of the Prime Payment Event (see IBM Knowledge Center for details):

  • PrepareOrderCmdImpl
  • ProcessOrderCmdImpl

As the names indicate, the first command executes certain processes to prepare the order for checkout, meanwhile the latter executes (among other things) the payment process. As is indicated in Figure 1, we split the logic of the checkout process into two custom commands:

  • AffirmForwardCmdImpl
  • AffirmReturnCmdImpl

The reason for this is that we must redirect the customer to Affirm’s site in order for them to apply for credit. After the credit application is done, Affirm will redirect the customer to a URL that will execute the second custom command, where the more standard WCS payment process happens such as the Payment Plug-in Controller creating a Financial Transaction which is then processed by the Payment Plug-in.

Similarly, a customized flow like we have implemented for the Prime Payment Event can also be implemented for the other two payment events (Reserve Payment Event and Finalize Payment Event). However, we did not have any need for that, so we simply use out-of-the-box commands that will trigger the Payment Plug-in Controller to execute an appropriate method on the Payment Plug-in. These commands will be executed when the order reaches a certain stage. In our example it is when the order is ready to be shipped and then after the order has been shipped.  

After analyzing the needs for the Affirm Payment Plug-in, we determined that we needed to implement methods to authorize and capture a payment along with the reversal for those transactions. The implementation basically consists of creating a request with all the required information that the Cybersource API expects and then the handling of the received response. We need to ensure that the plug-in is being passed all the required information needed to build the request. That is done in the XML configuration files for the plug-in.

Conclusion

This is an example of how a new Payment Method can be implemented in WCS. As we have discussed, it will always depend on the nature of the payment to be implemented and the needs of the business how exactly the details of the process turn out to be. For more details on how to actually implement a Payment Methods we direct the reader to the IBM Knowledge Center where hands-on tutorials and other documentation can be found.