Broadleaf Microservices
  • v1.0.0-latest-prod

Payment Transaction Release Notes for 2.0.3-GA

The 2.x versions are Spring Boot 3 compatible.


  • JDK 17 is required for Broadleaf release trains 2.0.0-GA, and beyond.

New Features & Notable Changes

  • Introduced improved support for externally-executed checkout payment transactions

    • Introduced the DefaultPaymentManagementAccessRestrictions#CUSTOMER_MUTABILITY_BLOCKED_FOR_PAYMENT_FINALIZATION which mimics the CUSTOMER_MUTABILITY_BLOCKED access restriction in most functional ways, but it’s used in the specific case of checkout payment finalization.

    • Introduced the ability to callback redirects for 3DS verification & HPP interactions. This is done by generating a security token & adding it to relevant redirect urls at creation time. From there, the ExternalTransactionResultEndpoint#validatePaymentCallbackToken endpoint is used to validate the token provided by the redirect from the payment gateway to CartOps.

      • See how PaymentGatewayPaymentModificationService#getCallbackUrlKeys() implementations are use within DefaultPaymentManagementService#modifyPaymentMethodProperties(…​).

    • Introduced the NextAction object to the PaymentSummary describing the required next action for the payment

  • Introduced anonymous payment TTL logic that also conditionally archives all of the owning entity’s payments based on the broadleaf.paymenttransaction.service.anonymous-payment-ttl-archive-all-owning-entity-payments property.

    • In a multi-payment scenario, this is used to create a clean slate when the first payment expires, instead of waiting for a series of expirations that may be minutes apart.

    • Update the TransactionWebhookMessageService to send enhanced & secure TransactionResultEvent payloads

Bug Fixes

  • Increase the PaymentTransactionReversalJob’s reversal candidate TTL from 15 minutes to 2 hours.

    • This is done to avoid any scenarios where successful payment transactions are reversed while the customer is still interacting with CartOps, attempting to complete their checkout. See this document on cart/payment TTLs for more detail.

  • Remove DefaultPaymentAccessValidationService logic that archives the payment if the requesting customer does not match the registered customer.

  • Updated 3DS & external transaction lookup services to not create a child PaymentTransaction if the lookup result indicates that 3DS verification or an external payment interaction are still required.

  • Add alias names to the "CreatePaymentRequest#isSingleUsePaymentMethod" property to fix an issue when "isSingleUsePaymentMethod" property in the request is not deserialized properly

  • Add validation before updating the payment, to check if the payment is a single-use payment and has successful transactions, or transactions pending a 3DS validation or external interaction. Such payments cannot be updated and should be archived instead

Upgrade Guide

API Changes

New Endpoints

Path Description

POST /validate-payment-callback-token

Validates the external payment interaction callback request and returns the result of that validation.

POST /handle-external-transaction-result/{gatewayType}/hydrated

Reads the transaction result using PaymentGatewayTransactionLookupService, records the result to the appropriate transaction and payment, & returns the full set of PaymentSummaries related to owning entity.

GET /lookup-external-transaction-result/{id}/hydrated

Reads the transaction result using PaymentGatewayTransactionLookupService, and if it exists, records the result to the appropriate transaction and payment, & returns the full set of PaymentSummaries related to owning entity.

Configuration Properties

Added Properties

  • broadleaf.paymenttransaction.service.anonymous-payment-ttl-archive-all-owning-entity-payments

    • Declares whether the owning entity’s payments should all be archived when the anonymous payment TTL has expired for any one of the owning entity’s payments. This additional archival is done to keep the lifecycle of the owning entity’s payments in sync for UX purposes. This is done with the assumption that the owning entity’s payments are associated to the same anonymous user (generally a very safe assumption).

    • Default value: true