Package com.broadleafcommerce.cartoperation.service.provider

Interface PaymentProvider<P extends PaymentSummary>

  • All Known Implementing Classes:
    ExternalPaymentProvider
    public interface PaymentProvider<P extends PaymentSummary>
    Provider for interfacing with a Payment Management system for operations around payment related entities. Typically utilizes WebClient to make requests to an external REST API.
    Author:
    Dima Myroniuk (dmyroniuk), Sunny Yu

    • Method Detail

      • readByCartId

        default List<P> readByCartId​(@NonNull
                             @NonNull String cartId,
                             @Nullable
                             com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Retrieves a list of PaymentSummaries that belong to the given Cart.getId().
        Parameters:
        cartId - the Cart.getId() of the PaymentSummaries to retrieve
        contextInfo - context information around sandbox and multitenant state.
        Returns:
        a list of PaymentSummaries that belong to the given Cart.getId()

      • readAllByOwnerTypeAndOwnerId

        List<P> readAllByOwnerTypeAndOwnerId​(String ownerType,
                                     String ownerId,
                                     @Nullable
                                     com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Retrieves a list of PaymentSummaries that belong to the given owner type and owner id.
        Parameters:
        ownerType - the owner type of the PaymentSummaries to retrieve
        ownerId - the owner id of the PaymentSummaries to retrieve
        contextInfo - context information around sandbox and multitenant state.
        Returns:
        a list of PaymentSummaries based on the given owner type and owner id

      • patchPayment

        default PaymentSummary patchPayment​(@NonNull
                                    @NonNull UpdatePaymentRequest updatePaymentRequest,
                                    @NonNull
                                    @NonNull Integer version,
                                    @Nullable
                                    com.broadleafcommerce.data.tracking.core.context.ContextInfo context)
        Updates the payment based on the provided UpdatePaymentRequest. This method can be used to partially update the payment. To do so provide only the fields you would like to update. The default implementation archives the payment if UpdatePaymentRequest.getAmount() is equal to zero.
        Parameters:
        updatePaymentRequest - the request payload used to update the payment
        version - the payment version
        context - Context information related to multitenancy
        Returns:
        the updated payment summary.

      • patchPayment

        PaymentSummary patchPayment​(UpdatePaymentRequest updatePaymentRequest,
                            Integer version,
                            @Nullable
                            String lockToken,
                            @Nullable
                            com.broadleafcommerce.data.tracking.core.context.ContextInfo context)
        Updates the payment based on the provided UpdatePaymentRequest. This method can be used to partially update the payment. To do so provide only the fields you would like to update. The default implementation archives the payment if UpdatePaymentRequest.getAmount() is equal to zero.
        Parameters:
        updatePaymentRequest - the request payload used to update the payment
        version - the payment version
        lockToken - the token that owns the payment lock
        context - Context information related to multitenancy
        Returns:
        the updated payment summary.

      • archivePayment

        default void archivePayment​(String paymentId,
                            Integer version,
                            @Nullable
                            com.broadleafcommerce.data.tracking.core.context.ContextInfo context)
        Archives the payment based on the provided id and version.
        Parameters:
        paymentId - the context id of the payment
        version - the payment version
        context - context information related to multitenancy

      • archivePayment

        void archivePayment​(String paymentId,
                    Integer version,
                    @Nullable
                    String lockToken,
                    @Nullable
                    com.broadleafcommerce.data.tracking.core.context.ContextInfo context)
        Archives the payment based on the provided id and version.
        Parameters:
        paymentId - the context id of the payment
        version - the payment version
        lockToken - Token that can be used to unlock the cart's payment
        context - context information related to multitenancy

      • lockCartPayments

        Map<String,​String> lockCartPayments​(com.broadleafcommerce.cart.client.domain.Cart cart,
                                          @Nullable
                                          com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Locks the cart's payments to ensure that all of the work done within the CheckoutWorkflow and checkout process in general is consistently interacting with payments that will not change. With these locks in place, only this executing process will have access to modify the payments, until the lock TTL expires. Note: make sure that the checkout process can sufficiently be contained within the payment lock TTL. This can be configured in PaymentTransactionServices.
        Parameters:
        cart - the Cart whose payments are to be locked.
        contextInfo - context information around sandbox and multitenant state.
        Returns:
        A map of payment id to lock token.
        Throws:
        PaymentLockException - if a lock could not be obtained.

      • lockAndRetrieveCartPayments

        LockPaymentsResponse lockAndRetrieveCartPayments​(com.broadleafcommerce.cart.client.domain.Cart cart,
                                                 @Nullable
                                                 com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Same functionality as lockCartPayments(Cart, ContextInfo) but this method also includes the PaymentSummaries in the response.

        This is useful to reduce the amount of network calls.

        Parameters:
        cart - the Cart whose payments are to be locked.
        contextInfo - context information around sandbox and multitenant state.
        Returns:
        A LockPaymentsResponse containing the payment locks and PaymentSummaries
        Throws:
        PaymentLockException - if a lock could not be obtained.

      • unlockCartPayments

        void unlockCartPayments​(Collection<String> lockTokens,
                        @Nullable
                        com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Unlocks the cart's payments, based on the lock tokens that were previously obtained via lockCartPayments(Cart, ContextInfo).
        Parameters:
        lockTokens - Tokens that can be used to unlock the cart's payments

      • finalizePaymentsForCheckout

        UpdatePaymentsResponse finalizePaymentsForCheckout​(String ownerId,
                                                   Map<String,​String> paymentLockTokens,
                                                   @Nullable
                                                   com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        The PaymentTransactionServices internally prepares and finalizes the payments for checkout.
        Parameters:
        ownerId - the owner id of the PaymentSummaries to finalize
        paymentLockTokens - Tokens that can be used to unlock the cart's payments
        contextInfo - context information around sandbox and multitenant state.

      • blockCustomerMutabilityForPayments

        UpdatePaymentsResponse blockCustomerMutabilityForPayments​(String ownerId,
                                                          Map<String,​String> paymentLockTokens,
                                                          boolean markTransactionsIneligibleForAutoReversal,
                                                          @Nullable
                                                          com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Blocks customer mutability for the cart's payments.
        Parameters:
        ownerId - the owner id of the PaymentSummaries to finalize
        paymentLockTokens - Tokens that can be used to unlock the cart's payments
        markTransactionsIneligibleForAutoReversal - Determines if the payments' transactions should be marked ineligible for automatic reversal
        contextInfo - context information around sandbox and multitenant state.

      • transferPaymentsToCSR

        UpdatePaymentsResponse transferPaymentsToCSR​(String ownerId,
                                             Map<String,​String> paymentLockTokens,
                                             @Nullable
                                             com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        The PaymentTransactionServices internally prepares and transfers the payments to the CSR user. The expectation is that the payments will no longer be owned by the customer and cannot be accessed except by the CSR user.
        Parameters:
        ownerId - the owner id of the PaymentSummaries to transfer
        paymentLockTokens - Tokens that can be used to unlock the cart's payments
        contextInfo - context information around sandbox and multitenant state.

      • transferPaymentsToCSR

        default UpdatePaymentsResponse transferPaymentsToCSR​(String ownerId,
                                                     @Nullable
                                                     com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)

      • transferPaymentsToCustomer

        UpdatePaymentsResponse transferPaymentsToCustomer​(String ownerId,
                                                  Map<String,​String> paymentLockTokens,
                                                  @Nullable
                                                  com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        The PaymentTransactionServices internally prepares and transfers the payments to the customer user.
        Parameters:
        ownerId - the owner id of the PaymentSummaries to transfer
        paymentLockTokens - Tokens that can be used to unlock the cart's payments
        contextInfo - context information around sandbox and multitenant state.

      • transferPaymentsToCustomer

        default UpdatePaymentsResponse transferPaymentsToCustomer​(String ownerId,
                                                          @Nullable
                                                          com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)

      • claimTransactionsForRequest

        @Deprecated(since="1.7.6",
            forRemoval=true)
default void claimTransactionsForRequest​(String paymentId,
                                         String requestId,
                                         String transactionType,
                                         boolean resetTransactionReversalState,
                                         @Nullable
                                         String lockToken,
                                         @Nullable
                                         com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Deprecated, for removal: This API element is subject to removal in a future version.
        since 1.7.6, in favor of claimTransactionsForRequest(ClaimCheckoutTransactionsRequest, ContextInfo)
        Updates the payment transaction request id with the new value, stores the previous value, clears transaction management state and management state reason.
        Parameters:
        paymentId - the payment id
        requestId - id used to represent the request that produced this transaction e.g during checkout
        transactionType - the transaction type
        resetTransactionReversalState - reset or not the state of the transaction reversal
        lockToken - token granted to resource that owns the payment lock
        contextInfo - context information related to multitenancy

      • claimTransactionsForRequest

        PaymentSummary claimTransactionsForRequest​(ClaimCheckoutTransactionsRequest request,
                                           @Nullable
                                           com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
        Updates the payment transaction request id with the new value, stores the previous value, clears transaction management state and management state reason.
        Parameters:
        request - the ClaimCheckoutTransactionsRequest to claim the transactions for a checkout request
        contextInfo - context information related to multitenancy