Broadleaf Microservices

Payment Gateway Common Domain


While not a part of the Payment Gateway Common domain itself, com.broadleafcommerce.order.common.domain.Payment represents the payment method associated with a Cart or Order.

When interacting with payment gateway’s through the Payment Gateway Common library, Payments should be converted in to PaymentRequests.

A Payment indicates how a customer will pay for their order. Each time a transaction occurs with that Payment, a com.broadleafcommerce.order.common.domain.PaymentTransaction is create. Conceptually, a Payment is more about what a customer intends to do, while a PaymentTransaction is what actually happened to that Payment. For instance, a customer might say that they want to pay for $20 of the order with a gift card (which would be an Payment) but actually decrementing the amount from the gift card would not occur until checkout. All completed orders should have at least 1 Payment, and that Payment should have at least 1 confirmed and successful PaymentTransaction of type AUTHORIZE or AUTHORIZE_AND_CAPTURE.

Checkout "Understanding the Transaction Lifecycle" for details on what AUTHORIZE and AUTHORIZE_AND_CAPTURE signify.

Key Fields

A few key parts make up a payment:

  • type: The type of this payment like Credit Card or Gift Card.

    • Default types are:

      • GIFT_CARD



      • CHECK


      • WIRE



      • COD



      • THIRD_PARTY_ACCOUNT: Intended for payments like PayPal Express Checkout.

  • amount: How much the customer is going to pay with this payment on a particular order.

    • In the common case, a customer will pay for the entire order total using only a single payment (1 credit card), but you might want to support a customer paying for items with both a credit card and a gift card, multiple gift cards, or even multiple credit cards.

      While the Broadleaf domain does not explicitly prevent you from allowing customers to pay for an order with multiple credit cards, if you do not want to store the credit cards yourself (to forego the PCI requirements) and integrate with a Payment Gateway but also still capture multiple cards, then this scenario becomes very complicated. Many payment gateways assume that a call to them with credit card information is the last step in the checkout process and will ultimately complete the order. This causes issues if you intend to capture multiple credit card payments, and a more customized solution is needed.
  • billingAddress: This is normally used for credit cards. Gift cards do not usually require a billing address.

  • gatewayType: Allows for easy reference to what gateway was used for this particular payment for auditing purposes or in multi-site configurations where 2 sites might use different payment processors.

    • While Broadleaf does not provide any of these types out of the box besides PASSTHROUGH, this will be used by different payment providers (Braintree,, Cybersource, etc).

    • Every implementing module will have a PaymentGatewayType

  • transactions: A transaction represents a state or modification for a particular payment.

    • For instance, a customer might say that they intend to pay for an order with $20 from a credit card (which would be an Payment) but then actually authorizing or capturing the card would occur within a transaction. Let’s say you’ve integrated with the Broadleaf OMS system and wanted to perform a refund of the transaction mentioned above. The system will now create a new REFUND transaction with a parent transaction that references the original AUTHORIZE_AND_CAPTURE mentioned above on the same Payment.

    • The Broadleaf Admin also gives the ability to look at the logs for any particular transaction and inspect the responses coming back from a particular gateway.

Checkout Workflow

Payments should be added before submitted the final checkout request—however, they do not need to be yet authorized. During the Broadleaf Checkout Workflow, there is a PaymentMethodValidationWorkflowActivity that ensures that the cart contains sufficient payments to cover its total price. That is followed by a PaymentConfirmationActivity that is responsible for authorizing all unconfirmed payments.