Broadleaf Microservices
  • v1.0.0-latest-prod

Payment Transaction Components (Since 1.7.0-GA)


As of 1.7, payment data storage and interactions have been moved to the Payment Transaction Services and the payments were removed from the Cart.

Introduced the new PaymentSummary domain to replace the Payment status concept. This domain summarizes the current state of transactions against the payment.

There are two new external providers to interact with the Payment Transaction Service Payment Provider.

Payment Locking Mechanism

To ensure that a payment cannot be updated while checkout is in progress the checkout uses payment locking concept. The lock tokens pass throughout the workflow and other DefaultCheckoutService methods, so that any payment-modifying requests can make use of the existing lock.

Sorting Payments


When executing transactions against payments on a Cart, they are sorted based on configured priority based on payment gateway types. In some cases, the sorting order of the payments may matter.

For example, transactions through certain payment gateways may be more challenging to reverse than others if the checkout workflow is rolled back. Let’s say we have two payment gateways, G1 and G2, and G1 is more challenging to reverse the payments than G2. Let’s say we also prioritized G2 payments to execute ahead of G1 payments. In this case, if there’s a problem authorizing G1 payments after G2 payments have already been authorized, then we’re faced with a more favorable transaction reversal scenario using G2.


To allow customizations of the payment sorting order, a hook point has been added for the transaction execution in CartOperationServices:

  1. DefaultPaymentTransactionExecutionService#sortPaymentsByPriority

By default, this method delegates to to sort the payments based on the payment gateway type, which can be configured in the Configuration section.


It is crucial to understand that the list of payment gateways for the property is ordered. Payment gateway type that is placed at the first of the list will be the highest priority.

  • Property: broadleaf.cartoperation.service.checkout.payment-gateway-priorities

  • Contains the ordered list of payment gateway types


          - PAYPAL
          - CYBERSOURCE
          - STRIPE

In this example, the payments for PayPal will be authorized first, then CyberSource, so on and so forth.

Checkout Payment Method Options


To retrieve the list of payment method options as a frontend client, call the Get payment method options endpoint, which uses the CheckoutPaymentMethodService#getCheckoutPaymentMethodOptions to get the list of applicable payment methods. This provides an array of payment method options, detailing the type and gateway type, that are available for the customer.


  • broadleaf.cartoperation.service.checkout.checkout-payment-method-options: A list of configured payment method options that are available during checkout. It has the following properties:

    • payment-method-type: The type of method such as CREDIT_CARD or COD

    • payment-method-gateway-type: The specific payment gateway to configure, e.g., PASSTHROUGH.

    • cart-max-total-restriction: The maximum cart total for which the payment is allowed to be used. This is a map where the key is the currency code and the value is the amount.

    • cart-min-total-restriction: The minimum cart total for which the payment is allowed to be used. This is a map where the key is the currency code and the value is the amount.

    • fulfillment-inclusions: List of inclusion criteria to compare against a FulfillmentGroup to determine if this payment option is allowed. The key is the path of the field to compare with on the group. The value is the list of valid values.

      • Example values:

        • ['US', 'UK', 'CA']


    • fulfillmentExclusions: Like fulfillment-inclusions but for providing excluded values instead.

    • fees: A list of applicable fees for the this payment option. Can be discountable and/or taxable.

      • Note: Will only be applied in the case of Collect on Delivery (COD) type payments by default. We will eventually extend out of box support to any payment option.

      • Properties:

        • name: Used to identify the fee after it is applied to make sure that it is not double added and is easily removed if the payment method changes.

        • amount: Decimal amount to charge

        • currency: The currency code

        • discountable: Whether it can be discounted.

        • taxable: Whether it can be taxed. Some fees may already include tax.

        • refundable: Whether it can be refunded.

  • broadleaf.cartoperation.service.checkout.tenant.{MY_TENANT}.checkout-payment-method-options

    • Tenant-discriminated property for broadleaf.cartoperation.service.checkout.checkout-payment-method-options

  • broadleaf.cartoperation.service.checkout.application.{MY_APPLICATION}.checkout-payment-method-options

    • Application-discriminated property for broadleaf.cartoperation.service.checkout.checkout-payment-method-options

If using properties discriminated by tenant or application, the list of payment method options provided will override the list of payment method option properties without any tenant/application discrimination. Be sure to re-include all gateways permitted for that tenant/application. See example below.


        # global default
          - payment-method-type: CREDIT_CARD
            payment-method-gateway-type: STRIPE
        # application specific
          # the keys are the IDs of the applications
               - payment-method-type: CREDIT_CARD
                 payment-method-gateway-type: STRIPE
               - payment-method-type: ACCOUNT_CREDIT
                 payment-method-gateway-type: BLC_ACCOUNT_CREDIT_GATEWAY
               - payment-method-type: COD
                 payment-method-gateway-type: COD
                   USD: 500.00
                   USD: 100.00
                   address.postalCode: ['10100']
                   - name: Fee 1
                     amount: 1.00
                     currency: USD
                     taxable: false
                     discountable: false
                     refundable: false


To support customizations of the availability of payment method options by customer, cart, or context attributes, several hookpoints were added in CheckoutPaymentMethodService.

  1. CheckoutPaymentMethodService#filterAvailableCheckoutPaymentMethodOptionsByCustomer

  2. CheckoutPaymentMethodService#filterAvailableCheckoutPaymentMethodOptionsByCart

By default, these hooks return the unmodified list of payment method options.

Payment Option Checkout Workflow Verification

The payment method option lookup was also added in CartPaymentMethodValidationActivity to validate that all the payment options on the cart during this checkout are valid for the customer.

To enable this validation, set broadleaf.cartoperation.service.checkout.checkout-payment-method-validation-enabled to true.