Broadleaf Microservices
  • v1.0.0-latest-prod

Integrating With A Payment Gateway

In an eCommerce ecosystem, payment interactions primarily take place in two areas: in the checkout & in the order management system (OMS). In the following sections, we’ll explore the architecture behind these functional areas and the foundational concepts that must be maintained for any payment gateway integration. From there, we’ll review how you can build a new payment gateway integration.

Roles & Responsibilities of Services/Resources

  • Frontend

    • Renders payment options fetched from the checkout payment method option endpoint

    • Gathers payment method data from customer input and/or the customer’s profile

    • Interacts with the payment gateway to tokenize the payment method data

    • Coordinates the amount that will be paid with each selected payment option

Note
 For frontend SDK library support across payment gateways, see our payment SDK.

  • CartOperationServices

    • Provides the list of available payment method options in checkout

    • Coordinates cart & checkout-related processes

    • Validates the cart’s payments & that they cover the cart total

    • Coordinates the execution of checkout-related payment transactions (esp. authorizations or authorizationAndCaptures), calling PaymentTransactionServices to execute the transactions

  • OrderOperationServices

    • Coordinates post-checkout order management processes like fulfilling, cancelling fulfillments, & returning items

    • Coordinates the execution of payment transactions (esp. captures & refunds) for fulfillment-related processes, calling PaymentTransactionServices to execute the transactions

  • PaymentTransactionServices

    • Stores the Payment representation (i.e. how much will be paid against which payment method)

    • Stores the customer’s saved payments representation for re-use of the payment

    • Executes payment transactions against payment gateway integrations

    • Keeps a record of payment transaction interactions and results

  • Payment Gateway Common Implementation

    • Integrates the payment transaction execution plumbing of PaymentTransactionServices with calls to the payment gateway’s APIs

    • Maps PaymentRequest payloads from PaymentTransactionServices into gateway API requests, calls the gateway’s API, & interprets the response into a PaymentResponse, which PaymentTransactionServices uses to record transaction results.

Tip
 To get a better sense of how checkout is processed via the services/resources listed above, checkout the Checkout Payment Architecture document.
Note

The frontend can be responsible for executing payment transactions, but we strongly prefer executing payment transactions via PaymentTransactionServices. The primary reason for this is our ability to know when payment transactions have been attempted/executed.

Before sending a transaction to the payment gateway, the PaymentTransactionService first records a PaymentTransaction with status SENDING_TO_PROCESSOR and a transactionReferenceId. That way, if anything happens where we don’t receive transaction results, we always know that we attempted to execute a transaction. Additionally, since the transactionReferenceId is always unique and is sent to the gateway in the transaction request, we can always check with the gateway to see if they have knowledge of the transaction results.

Implementing a New Payment Gateway Integration

  1. Integrate the gateway with your frontend UI & create a PaymentTransactionServices Payment

  2. Create a module implementing the PaymentGatewayCommon interfaces

  3. Register your module with PaymentTransactionServices

  4. Configure CartOperationServices to consider your gateway

  5. Configure OrderOperationServices to consider your gateway