Class PaymentTransaction
- All Implemented Interfaces:
Serializable
Used to store individual transactions about a particular payment. While a
PaymentValidationRequest
holds data like what the user might be paying with and the total
amount they will be paying (like credit card and $10), a PaymentTransaction
is used to
record transactional interactions with a payment gateway for a particular payment. Thus,
PaymentTransactions
do not make sense by themselves and ONLY make
sense in the context of a PaymentValidationRequest
.
For instance, the user might pay $10, but rather than capture the payment during checkout, the business may first want to use & record an authorize-typed transaction. Later, when the business ships the item, a capture-typed transaction would be used & recorded.
In the above case, this also implies that a PaymentTransaction
can have a parent
transaction (retrieved via getParentTransactionId()
). The parent transaction will
only be set in the following cases:
- Child Transaction -> Parent Transaction
- Reverse Authorize -> Authorize
- Capture -> Authorize
- Refund -> Capture
- Refund -> AuthorizeAndCapture
- Author:
- Phillip Verheyden (phillipuniverse), Chris Kittrell (ckittrell)
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected boolean
boolean
javax.money.MonetaryAmount
The amount related to this transaction.Map of specific attributes that have been gathered from the raw response.javax.money.CurrencyUnit
The currency gathered fromgetAmount()
The customer IP address that instigated this transactionThe timestamp when this transaction response was recordedThe type of transaction failure (hard vs soft failure)The type of transaction failureMessage from the gateway describing the result of the transaction.The response code provided by the payment gateway which may represent a success or failureThe gateway-specific id for the transaction.getId()
The id of this payment transaction.The state of this transaction - e.g.The id of the parentPaymentTransaction
.The string representation of the serialized response from the gateway.The id used to represent the request that produced this transaction.The name of the system that initiated the transaction - e.g.The status of the transactionThe transaction id known by the payment gateway.getType()
The type of this transaction (authorize, capture, refund, etc.)The version of this payment transaction.int
hashCode()
boolean
Tells if this transaction has an indeterminate result.void
setAmount
(javax.money.MonetaryAmount amount) The amount related to this transaction.void
setAttributes
(Map<String, String> attributes) Map of specific attributes that have been gathered from the raw response.void
setCustomerIpAddress
(String customerIpAddress) The customer IP address that instigated this transactionvoid
setDateRecorded
(Instant dateRecorded) The timestamp when this transaction response was recordedvoid
setDeclineType
(String declineType) The type of transaction failure (hard vs soft failure)void
setFailureType
(String failureType) The type of transaction failurevoid
setGatewayMessage
(String gatewayMessage) Message from the gateway describing the result of the transaction.void
setGatewayResponseCode
(String gatewayResponseCode) The response code provided by the payment gateway which may represent a success or failurevoid
setGatewayTransactionId
(String gatewayTransactionId) The gateway-specific id for the transaction.void
The id of this payment transaction.void
setIndeterminateResult
(boolean indeterminateResult) Tells if this transaction has an indeterminate result.void
setManagementState
(String managementState) The state of this transaction - e.g.void
setNextAction
(NextAction nextAction) The next step required for the payment gateway to continue processing this payment.void
setParentTransactionId
(String parentTransactionId) The id of the parentPaymentTransaction
.void
setRawResponse
(String rawResponse) The string representation of the serialized response from the gateway.void
setRequestId
(String requestId) The id used to represent the request that produced this transaction.void
The name of the system that initiated the transaction - e.g.void
The status of the transactionvoid
setThreeDSecureVerificationUrl
(String threeDSecureVerificationUrl) Deprecated.void
setTransactionReferenceId
(String transactionReferenceId) The transaction id known by the payment gateway.void
The type of this transaction (authorize, capture, refund, etc.)void
setVersion
(Integer version) The version of this payment transaction.toString()
-
Constructor Details
-
PaymentTransaction
public PaymentTransaction()
-
-
Method Details
-
getThreeDSecureVerificationUrl
-
getNextAction
-
getCurrency
@Nullable public javax.money.CurrencyUnit getCurrency()The currency gathered fromgetAmount()
- Returns:
- The currency gathered from the amount
-
getId
The id of this payment transaction.- Returns:
- The id of this payment transaction.
-
getType
The type of this transaction (authorize, capture, refund, etc.)- Returns:
- The type of this transaction (authorize, capture, refund, etc.)
-
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
-
getStatus
The status of the transaction- Returns:
- The status of the transaction
-
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
The gateway-specific id for the transaction.- Returns:
- The gateway-specific id for the transaction
-
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
-
getRequestId
The id used to represent the request that produced this transaction. This is normally related to a checkout submission request.- Returns:
- The id used to represent the request that produced this transaction
-
getAmount
public javax.money.MonetaryAmount getAmount()The amount related to this transaction. Depending on thetype
, this may be the amount authorized, captured, refunded, etc.- Returns:
- The amount related to this transaction
-
getDateRecorded
The timestamp when this transaction response was recorded- Returns:
- The timestamp when this transaction response was recorded
-
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
The type of transaction failure- Returns:
- The type of transaction failure
-
getDeclineType
The type of transaction failure (hard vs soft failure)- Returns:
- The type of transaction failure (hard vs soft failure)
-
getGatewayMessage
Message from the gateway describing the result of the transaction.- Returns:
- Message from the gateway describing the result of the transaction.
-
getRawResponse
The string representation of the serialized response from the gateway. This is usually the complete request parameter map serialized in string form.- Returns:
- The string representation of the serialized response from the gateway
-
getParentTransactionId
The id of the parentPaymentTransaction
. 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.
-
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
-
getCustomerIpAddress
The customer IP address that instigated this transaction- Returns:
- The customer IP address that instigated this transaction
-
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
-
getVersion
The version of this payment transaction. Used for checking that the requested version of the payment transaction is up-to-date before saving changes. Required for any request which results in an update being made to the payment transaction. This should never be manually incremented/decremented. -
setId
The id of this payment transaction.- Parameters:
paymentTransactionId
- The id of this payment transaction.
-
setType
The type of this transaction (authorize, capture, refund, etc.)- Parameters:
amount
- The type of this transaction
-
setManagementState
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
-
setStatus
The status of the transaction- Parameters:
status
- The status of the transaction
-
setTransactionReferenceId
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
The gateway-specific id for the transaction.- Parameters:
gatewayTransactionId
- The gateway-specific id for the transaction
-
setSource
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
-
setRequestId
The id used to represent the request that produced this transaction. This is normally related to a checkout submission request.- Parameters:
requestId
- The id used to represent the request that produced this transaction
-
setAmount
public void setAmount(javax.money.MonetaryAmount amount) The amount related to this transaction. Depending on thetype
, this may be the amount authorized, captured, refunded, etc.- Parameters:
amount
- The amount related to this transaction
-
setDateRecorded
The timestamp when this transaction response was recorded- Parameters:
dateRecorded
- The timestamp when this transaction response was recorded
-
setGatewayResponseCode
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
The type of transaction failure- Parameters:
failureType
- The type of transaction failure
-
setDeclineType
The type of transaction failure (hard vs soft failure)- Parameters:
failureType
- The type of transaction failure (hard vs soft failure)
-
setThreeDSecureVerificationUrl
Deprecated.in favor ofnextAction
The gateway-provided url where the customer must verify that they are in fact the owner of the payment method. The customer is typically redirected to this location, but the page can also be rendered within an iframe if you'd like.- Parameters:
threeDSecureVerificationUrl
- The gateway-provided url where the customer must verify that they are in fact the owner of the payment method.
-
setGatewayMessage
Message from the gateway describing the result of the transaction.- Parameters:
gatewayMessage
- Message from the gateway describing the result of the transaction.
-
setRawResponse
The string representation of the serialized response from the gateway. This is usually the complete request parameter map serialized in string form.- Parameters:
rawResponse
- The string representation of the serialized response from the gateway
-
setParentTransactionId
The id of the parentPaymentTransaction
. 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.
-
setAttributes
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
-
setCustomerIpAddress
The customer IP address that instigated this transaction- Parameters:
customerIpAddress
- The customer IP address that instigated this transaction
-
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
-
setVersion
The version of this payment transaction. Used for checking that the requested version of the payment transaction is up-to-date before saving changes. Required for any request which results in an update being made to the payment transaction. This should never be manually incremented/decremented. -
setNextAction
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.
-
equals
-
canEqual
-
hashCode
public int hashCode() -
toString
-
nextAction