Package com.broadleafcommerce.cartoperation.domain.payment

Class PaymentTransactionRef

java.lang.Object
com.broadleafcommerce.cartoperation.domain.payment.PaymentTransactionRef
All Implemented Interfaces:
Serializable
public class PaymentTransactionRef extends Object implements Serializable
A reference to a payment transaction.
Author:
Chris Kittrell (ckittrell)
See Also:

  • Constructor Details

    • PaymentTransactionRef

      public PaymentTransactionRef()

  • Method Details

    • wasSuccessful

      public boolean wasSuccessful()
      Whether this transaction was successful based on getStatus().
      Returns:
      Whether this transaction was successful.
      See Also:

    • getCurrency

      @Nullable public javax.money.CurrencyUnit getCurrency()
      The currency gathered from getAmount()
      Returns:
      The currency gathered from the amount

    • getId

      public String getId()
      The payment transaction's id.
      Returns:
      The payment transaction's id.

    • getParentTransactionId

      public String getParentTransactionId()
      The id of the parent payment transaction. Necessary for operations on a payment that require something to have happened beforehand. For instance, an authorize transaction would not have a parent but a capture must have an authorize parent transaction and a refund must have a capture parent transaction. The full set of expected parent-child transaction relationships are as follows:
      • Child Transaction -> Parent Transaction
      • Reverse Authorize -> Authorize
      • Capture -> Authorize
      • Refund -> Capture
      • Refund -> AuthorizeAndCapture
      Returns:
      The id of the parent PaymentTransaction.

    • getPaymentId

      public String getPaymentId()
      The payment's id.
      Returns:
      The payment's id.

    • getRequestId

      public String getRequestId()
      The id used to represent the request that produced this transaction.
      Returns:
      The id used to represent the request that produced this transaction

    • getPreviousRequestIds

      public List<String> getPreviousRequestIds()
      The list of requestIds that were previously used for this transaction.

      Note: if the transaction is reused for multiple requests, then the requestId should be updated with the latest value, & the previous value should be stored in this collection.

      Returns:
      The list of request ids that were previously used for this transaction.

    • getTransactionReferenceId

      public String getTransactionReferenceId()
      The transaction id known by the payment gateway.

      This reference can be used to link the request to the gateway's record of the transaction in the case that the calling application does not receive a response from the gateway.

      Returns:
      The transaction id known by the payment gateway

    • getGatewayTransactionId

      public String getGatewayTransactionId()
      The gateway-specific id for the transaction.
      Returns:
      The gateway-specific id for the transaction

    • getType

      public String getType()
      The type of this transaction (authorize, capture, refund, etc.)
      Returns:
      The type of this transaction (authorize, capture, refund, etc.)

    • getGatewayTransactionType

      public String getGatewayTransactionType()
      The type of this transaction, as described by the gateway.
      Returns:
      The type of this transaction, as described by the gateway.

    • getStatus

      public String getStatus()
      The status of the transaction
      Returns:
      The status of the transaction
      See Also:

    • getGatewayResponseCode

      public String getGatewayResponseCode()
      The response code provided by the payment gateway which may represent a success or failure
      Returns:
      The response code provided by the payment gateway which may represent a success or failure

    • getFailureType

      public String getFailureType()
      The type of transaction failure
      Returns:
      The type of transaction failure

    • getAmount

      public javax.money.MonetaryAmount getAmount()
      The amount related to this transaction. Depending on the type, this may be the amount authorized, captured, refunded, etc.
      Returns:
      The amount related to this transaction

    • getSubtotal

      public javax.money.MonetaryAmount getSubtotal()
      The payment's total usually excluding adjustments, tax, fees, and shipping.

      Note: Only the amount is required, but if this value is included, then the fulfillmentTotal, feesTotal, adjustmentsTotal, taxTotal, & includedTaxTotal should be included also.

      Returns:
      The payment's total usually excluding adjustments, tax, fees, and shipping.

    • getAdjustmentsTotal

      public javax.money.MonetaryAmount getAdjustmentsTotal()
      The payment's adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, feesTotal, taxTotal, & includedTaxTotal should be included also.

      Returns:
      The payment's adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.

    • getFulfillmentTotal

      public javax.money.MonetaryAmount getFulfillmentTotal()
      The payment's total fulfillment cost.

      Note: Only the amount is required, but if this value is included, then the subtotal, feesTotal, adjustmentsTotal, taxTotal, & includedTaxTotal should be included also.

      Returns:
      The payment's total fulfillment cost.

    • getFeesTotal

      public javax.money.MonetaryAmount getFeesTotal()
      The total fees related to the amount

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, adjustmentsTotal, taxTotal, & includedTaxTotal should be included also.

      Returns:
      The total fees related to the amount

    • getTaxTotal

      public javax.money.MonetaryAmount getTaxTotal()
      The payment's total tax cost.

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, feesTotal, adjustmentsTotal, & includedTaxTotal should be included also.

      Returns:
      The payment's total tax cost.

    • getIncludedTaxTotal

      public javax.money.MonetaryAmount getIncludedTaxTotal()
      The amount of taxes that are included in the subtotal (VAT).

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, feesTotal, adjustmentsTotal, & taxTotal should be included also.

      Returns:
      The amount of taxes that are included in the subtotal (VAT).

    • getSource

      public String getSource()
      The name of the system that initiated the transaction - e.g. CART_OPERATION_SERVICES vs ORDER_OPERATION_SERVICES.
      Returns:
      The name of the system that initiated the transaction

    • getSourceEntityType

      public String getSourceEntityType()
      The type of the source entity associated with the transaction. For example, "CHECKOUT_REQUEST" or "ORDER_FULFILLMENT".
      Returns:
      The type of the source entity associated with the transaction

    • getSourceEntityId

      public String getSourceEntityId()
      The ID of the source entity associated with the transaction.

      For example, if getSourceEntityType() is ORDER_FULFILLMENT, this would be the ID of the OrderFulfillment.

      Returns:
      The ID of the source entity associated with the transaction
      See Also:

    • getParentSourceEntityType

      public String getParentSourceEntityType()
      The type of the parent source entity of the transaction that proceeded this transaction.

      This is used to identify the parent transaction instead of using the parent transaction id itself, because other systems have no knowledge of specific transactions.

      For example, the execution of a refund transaction requires a proceeding capture or authorize and capture transaction. Let's say the proceeding capture transaction has the source entity type of ORDER_FULFILLMENT, and the refund transaction has the entity source type of RETURN_CONFIRMATION. In this case, the refund transaction request needs the parent source entity type of ORDER_FULFILLMENT and its id in order to identify the parent capture transaction.

      Returns:
      The type of the parent source entity of the transaction that proceeded this transaction

    • getParentSourceEntityId

      public String getParentSourceEntityId()
      The id of the parent source entity of the transaction that proceeded this transaction.
      Returns:
      The id of the parent source entity of the transaction that proceeded this transaction
      See Also:

    • getManagementState

      public String getManagementState()
      The state of this transaction - e.g. whether the transaction is scheduled for reversal or if it's being used in an active checkout. If the transaction was not successful, then we expect this value to be null.
      Returns:
      The state of this transaction

    • getManagementStateReason

      public String getManagementStateReason()
      Describes the reason for the managementState.
      Returns:
      The reason for the managementState value

    • isFlaggedForManualReview

      public boolean isFlaggedForManualReview()
      Indicates that the payment transaction has been flagged for manual review via fraud checks.
      Returns:
      true if the transaction flagged for manual review

    • getManualReviewResult

      public String getManualReviewResult()
      Describes the outcome of the manual review of a transaction after it was flagged by fraud checks.
      Returns:
      The outcome of the manual review of a transaction after it was flagged by fraud checks.

    • getManualReviewResultReason

      public String getManualReviewResultReason()
      Describes the reason for approving/rejecting a transaction during a manual fraud review.
      Returns:
      The reason for approving/rejecting a transaction during a manual fraud review.

    • getDateRecorded

      public Instant getDateRecorded()
      The timestamp when this transaction response was recorded
      Returns:
      The timestamp when this transaction response was recorded

    • isIndeterminateResult

      public boolean isIndeterminateResult()
      Tells if this transaction has an indeterminate result.

      Having an indeterminate result means that the true outcome of the transaction is not known. For example, if a transaction is sent to the payment processor but a network error occurred, it is not known to us whether the user was actually charged or not (thus, the result is indeterminate).

      Transactions should be marked as indeterminate when sending to the payment processor, and then unmarked once a response is received, understood, and recorded. This means that a transaction in an indeterminate result state is expected during the sending to processor phase. However, if the transaction remains in that state for an excessive amount of time, something likely went wrong and the transaction will need to be reconciled. If the transaction changes from the sending to processor status but remains indeterminate, the transaction will also require reconciliation in that scenario.

      Some situations which may lead to an indeterminate result:

      • A transaction is sent to the processor, but a network error prevents us from receiving the response
      • A transaction is sent to the processor, but the processor returns an unexpected error (e.g. 500 internal server error)
      • A transaction is sent to the processor and a response is received, but cannot be recorded because Cart Services is down
      • A transaction is sent to the processor and a response is received, but cannot be recorded because the database is down

    • getNextAction

      public NextAction getNextAction()
      The next step required for the payment gateway to continue processing this payment.
      Returns:
      The next step required for the payment gateway to continue processing this payment.

    • getAttributes

      public Map<String,String> getAttributes()
      Map of specific attributes that have been gathered from the raw response. This should be used for data points that are to be used programmatically. For example, a gateway-specific transaction id that can be used to capture or refund the transaction.
      Returns:
      Map of specific fields that have been gathered from the raw response

    • setId

      public void setId(String id)
      The payment transaction's id.
      Parameters:
      id - The payment transaction's id.

    • setParentTransactionId

      public void setParentTransactionId(String parentTransactionId)
      The id of the parent payment transaction. Necessary for operations on a payment that require something to have happened beforehand. For instance, an authorize transaction would not have a parent but a capture must have an authorize parent transaction and a refund must have a capture parent transaction. The full set of expected parent-child transaction relationships are as follows:
      • Child Transaction -> Parent Transaction
      • Reverse Authorize -> Authorize
      • Capture -> Authorize
      • Refund -> Capture
      • Refund -> AuthorizeAndCapture
      Parameters:
      parentTransactionId - The id of the parent PaymentTransaction.

    • setPaymentId

      public void setPaymentId(String paymentId)
      The payment's id.
      Parameters:
      paymentId - The payment's id.

    • setRequestId

      public void setRequestId(String requestId)
      The id used to represent the request that produced this transaction.
      Parameters:
      requestId - The id used to represent the request that produced this transaction

    • setPreviousRequestIds

      public void setPreviousRequestIds(List<String> previousRequestIds)
      The list of requestIds that were previously used for this transaction.

      Note: if the transaction is reused for multiple requests, then the requestId should be updated with the latest value, & the previous value should be stored in this collection.

      Parameters:
      previousRequestIds - The list of request ids that were previously used for this transaction.

    • setTransactionReferenceId

      public void setTransactionReferenceId(String transactionReferenceId)
      The transaction id known by the payment gateway.

      This reference can be used to link the request to the gateway's record of the transaction in the case that the calling application does not receive a response from the gateway.

      Parameters:
      transactionReferenceId - The transaction id known by the payment gateway

    • setGatewayTransactionId

      public void setGatewayTransactionId(String gatewayTransactionId)
      The gateway-specific id for the transaction.
      Parameters:
      gatewayTransactionId - The gateway-specific id for the transaction

    • setType

      public void setType(String type)
      The type of this transaction (authorize, capture, refund, etc.)
      Parameters:
      type - The type of this transaction

    • setGatewayTransactionType

      public void setGatewayTransactionType(String gatewayTransactionType)
      The type of this transaction, as described by the gateway.
      Parameters:
      gatewayTransactionType - The type of this transaction, as described by the gateway.

    • setStatus

      public void setStatus(String status)
      The status of the transaction
      Parameters:
      status - The status of the transaction
      See Also:

    • setGatewayResponseCode

      public void setGatewayResponseCode(String gatewayResponseCode)
      The response code provided by the payment gateway which may represent a success or failure
      Parameters:
      gatewayResponseCode - The response code provided by the payment gateway which may represent a success or failure

    • setFailureType

      public void setFailureType(String failureType)
      The type of transaction failure
      Parameters:
      failureType - The type of transaction failure

    • setAmount

      public void setAmount(javax.money.MonetaryAmount amount)
      The amount related to this transaction. Depending on the type, this may be the amount authorized, captured, refunded, etc.
      Parameters:
      amount - The amount related to this transaction

    • setSubtotal

      public void setSubtotal(javax.money.MonetaryAmount subtotal)
      The payment's total usually excluding adjustments, tax, fees, and shipping.

      Note: Only the amount is required, but if this value is included, then the fulfillmentTotal, feesTotal, adjustmentsTotal, taxTotal, & includedTaxTotal should be included also.

      Parameters:
      subtotal - The payment's total usually excluding adjustments, tax, fees, and shipping.

    • setAdjustmentsTotal

      public void setAdjustmentsTotal(javax.money.MonetaryAmount adjustmentsTotal)
      The payment's adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, feesTotal, taxTotal, & includedTaxTotal should be included also.

      Parameters:
      adjustmentsTotal - The payment's adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.

    • setFulfillmentTotal

      public void setFulfillmentTotal(javax.money.MonetaryAmount fulfillmentTotal)
      The payment's total fulfillment cost.

      Note: Only the amount is required, but if this value is included, then the subtotal, feesTotal, adjustmentsTotal, taxTotal, & includedTaxTotal should be included also.

      Parameters:
      fulfillmentTotal - The payment's total fulfillment cost.

    • setFeesTotal

      public void setFeesTotal(javax.money.MonetaryAmount feesTotal)
      The total fees related to the amount

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, adjustmentsTotal, taxTotal, & includedTaxTotal should be included also.

      Parameters:
      feesTotal - The total fees related to the amount

    • setTaxTotal

      public void setTaxTotal(javax.money.MonetaryAmount taxTotal)
      The payment's total tax cost.

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, feesTotal, adjustmentsTotal, & includedTaxTotal should be included also.

      Parameters:
      taxTotal - The payment's total tax cost.

    • setIncludedTaxTotal

      public void setIncludedTaxTotal(javax.money.MonetaryAmount includedTaxTotal)
      The amount of taxes that are included in the subtotal (VAT).

      Note: Only the amount is required, but if this value is included, then the subtotal, fulfillmentTotal, feesTotal, adjustmentsTotal, & taxTotal should be included also.

      Parameters:
      includedTaxTotal - The amount of taxes that are included in the subtotal (VAT).

    • setSource

      public void setSource(String source)
      The name of the system that initiated the transaction - e.g. CART_OPERATION_SERVICES vs ORDER_OPERATION_SERVICES.
      Parameters:
      source - The name of the system that initiated the transaction

    • setSourceEntityType

      public void setSourceEntityType(String sourceEntityType)
      The type of the source entity associated with the transaction. For example, "CHECKOUT_REQUEST" or "ORDER_FULFILLMENT".
      Parameters:
      sourceEntityType - The type of the source entity associated with the transaction

    • setSourceEntityId

      public void setSourceEntityId(String sourceEntityId)
      The ID of the source entity associated with the transaction.

      For example, if getSourceEntityType() is ORDER_FULFILLMENT, this would be the ID of the OrderFulfillment.

      Parameters:
      sourceEntityId - The ID of the source entity associated with the transaction
      See Also:

    • setParentSourceEntityType

      public void setParentSourceEntityType(String parentSourceEntityType)
      The type of the parent source entity of the transaction that proceeded this transaction.

      This is used to identify the parent transaction instead of using the parent transaction id itself, because other systems have no knowledge of specific transactions.

      For example, the execution of a refund transaction requires a proceeding capture or authorize and capture transaction. Let's say the proceeding capture transaction has the source entity type of ORDER_FULFILLMENT, and the refund transaction has the entity source type of RETURN_CONFIRMATION. In this case, the refund transaction request needs the parent source entity type of ORDER_FULFILLMENT and its id in order to identify the parent capture transaction.

      Parameters:
      parentSourceEntityType - The type of the parent source entity of the transaction that proceeded this transaction

    • setParentSourceEntityId

      public void setParentSourceEntityId(String parentSourceEntityId)
      The id of the parent source entity of the transaction that proceeded this transaction.
      Parameters:
      parentSourceEntityId - The id of the parent source entity of the transaction that proceeded this transaction
      See Also:

    • setManagementState

      public void setManagementState(String managementState)
      The state of this transaction - e.g. whether the transaction is scheduled for reversal or if it's being used in an active checkout. If the transaction was not successful, then we expect this value to be null.
      Parameters:
      managementState - The state of this transaction

    • setManagementStateReason

      public void setManagementStateReason(String managementStateReason)
      Describes the reason for the managementState.
      Parameters:
      managementStateReason - The reason for the managementState value

    • setFlaggedForManualReview

      public void setFlaggedForManualReview(boolean flaggedForManualReview)
      Indicates that the payment transaction has been flagged for manual review via fraud checks.
      Parameters:
      flaggedForManualReview - whether the transaction is marked for manual review

    • setManualReviewResult

      public void setManualReviewResult(String manualReviewResult)
      Describes the outcome of the manual review of a transaction after it was flagged by fraud checks.
      Parameters:
      manualReviewResult - The outcome of the manual review of a transaction after it was flagged by fraud checks.

    • setManualReviewResultReason

      public void setManualReviewResultReason(String manualReviewResultReason)
      Describes the reason for approving/rejecting a transaction during a manual fraud review.
      Parameters:
      manualReviewResultReason - The reason for approving/rejecting a transaction during a manual fraud review.

    • setDateRecorded

      public void setDateRecorded(Instant dateRecorded)
      The timestamp when this transaction response was recorded
      Parameters:
      dateRecorded - The timestamp when this transaction response was recorded

    • setIndeterminateResult

      public void setIndeterminateResult(boolean indeterminateResult)
      Tells if this transaction has an indeterminate result.

      Having an indeterminate result means that the true outcome of the transaction is not known. For example, if a transaction is sent to the payment processor but a network error occurred, it is not known to us whether the user was actually charged or not (thus, the result is indeterminate).

      Transactions should be marked as indeterminate when sending to the payment processor, and then unmarked once a response is received, understood, and recorded. This means that a transaction in an indeterminate result state is expected during the sending to processor phase. However, if the transaction remains in that state for an excessive amount of time, something likely went wrong and the transaction will need to be reconciled. If the transaction changes from the sending to processor status but remains indeterminate, the transaction will also require reconciliation in that scenario.

      Some situations which may lead to an indeterminate result:

      • A transaction is sent to the processor, but a network error prevents us from receiving the response
      • A transaction is sent to the processor, but the processor returns an unexpected error (e.g. 500 internal server error)
      • A transaction is sent to the processor and a response is received, but cannot be recorded because Cart Services is down
      • A transaction is sent to the processor and a response is received, but cannot be recorded because the database is down

    • setNextAction

      public void setNextAction(NextAction nextAction)
      The next step required for the payment gateway to continue processing this payment.
      Parameters:
      nextAction - The next step required for the payment gateway to continue processing this payment.

    • setAttributes

      public void setAttributes(Map<String,String> attributes)
      Map of specific attributes that have been gathered from the raw response. This should be used for data points that are to be used programmatically. For example, a gateway-specific transaction id that can be used to capture or refund the transaction.
      Parameters:
      attributes - Map of specific fields that have been gathered from the raw response

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • canEqual

      protected boolean canEqual(Object other)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object