Interface FinancialTransaction
-
- All Superinterfaces:
- java.io.Serializable
- All Known Implementing Classes:
- FinancialTransactionImpl
public interface FinancialTransaction extends java.io.Serializable
This Interface is a value object container representing a financial transaction.
A
FinancialTransaction
container represents all possible types of financial transactions processed by a plug-in. Depending on the actual transaction type, different attributes will be available.These are the transaction types supported in this specification:
Plug-ins are responsible for updating these containers while processing financial transactions. Several attributes are predefined in the
FinancialTransaction
container. However, the plug-in might also need to add additional information to theFinancialTransaction
container by using the associatedExtendedData
.Response code, reason code, reference number and tracking ID
Theresponse code
is a back-end system specific representation of a financial transaction result. It is typically used by the backend system to indicate if the financial transaction was successful or not. For example, it might indicate that a credit card authorization failed.The
reason code
is a back-end system specific representation of an error condition. It is typically used by the backend system to indicate why a financial transaction failed. For example, it might indicate that a credit card has expired.When the
response code
alone cannot determine what has happened in a financial transaction, thereason code
can be used to precisely determine a financial transaction error.The
response code
and thereason code
can also be seen as primary and secondary error codes. These codes are back-end system specific and used in problem determination whenever the standard plug-in mechanisms do not suffice.The
tracking ID
is an optional attribute used by the plug-in to identify the financial transaction in the payment back-end system on behalf of the merchant. Thetracking ID
is set by the plug-in during the processing of financial transactions. The plug-in generates this ID and has to make sure it is unique in the plug-in and in the backend system realm. Although optional, thetracking ID
might be the only way to track a financial transaction in the backend system if an error occurs. For example, during a financial transaction, the connection can be lost. And the plug-in wouldn't be able to tell if the backend system actually processed the transaction. Thetracking ID
would be the mechanism to query the back-end system later on, once connectivity is reestablished. If thetracking ID
is known by the backend system it means the transaction has reached the backend system. If it is unknown, the transaction needs to be executed again.The
reference number
is an ID generated by the payment back-end system during the processing of financial transactions. Thereference number
is usually required by back-end systems to process subsequent (and related) financial transactions. For example, during adeposit
transaction thereference number
of a previousapprove
transaction is required. In this case, thereference number
is the authorization code returned by the backend system during the approve transaction.While the
tracking ID
is used to identify a financial transaction from the plug-in perspective, thereference number
is used to identify a financial transaction from the payment back-end system perspective. Thetracking ID
is the first identifier of the financial transaction to exist. Once thereference number
is obtained from the backend system, the plug-ins might not need thetracking ID
anymore since thereference number
is known by both parties: the plug-in and the payment back-end system.
-
-
Field Summary
Fields Modifier and Type Field and Description static java.lang.String
COPYRIGHT
The IBM copyright notice field.static short
STATE_CANCELED
The state for the payment or credit transaction when the transaction has been canceled.static short
STATE_FAILED
The state for the payment or credit transaction when the transaction has failed.static short
STATE_NEW
The state of the financial transaction to allow the plugin has chance to control the state transition.static short
STATE_PENDING
The state for the payment or credit transaction when the transaction has not finished yet.static short
STATE_SUCCESS
The state for the payment or credit transaction on a successful execution.static short
TRANSACTION_TYPE_APPROVE
Indicates the transaction is an approval (authorization).static short
TRANSACTION_TYPE_APPROVE_AND_DEPOSIT
Indicates that the transaction is an approval (authorization) and deposit (capture) at the same time.static short
TRANSACTION_TYPE_CREDIT
Indicates that the transaction is a credit transaction.static short
TRANSACTION_TYPE_DEPOSIT
Indicates the transaction is a deposit (capture).static short
TRANSACTION_TYPE_REVERSE_APPROVAL
Indicates that the transaction is an approval (authorization) reversal.static short
TRANSACTION_TYPE_REVERSE_CREDIT
Indicates that the transaction is a credit reversal transaction.static short
TRANSACTION_TYPE_REVERSE_DEPOSIT
Indicates that the transaction is a deposit (capture) reversal.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method and Description Credit
getCredit()
This method gets theCredit
container that is associated with the financial transaction.ExtendedData
getExtendedData()
This method gets the extra data associated with the financial transaction.java.lang.String
getId()
This method gets the unique identifier of theFinancialTransaction
container.Payment
getPayment()
This method gets thePayment
container that is associated with the financial transaction.java.math.BigDecimal
getProcessedAmount()
This method gets the actual processed amount.java.lang.String
getReasonCode()
This method gets the reason for a failed financial transaction.java.lang.String
getReferenceNumber()
This method gets the reference number of the financial transaction.java.math.BigDecimal
getRequestedAmount()
This method gets the amount to be processed in a financial transaction.java.lang.String
getResponseCode()
This method gets the back-end system specific result of the financial transaction.short
getState()
This method gets the state of the financial transaction.java.util.Date
getTimeCreated()
This method gets the time theFinancialTransaction
was created.java.util.Date
getTimeUpdated()
This method gets the most recent time that theFinancialTransaction
was updated.java.lang.String
getTrackingId()
This method gets theFinancialTransaction
tracking ID.short
getTransactionType()
This method gets the type of theFinancialTransaction
.void
setExtendedData(ExtendedData extendedData)
This method adds extended data to theFinancialTransaction
container.void
setProcessedAmount(java.math.BigDecimal processedAmount)
This method sets the amount actually processed in the financial transaction.void
setReasonCode(java.lang.String reasonCode)
This method sets the reason for a failed transaction.void
setReferenceNumber(java.lang.String referenceNumber)
This method sets the reference number of the financial transaction.void
setResponseCode(java.lang.String responseCode)
This method sets the back-end system specific result of the financial transaction.void
setState(short state)
This method sets the state of theFinancialTransaction
.void
setTrackingId(java.lang.String trackingId)
This method sets theFinancialTransaction
tracking identifier.java.lang.String
toString()
This method obtains a human-readable description of the contents of theFinancialTransaction
container.
-
-
-
Field Detail
-
COPYRIGHT
static final java.lang.String COPYRIGHT
The IBM copyright notice field.- See Also:
- Constant Field Values
-
STATE_NEW
static final short STATE_NEW
The state of the financial transaction to allow the plugin has chance to control the state transition. Just before Plugin Controller passes the current financial transaction to plugins, it set the transaction state to STATE_NEW. If the plugin wants to control the state transition of the transaction, the plugin can set any other valid state: STATE_PENDING, STATE_SUCCESS, STATE_FAILED or STATE_CANCELED.- See Also:
- Constant Field Values
-
STATE_PENDING
static final short STATE_PENDING
The state for the payment or credit transaction when the transaction has not finished yet. It might mean that the plug-in implements an offline protocol that requires external intervention to move the payment or credit transaction into another state.- See Also:
- Constant Field Values
-
STATE_SUCCESS
static final short STATE_SUCCESS
The state for the payment or credit transaction on a successful execution.- See Also:
- Constant Field Values
-
STATE_FAILED
static final short STATE_FAILED
The state for the payment or credit transaction when the transaction has failed.- See Also:
- Constant Field Values
-
STATE_CANCELED
static final short STATE_CANCELED
The state for the payment or credit transaction when the transaction has been canceled.- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_APPROVE
static final short TRANSACTION_TYPE_APPROVE
Indicates the transaction is an approval (authorization).- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_DEPOSIT
static final short TRANSACTION_TYPE_DEPOSIT
Indicates the transaction is a deposit (capture).- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_APPROVE_AND_DEPOSIT
static final short TRANSACTION_TYPE_APPROVE_AND_DEPOSIT
Indicates that the transaction is an approval (authorization) and deposit (capture) at the same time. Some refer to this as a sale transaction.- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_CREDIT
static final short TRANSACTION_TYPE_CREDIT
Indicates that the transaction is a credit transaction.- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_REVERSE_APPROVAL
static final short TRANSACTION_TYPE_REVERSE_APPROVAL
Indicates that the transaction is an approval (authorization) reversal.- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_REVERSE_DEPOSIT
static final short TRANSACTION_TYPE_REVERSE_DEPOSIT
Indicates that the transaction is a deposit (capture) reversal.- See Also:
- Constant Field Values
-
TRANSACTION_TYPE_REVERSE_CREDIT
static final short TRANSACTION_TYPE_REVERSE_CREDIT
Indicates that the transaction is a credit reversal transaction.- See Also:
- Constant Field Values
-
-
Method Detail
-
getCredit
Credit getCredit()
This method gets the
Credit
container that is associated with the financial transaction.The
Credit
container will be present only for transactions of the typesTRANSACTION_TYPE_CREDIT
andTRANSACTION_TYPE_REVERSE_CREDIT
.- Returns:
- The
Credit
container associated with thisFinancialTransaction
.
-
setExtendedData
void setExtendedData(ExtendedData extendedData)
This method adds extended data to the
FinancialTransaction
container.The information passed here will be added to the existing extended data associated to the financial transaction. If any mapped value already exists it will be replaced with the new value.
The plug-in invokes this method when additional information needs to be added to the
FinancialTransaction
container during the processing of a financial transaction. The information might be required in subsequent financial transactions.- Parameters:
extendedData
- Map of name-value pairs representing extended payment information.- See Also:
getExtendedData().
-
getExtendedData
ExtendedData getExtendedData()
This method gets the extra data associated with the financial transaction.
- Returns:
- The extended data associated with the financial transaction
- See Also:
setExtendedData(ExtendedData).
-
setReferenceNumber
void setReferenceNumber(java.lang.String referenceNumber)
This method sets the reference number of the financial transaction.
The plug-in needs to invoke this method during the processing of a financial transaction to update the reference number from the payment back-end system. This field is the unique identifier of the financial transaction from the payment back-end system perspective. For more details, please refer to the introduction of this Javadoc.
- Parameters:
referenceNumber
- The unique identifier of the financial transaction from the payment backend system perspective.- See Also:
getReferenceNumber().
-
getReferenceNumber
java.lang.String getReferenceNumber()
This method gets the reference number of the financial transaction.
This field is the unique identifier of the financial transaction from the payment back-end system perspective. For more details, please refer to the introduction of this Javadoc.
- Returns:
- The unique identifier of the financial transaction from the Payment back-end system perspective.
- See Also:
setReferenceNumber(String).
-
getId
java.lang.String getId()
This method gets the unique identifier of the
FinancialTransaction
container.This ID is guaranteed to be unique by the Payment Plug-in Controller.
- Returns:
- A numeric unique identifier of the
FinancialTransaction
container
-
getPayment
Payment getPayment()
This method gets the
Payment
container that is associated with the financial transaction. ThePayment container is only present in financial transactions with these types:
TRANSACTION_TYPE_APPROVE
,TRANSACTION_TYPE_DEPOSIT
,TRANSACTION_TYPE_REVERSE_APPROVAL
,TRANSACTION_TYPE_REVERSE_DEPOSIT
.- Returns:
- The
Payment
container to which thisFinancialTransaction
is associated with.
-
setProcessedAmount
void setProcessedAmount(java.math.BigDecimal processedAmount)
This method sets the amount actually processed in the financial transaction.
This is the amount that was actually processed by the back-end system on the
FinancialTransaction
. This value will typically be the same as the requested amount. Unless the payment protocol used by the backend system supports a different amount to be processed.The plug-in is responsible for setting this amount during the processing of a financial transaction. It is set when the amount processed by the backend system is different from the requested amount. If this amount is not set, the Payment Plug-in Controller will assume that the requested amount was completely processed.
- Parameters:
processedAmount
- The processed amount.- See Also:
getProcessedAmount().
-
getProcessedAmount
java.math.BigDecimal getProcessedAmount()
This method gets the actual processed amount.
- Returns:
- The amount actually processed by the payment back-end system.
- See Also:
setProcessedAmount(BigDecimal).
-
setReasonCode
void setReasonCode(java.lang.String reasonCode)
This method sets the reason for a failed transaction.
The plug-in needs to invoke this method during the processing of a financial transaction to update the failure reason from the payment back-end system. For more details on this field, please refer to the introduction of this Javadoc.
- Parameters:
reasonCode
- The back-end system specific reason for a failed transaction.- See Also:
getReasonCode().
-
getReasonCode
java.lang.String getReasonCode()
This method gets the reason for a failed financial transaction.
For more details on this field, please refer to the introduction of this Javadoc.
- Returns:
- The back-end system specific reason for a failed transaction .
- See Also:
setReasonCode(String).
-
getRequestedAmount
java.math.BigDecimal getRequestedAmount()
This method gets the amount to be processed in a financial transaction.
This amount represents the amount that the system needs to process for any given transaction. The actual processed amount might be different from the requested amount.
- Returns:
- The amount to be processed in a financial transaction.
- See Also:
getProcessedAmount().
,setProcessedAmount(BigDecimal).
-
setResponseCode
void setResponseCode(java.lang.String responseCode)
This method sets the back-end system specific result of the financial transaction.
The plug-in needs to invoke this method during the processing of financial transactions to update the result coming from the payment back-end system. For more details on this field, please refer to the introduction of this Javadoc.
- Parameters:
responseCode
- The back-end system specific result of the financial transaction.- See Also:
getResponseCode().
-
getResponseCode
java.lang.String getResponseCode()
This method gets the back-end system specific result of the financial transaction.
- Returns:
- The back-end system specific result of the financial transaction.
- See Also:
setResponseCode(String).
-
setState
void setState(short state) throws InvalidDataException
This method sets the state of the
FinancialTransaction
.Valid values are:
Usually the Payment Plug-in Controller will invoke this method to update a financial transaction during its lifetime. However, if the plug-in needs to force the financial transaction into a different state, the plug-in can call this method directly.
- Parameters:
state
- The state of theFinancialTransaction
.- Throws:
InvalidDataException
- If an invalid state is passed in.- See Also:
getState()
-
getState
short getState()
This method gets the state of the financial transaction.
Valid values are:
- Returns:
- The state of the financial transaction.
- See Also:
setState(short).
-
getTimeCreated
java.util.Date getTimeCreated()
This method gets the time the
FinancialTransaction
was created.The Payment Plug-in Controller sets this field when the
FinancialTransaction
is created.- Returns:
- The time the
FinancialTransaction
was created.
-
getTimeUpdated
java.util.Date getTimeUpdated()
This method gets the most recent time that the
FinancialTransaction
was updated.The Payment Plug-in Controller updates this field everytime the
FinancialTransaction
changes.- Returns:
- The last time the
FinancialTransaction
was updated.
-
setTrackingId
void setTrackingId(java.lang.String trackingId)
This method sets the
FinancialTransaction
tracking identifier.The plug-in needs to invoke this method when processing a financial transaction to update the tracking ID. This field is the unique identifier of the financial transaction from the plug-in perspective. For more details, please refer to the introduction of this Javadoc.
- Parameters:
trackingId
- The unique identifier of the financial transaction from the plug-in perspective.- See Also:
getTrackingId().
-
getTrackingId
java.lang.String getTrackingId()
This method gets the
FinancialTransaction
tracking ID.This field is the unique identifier of the financial transaction from the plug-in perspective. For more details, please refer to the introduction of this Javadoc.
- Returns:
- The unique identifier of the financial transaction from the plug-in perspective.
- See Also:
setTrackingId(String).
-
getTransactionType
short getTransactionType()
This method gets the type of the
FinancialTransaction
.Valid transaction types are:
TRANSACTION_TYPE_APPROVE
TRANSACTION_TYPE_DEPOSIT
TRANSACTION_TYPE_APPROVE_AND_DEPOSIT
TRANSACTION_TYPE_CREDIT
TRANSACTION_TYPE_REVERSE_APPROVAL
TRANSACTION_TYPE_REVERSE_DEPOSIT
TRANSACTION_TYPE_REVERSE_CREDIT
The Payment Plug-in Controller sets the type of the transaction during its creation.
- Returns:
- The type of the financial transaction.
-
toString
java.lang.String toString()
This method obtains a human-readable description of the contents of the
FinancialTransaction
container.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A human-readable representation of the
FinancialTransaction
container.
-
-