Broadleaf Microservices
  • v1.0.0-latest-prod

Payment Components (Prior to 1.7.0-GA)

Overview

The following documentation is only relevant prior to version 1.7.0-GA. For payment interactions in 1.7.0-GA and later releases, see Payment Transaction Components (Since 1.7.0-GA) and Checkout Payment Architecture.

Payment management and operations are invoked during checkout. The following components are the ones primarily responsible for managing payments for a cart. These are invoked through interactions with the CartOperationService and CheckoutWorkflow components.

Note
 Read about the checkout workflow.

CartOperationServices

Overview

CartOperationServices handles adding, updating, and removing payment methods to the cart prior to initiating the CheckoutWorkflow. At least one active payment must be added to the cart before entering the checkout workflow, and the sum of payments must equal the cart’s total.

Note
 Read about the other cart-management functions of CartOperationServices.

REST API Access

CartOperationEndpoint provides REST API access to managing payments. See Cart Pricing OpenAPI documentation.

Configuration

CartOperationServices uses following configuration properties:

  • broadleaf.cartoperation.service.priceInvalidation.addPaymentMethod: Whether to consider pricing invalid if a payment is added to the cart, that is, whether the cart should be repriced in that case.

    • Payment might matter in the case of offers and promotions that target specific payment types.

    • Default is false.

  • broadleaf.cartoperation.service.priceInvalidation.updatePaymentMethod: Whether to consider pricing invalid if a payment is updated, that is, whether the cart should be repriced in that case.

    • Default is false.

  • broadleaf.cartoperation.service.priceInvalidation.removePaymentMethod: Whether to consider pricing invalid if a payment is removed, that is, whether the cart should be repriced in that case.

    • Default is false.

PaymentConfirmationService

Overview

This service is meant to coordinate the confirmation (and possible rollback) of a cart’s payments in the context of the CheckoutWorkflow.

Tip
 See the PaymentConfirmationActivity for usage.

Default Implementation Details

During the PaymentConfirmationActivity, DefaultPaymentConfirmationService will first work through all of the active payments on the cart and determine their statuses. Then, it will authorize all of the unconfirmed payments using the PaymentGatewayTransactionServiceProvider to determine the configured PaymentGatewayTransactionService that actual interacts with the payment gateway for the authorization.

The service also determines which payments are valid for rollbacks in the case of checkout failure and uses the configured PaymentGatewayTransactionService to do the rollback, that is, reverse the authorization. Typically, this won’t happen since the PaymentConfirmationActivity should be the last activity in the workflow. Instead, reverse authorizations will be triggered by the OMS after the submitted cart is converted into an order.

PaymentRequestService

This service is used by the PaymentConfirmationService to create a PaymentRequest to send to the configured payment gateway via the PaymentGatewayTransactionService. PaymentRequests represent all of the information that is needed by a payment gateway to complete a transaction including the breakdown of the transaction total, customer info, shipping, and billing addresses.

The PaymentRequest uses a builder pattern to provide a convenient way for its construction.

Example of using the payment request builder 
PaymentRequest paymentRequest = new PaymentRequest()
      .orderId(referenceNumber)
      .customer()
          .customerId("1")
          .done()
      .shipTo()
          .firstName("Bill")
          .lastName("Broadleaf")
          .addressLine1("123 Test Dr.")
          .city("Austin")
          .stateRegion("TX")
          .postalCode("78759")
          .done()
      .billTo()
          .firstName("Bill")
          .lastName("Broadleaf")
          .addressLine1("123 Test Dr.")
          .city("Austin")
          .stateRegion("TX")
          .postalCode("78759")
          .done()
      .shippingTotal(0)
      .taxTotal(0)
      .orderDescription("My Order Description")
      .orderSubtotal(10.00)
      .transactionTotal(10.00)
      .lineItem()
          .name("My Product")
          .description("My Product Description")
          .shortDescription("My Product Short Description")
          .systemId("1")
          .amount(10.00)
          .quantity(1)
          .itemTotal(10.00)
          .tax(0)
          .total(10.00)
          .done();

PaymentTransactionService

This service is used by the PaymentConfirmationService to create a PaymentTransaction to send to the configured payment gateway via the PaymentGatewayTransactionService as well as record the response of the authorization on the transaction. PaymentTransactions store individual transactions for Payments, that is, the operations the payment has undergone through a payment gateway. Thus, in a typical Broadleaf flow, there would be an "authorize" transaction created during checkout indicating the payment method is valid and authorized by the payer for use; then, at the time of fulfillment, a "capture" transaction would be added to the payment indicating the funds have been transferred. PaymentTransactions also contain some audit data.

DefaultTransactionTypes defines the default types of transactions:

  • AUTHORIZE: Funds have been authorized for capture. This might appear as a 'pending' transaction on a customer’s credit card statement.

  • REVERSE_AUTH: The reverse of an AUTHORIZE transaction. This can only occur after funds have been authorized, and before they have been captured.

  • CAPTURE: Funds have been charged/submitted/debited from the customer and payment is complete. Can only occur after an amount has been authorized.

  • AUTHORIZE_AND_CAPTURE: Funds have been captured/authorized all at once. While this might be the simplest to implement from an order management perspective, the recommended approach is to AUTHORIZE during checkout, and then CAPTURE at the time of fulfillment.

    • Many gateways like to refer to this as also a SALE transaction.

  • REFUND: Funds have been refunded/credited. This can only occur after funds have been captured or settled.

    • This should only be used when money goes back to a customer.

    • This can also be referred to as a "follow-on credit"

  • DETACHED_CREDIT: Some payment processors allow you to issue credit to a customer that is not tied to an initial AUTHORIZE or AUTHORIZE_AND_CAPTURE transaction.

    • Most payment gateways disable this feature by default because it is against card association (e.g. Visa, MasterCard) rules.

    • However, there may be legitimate instances where you had a sale transaction but are not able to issue a refund (e.g. closed account of original payment, etc…​)

    • This can also be referred to as a "blind credit" or "stand-alone credit"

PassthroughTransactionService

Out-of-the-box, Broadleaf provides an implementation of the PaymentTransactionService for development-only purposes that doesn’t actual integrate with any payment gateway provider (e.g., PayPal or Stripe) called PassthroughTransactionService. This will allow developers to work on the checkout process without having to immediately handle integrating a payment gateway. It will handle requests to authorize, capture, auth-and-capture, refund, and void with dummy responses that can be used seamlessly in the checkout flow just by enabling it with the property, broadleaf.payment.gateway.passthrough-transactions.active=true. If also using the starter commerce app, set REACT_APP_PAYMENT_GATEWAY_TYPE=PASSTHROUGH; otherwise, make sure to include the gateway type of PASSTHROUGH in the payment’s gateway properties during checkout: paymentGatewayProperties['gatewayType'] = PASSTHROUGH.