spring:
cloud:
stream:
bindings:
checkoutCompletionInputPaymentTransaction:
group: payment-transaction-checkout-completion
destination: checkoutCompletion
- v1.0.0-latest-prod
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.
How and where saved payment methods are stored can be configured using the following property:
Property: broadleaf.paymenttransaction.saved-payment-method.storage-location
Options: BLC_PAYMENT_TRANSACTION_SERVICES, BLC_CUSTOMER_SERVICES
BLC_PAYMENT_TRANSACTION_SERVICES by default.
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).
|
Important
|
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
|
|
Important
|
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:
spring:
cloud:
stream:
bindings:
checkoutCompletionInputPaymentTransaction:
group: payment-transaction-checkout-completion
destination: checkoutCompletionThe 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 are split into two categories: customer-owned saved payment method management vs account-owned saved payment method management.
Customer Saved Payment Method Management (CustomerSavedPaymentMethodManagementEndpoint.java)
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 (AccountSavedPaymentMethodManagementEndpoint.java)
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.
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.
The CustomerSavedPaymentMethodManagementEndpoint and AccountSavedPaymentMethodManagementEndpoint both make use of CreateSavedPaymentMethodRequest.java
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.
|
Note
|
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 is the same for both Customer-owned and Account-owned saved payment methods, both make use of UpdateSavedPaymentMethodRequest.java.
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.
|
Important
|
It’s crucial to understand that you are not allowed to redefine the owningUserType and owningUserId of the saved payment methods
|
When adding or updating a saved payment, an EntityValidator is executed to ensure the required fields are provided:
owningUserType
owningUserId
type
gatewayType
paymentMethodProperties
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.
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.
|
Tip
|
For more details on ownership validation, please refer to Security Documentation |