Broadleaf Microservices
  • v1.0.0-latest-prod

Creating a Payment Gateway Module

Before you begin, it is recommended that you fully understand how gateways work and the context of how these gateway integration libraries are used, before attempting to implement any of the BLC interfaces. Please make sure to review the following docs to aid in this process:

Conventions

We’ll go over some of the conventions to create consistency across all Payment Modules.

Package Structure

  • All implementations of the Payment Gateway Common interfaces will be under com.broadleafcommerce.payment.service.gateway

  • All gateway specific services and constants will be under com.broadleafcommerce.vendor.<replace_with_gateway_name>.service

  • All gateway specific web components such as Spring MVC Controllers and Thymeleaf Processors will go under com.broadleafcommerce.vendor.<replace_with_gateway_name>.web

Use any SDK Provided by the Gateway Implementation

Some gateways don’t publish their Java SDK on Maven Central, so you may need to install it locally, and in your documentation, note that there is a dependency on their JAR for compilation. If this is the case, please make note of that and where to find that dependency in your documentation.

Use AbstractExternalPaymentGatewayCall

In a lot of cases, you may notice that a lot of the transaction methods share common code to create a request that then calls an external API or SDK and parses the response. If this is the case, you may wish to create a parent class that all these extend to unify this boiler-plate code.

It’s also important to extend AbstractExternalPaymentGatewayCall if your service makes an SDK or external API call. This allows anyone using the framework to configure the ServiceMonitor AOP hooks and detect any outages to provide (email/logging) feedback when necessary. You can look at the JavaDocs on that class for further examples and documentation.

Capture the Raw Response on the PaymentResponse DTO

It’s often very helpful and in some cases required to capture the entire response back from a gateway. Make sure to serialize all the information coming back from the gateway in the rawResponse field. You may wish to use a PaymentGatewayWebResponsePrintService to translate an HttpServletRequest into a rawResponse string.

Use a MessageConstants Class

Create a MessageConstants class that define the gateway specific constants that you pass between the additional fields map of the request and response DTOs to the gateway services.

Implementation Guidelines

Here are some steps to follow to help get you started developing your own module.

  1. Extend and implement the PaymentGatewayConfiguration. Every module should provide a configuration bean that provides information about what it can and cannot handle as well as any specific configuration parameters it needs.

  2. Implement the PaymentGatewayConfigurationService. Every module should provide an implementation of this service that will define all the Payment Gateway Interfaces that this module supports.

  3. Implement the PaymentGatewayTransactionService to handle any AUTHORIZE or AUTHORIZE_AND_CAPTURE operations.

  4. Implement the PaymentGatewayRollbackService to handle error scenarios. This API will be called in the event an error gets thrown in the Checkout Workflow after a payment has been confirmed. That means the payment has already been captured or authorized however something else in the workflow has caused an exception to occur which therefore needs to roll back any payments that have already been processed.

Debugging

If you’ve followed the package structure outlined above, it is helpful to enable trace debugging for the following:

<logger name="com.broadleafcommerce.payment.service.gateway"><level value="TRACE"/></logger>
<logger name="com.broadleafcommerce.vendor"><level value="TRACE"/></logger>