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 Details

    • 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.

    • blockCustomerMutabilityForPaymentFinalization

      UpdatePaymentsResponse blockCustomerMutabilityForPaymentFinalization(String cartId, Map<String,String> paymentLockTokens, @Nullable com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
      Blocks customer mutability for the cart's payments while payment finalization is completed. Note: this block can be removed via removeCustomerMutabilityBlockForPaymentFinalization(String, Map, ContextInfo) if the customer chooses to opt-out of the finalization interaction.
      Parameters:
      cartId - the id of the payment-owning cart
      paymentLockTokens - Tokens that can be used to unlock the cart's payments
      contextInfo - context information around sandbox and multitenant state.

    • removeCustomerMutabilityBlockForPaymentFinalization

      UpdatePaymentsResponse removeCustomerMutabilityBlockForPaymentFinalization(String cartId, Map<String,String> paymentLockTokens, @Nullable com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
      Unblocks customer mutability for the cart's payments.
      Parameters:
      cartId - the id of the payment-owning cart
      paymentLockTokens - Tokens that can be used to unlock the cart's payments
      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