Broadleaf Microservices
  • v1.0.0-latest-prod

Saved Payment Method Management

By default, PaymentTransactionServices handles the storage of saved payment methods. However, an alternative approach of having CustomerServices store saved payment methods (via PaymentAccounts) is also supported. Please see the Configuration section for more details on declaring your desired approach.


Saved Payment Method Storage Location

How and where saved payment methods are stored can be configured using the following property:

  • Property:



When this property is set to BLC_CUSTOMER_SERVICES, CustomerServices will store saved payments (via PaymentAccounts). When it’s set to BLC_PAYMENT_TRANSACTION_SERVICES, PaymentTransactionServices will store them instead (via SavedPaymentMethods).

Saved payment related beans are registered based on this configuration property. For example, PaymentAccount-related beans will only be registered if the property is set to BLC_CUSTOMER_SERVICES
Even though storing and managing saved payment methods via CustomerServices is still supported, it is deprecated and PaymentTransactionServices should be used instead


The CreateSavedPaymentMethodEventListener is designed to ensure that saved payments are still created for unprocessed CheckoutCompletionEvents after upgrading PaymentTransactionServices to 1.0.2.

Due to the updated pattern of producing saved payments just after the successful execution of Authorize or AuthorizeAndCapture transactions, this listener should only be needed for the transitional period of the upgrade, therefore it’s deprecated. Once all the remaining CheckoutCompletionEvents have been processed, the listener can be disabled using the following property:

  • Property: broadleaf.paymenttransaction.saved-payment.checkout-complete-create-listener.enabled

  • Determines whether the CreateSavedPaymentMethodEventListener is enabled

  • Enabled by default

Additionally, the following spring cloud messaging configuration can be removed:

          group: payment-transaction-checkout-completion
          destination: checkoutCompletion

Legacy Permissions

The new CUSTOMER_SAVED_PAYMENT_MANAGEMENT permission was introduced for the CustomerSavedPaymentMethodManagementEndpoint.

The following property can be used to continue using the legacy permissions (CUSTOMER or CUSTOMER_PROFILE):

  • Property: broadleaf.paymenttransaction.web.saved-payment-method.legacy-permission-enabled

  • Determines whether the legacy permissions should be used for CustomerSavedPaymentMethodManagementEndpoint

  • Disabled by default

Saved Payment Method Management Endpoints

Saved payment method management endpoints are split into two categories: customer-owned saved payment method management vs account-owned saved payment method management.

Customer Saved Payment Method Management (

  • Meant for customer-owned saved payment method interactions. For example: adding/updating saved payment methods for customers.

  • Endpoints

    • POST /customers/{customerId}/saved-payment-methods

    • GET /customers/{customerId}/saved-payment-methods

    • PATCH /customers/{customerId}/saved-payment-methods/{savedPaymentMethodId}

    • DELETE /customers/{customerId}/saved-payment-methods/{savedPaymentMethodId}

Account Saved Payment Method Management (

  • Meant for account-owned saved payment method interactions. For example: adding/updating saved payment methods for accounts.

  • Endpoints

    • POST /accounts/{accountId}/saved-payment-methods

    • GET /accounts/{accountId}/saved-payment-methods

    • PATCH /accounts/{accountId}/saved-payment-methods/{savedPaymentMethodId}

    • DELETE /accounts/{accountId}/saved-payment-methods/{savedPaymentMethodId}

For more details on these endpoints, please review the PaymentTransactionServices OpenAPI Docs.

Getting Saved Payment Methods

Saved payment methods are gathered by owner id (i.e. customer id or account id), and the provided owner id is used to validate the ownership of the gathered saved payment methods. For more details on ownership validation, see the Ownership Validation section below.

Adding a Saved Payment Method

The CustomerSavedPaymentMethodManagementEndpoint and AccountSavedPaymentMethodManagementEndpoint both make use of

  • Notable fields:

    • owningUserType - Describes the type of the owning user of the payment method. For example: BLC_CUSTOMER, if the saved payment belongs to a Broadleaf customer.

    • owningUserId - The id of the entity that owns this payment method. For example: a customer id.

    • gatewayType - String identifier for the related payment gateway.

    • defaultForOwner - Whether this saved payment method is the default payment method for the owner entity.

The only difference between the CustomerSavedPaymentMethodManagementEndpoint and the AccountSavedPaymentMethodManagementEndpoint is the authentication attributes used to validate the saved payment method ownership. For more details on ownership validation, see the Ownership Validation section below.

Updating a Saved Payment Method

Updating a saved payment is the same for both Customer-owned and Account-owned saved payment methods, both make use of

The process is quite straightforward, the ownership and version of the saved payment are validated before the update can be made. From there, we simply update the saved payment.

It’s crucial to understand that you are not allowed to redefine the owningUserType and owningUserId of the saved payment methods

Deleting a Saved Payment Method

Deleting a saved payment has a similar process as updating it. First, we validate the ownership is correct and the version is up-to-date. From there, we simply archive the saved payment.

Saved Payment Method Validation

Entity Validation

When adding or updating a saved payment, an EntityValidator is executed to ensure the required fields are provided:

  • owningUserType

  • owningUserId

  • type

  • gatewayType

  • paymentMethodProperties

Version Validation

When updating or deleting a saved payment method, version validation is executed to ensure that the caller is acting upon an up-to-date version before performing any actions. To provide the saved payment version, the X-SavedPayment-Version header should be used.

Ownership Validation

Before performing operations against saved payment methods, we first validate that the authenticated user has access to the saved payment method.

The ownership validation is done by leveraging our @Policy annotation with the OWNER identity type, which validates the ownership by checking the specified owner identifier. Take CustomerSavedPaymentMethodManagementEndpoint as example, since this endpoint is for the management of Customer-owned saved payments, the customer_id claim in the user’s authentication is used to validate the ownership.

For more details on ownership validation, please refer to Security Documentation