public interface Payment
extends java.io.Serializable
This interface is a value object container for payment-related transactions.
This container can contain a single payment approval (authorization) and multiple deposits (captures) for the same approval/capture. However, multiple deposits (captures) per a single approval (authorization) might not be supported by the payment back-end system.
The Payment container is created before the approval (authorization) transaction and it is used in subsequent transactions like deposits (captures) and reversals.
The Payment Plug-in Controller guarantees that:
Payments are always associated with a PaymentInstruction container. A PaymentInstruction keeps references to all Payment containers and all Credit containers associated with it.
Online and offline processing
Online refers to the processing of financial transactions that do not require external intervention for successful execution. In other words, the complete processing of the financial transaction is done electronically and automatically without needing any external (human) intervention.
Offline refers to the processing of financial transactions that require external intervention for successful execution. For example, when a credit card needs to be processed over the phone or through a swipe box. The processing of the credit card is considered offline.
Payment state machine
Modifier and Type | Field and Description |
---|---|
static short | AVS_COMPLETE_MATCH
Address Verification Service Code: Street addresses and postal codes match.
|
static short | AVS_NO_MATCH
Address Verification Service Code: Neither street addresses nor postal codes match.
|
static short | AVS_OTHER_RESPONSE
Address Verification Service Code: Address Verification Service code cannot be mapped to the standard Address Verification Service codes.
|
static short | AVS_POSTALCODE_MATCH
Address Verification Service Code: Postal codes match, but street addresses do not.
|
static short | AVS_STREET_ADDRESS_MATCH
Address Verification Service Code: Street addresses match, but postal codes do not.
|
static short | AVS_UNKNOWN
Address Verification Service Code: Address Verification Service code has not been set yet.
|
static java.lang.String | COPYRIGHT
The IBM copyright notice field.
|
static short | STATE_APPROVED
State for payment on a successful approve transaction.
|
static short | STATE_APPROVING
State for a payment on a pending approve transaction.
|
static short | STATE_CANCELED
State for payment or credit when it has been canceled.
|
static short | STATE_EXPIRED
State for payment when the payment approval has expired.
|
static short | STATE_FAILED
State for payment or credit when the transaction failed.
|
static short | STATE_NEW
State for credit container object.
|
Modifier and Type | Method and Description |
---|---|
java.math.BigDecimal | getApprovedAmount()
This method gets the currently approved amount.
|
FinancialTransaction | getApproveTransaction()
This method gets the approve transaction container.
|
java.math.BigDecimal | getApprovingAmount()
This method gets the amount being approved.
|
short | getAvsCode()
This method gets the Address Verification Service code associated with the approve transaction.
|
java.math.BigDecimal | getDepositedAmount()
This method gets the amount currently deposited.
|
java.math.BigDecimal | getDepositingAmount()
This method gets the amount being deposited.
|
java.util.ArrayList | getDepositTransactions()
This method gets a list of deposit transactions.
|
java.util.Date | getExpirationDate()
This method gets the date the payment approval (authorization) is supposed to expire.
|
java.lang.String | getId()
This method gets the unique identifier of the Payment container.
|
PaymentInstruction | getPaymentInstruction()
This method gets the PaymentInstruction container this Payment is associated with.
|
java.util.ArrayList | getReverseApprovalTransactions()
This method gets a list of reverse approval transactions.
|
java.util.ArrayList | getReverseDepositTransactions()
This method gets an array of reverse deposit transactions.
|
java.math.BigDecimal | getReversingApprovedAmount()
This method gets the reversing deposit amount.
|
java.math.BigDecimal | getReversingDepositedAmount()
This method gets the deposited amount being reversed.
|
short | getState()
This method gets the state of the Payment container.
|
java.math.BigDecimal | getTargetAmount()
This method gets the requested target amount.
|
boolean | isAttentionRequired()
This method checks if the Payment requires external intervention.
|
boolean | isExpired()
This method checks if the payment approval (authorization) has expired.
|
void | setApprovedAmount(java.math.BigDecimal approvedAmount)
This method sets the approved amount after an approve transaction.
|
void | setApprovingAmount(java.math.BigDecimal approvingAmount)
This method sets the amount being approved.
|
void | setAttentionRequired(boolean attentionRequired)
This method sets a flag to indicate that the Payment requires attention even though all transactions might have finalized successfully.
|
void | setAvsCode(short avsCode)
This method sets the Address Verification Service code for the approve transaction.
|
void | setDepositedAmount(java.math.BigDecimal depositedAmount)
This method sets the currently deposited amount.
|
void | setDepositingAmount(java.math.BigDecimal depositingAmount)
This method sets the amount being deposited.
|
void | setExpirationDate(java.util.Date expirationDate)
This method sets the date the payment approval (authorization) is supposed to expire.
|
void | setExpired(boolean isExpired)
This method indicates if the Payment approval (authorization) has expired.
|
void | setReversingApprovedAmount(java.math.BigDecimal reversingApprovedAmount)
This method sets the approved amount being reversed.
|
void | setReversingDepositedAmount(java.math.BigDecimal reversingDepositedAmount)
This method sets the deposited amount being reversed.
|
java.lang.String | toString()
This method Prints a human-readable rendering of this container object.
|
static final java.lang.String COPYRIGHT
static final short AVS_UNKNOWN
static final short AVS_COMPLETE_MATCH
static final short AVS_STREET_ADDRESS_MATCH
static final short AVS_POSTALCODE_MATCH
static final short AVS_NO_MATCH
static final short AVS_OTHER_RESPONSE
static final short STATE_NEW
static final short STATE_APPROVING
static final short STATE_APPROVED
static final short STATE_FAILED
static final short STATE_CANCELED
static final short STATE_EXPIRED
FinancialTransaction getApproveTransaction()
This method gets the approve transaction container.
void setApprovedAmount(java.math.BigDecimal approvedAmount)
This method sets the approved amount after an approve transaction.
Plug-ins will invoke this method when supporting queries.
java.math.BigDecimal getApprovedAmount()
This method gets the currently approved amount.
The approved amount will be different from zero only after the initial approve transaction has successfully finished and before any approve reversal transactions with full reversal amount.
The approved amount can be different from the target amount associated with the Payment container. This occurs if the back-end system supports processing less that the requested amount during an approval transaction. Also, if reversals have occurred, the approved amount will be different from the target amount.
Gift certificate example
Suppose a plug-in supports gift certificates. If an approve asks for $15.00 in a given gift certificate and the gift certificate has actually only $14.45 remaining, the plug-in could approve $14.45.
This is the rationale: Gift Certificates have very limited amounts and are typically used with other payment methods like Credit Cards. The Gift Certificate is expected to be fully consumed before the Credit Card is charged. If the requested amount cannot be fully processed, the remaining is expected to be processed later on against the Credit Card.
Acceptance of this behavior depends on the plug-in. Even though this scenario is possible, the plug-in might choose to reject the approve transaction indicating that the account limit has been reached.
void setApprovingAmount(java.math.BigDecimal approvingAmount)
Plug-ins will invoke this method when supporting queries.
java.math.BigDecimal getApprovingAmount()
This method gets the amount being approved.
The approving amount will be different from zero when the initial approve transaction has been issued and not completed. Or if its state stays in pending status pending after its execution.
void setAvsCode(short avsCode)
This method sets the Address Verification Service code for the approve transaction.
An Address Verification Service code is typically returned by a payment back-end system during approvals (authorization) transactions. It is returned when there is a mismatch between the billing address specified in the transaction and the actual billing address. The actual address is registered in the account being charged.
Plug-ins are responsible for setting the Address Verification Service code for approve and approveAndDeposit transactions whenever necessary. If plug-ins do not set the Address Verification Service code, the Payment Plug-in Controller will use AVS_COMPLETE_MATCH as default.
Whenever an AVS code different from the code AVS_COMPLETE_MATCH is set, the plug-ins should also use setAttentionRequired(boolean) accordingly. It is to indicate that human intervention is required to validate the complete business flow. Here is an example:
... // Payment payment; // payment is received as a parameter in a request like Plugin.approve(). // AVS is received from the backend (PSP) and converted into // one of the valid Plug-in specification AVS codes. short avsCode = ...; // Set AVS code in container object. payment.setAvsCode(avsCode); // This is an example how the attentionRequired flag would be set // when there was no address match. if (avsCode != Payment.AVS_COMPLETE_MATCH) { payment.setAttentionRequired(true); }
These are the possible Address Verification Service codes:
short getAvsCode()
This method gets the Address Verification Service code associated with the approve transaction.
These are the possible Address Verification Service codes:
java.util.ArrayList getDepositTransactions()
This method gets a list of deposit transactions.
Each element in the list is a FinancialTransaction.
void setDepositedAmount(java.math.BigDecimal depositedAmount)
This method sets the currently deposited amount.
The deposited amount is set by the Payment Plug-in Controller on a successful deposit transaction. If multiple deposits have been made against a payment this will represent the sum of the deposited amounts of all the individual transactions.
Plug-ins will invoke this method when supporting queries.
java.math.BigDecimal getDepositedAmount()
This method gets the amount currently deposited.
If multiple deposits have been made against a Payment, this amount will represent the total amount deposited for all deposit transactions, that is, the sum of all the individual deposit transaction amounts.
void setDepositingAmount(java.math.BigDecimal depositingAmount)
This method sets the amount being deposited.
The Payment Plug-in Controller will set the depositing amount on deposit transactions that go to the state FinancialTransaction.STATE_PENDING.
Plug-ins will invoke this method when supporting queries.
java.math.BigDecimal getDepositingAmount()
This method gets the amount being deposited.
void setExpired(boolean isExpired)
This method indicates if the Payment approval (authorization) has expired.
This flag indicates if the payment approval (authorization) has expired while the expiration date is the expected expiration date.
boolean isExpired()
This method checks if the payment approval (authorization) has expired.
java.lang.String getId()
This method gets the unique identifier of the Payment container.
PaymentInstruction getPaymentInstruction()
This method gets the PaymentInstruction container this Payment is associated with.
void setAttentionRequired(boolean attentionRequired)
This method sets a flag to indicate that the Payment requires attention even though all transactions might have finalized successfully.
External intervention might be required. Typical example:
The plug-in might have other reasons to raise this flag that are specific to the payment protocol being implemented.
boolean isAttentionRequired()
This method checks if the Payment requires external intervention.
java.util.ArrayList getReverseApprovalTransactions()
This method gets a list of reverse approval transactions.
Each of the elements in the list is a FinancialTransaction.
java.util.ArrayList getReverseDepositTransactions()
This method gets an array of reverse deposit transactions.
Each element in the list is a FinancialTransaction.
void setReversingApprovedAmount(java.math.BigDecimal reversingApprovedAmount)
This method sets the approved amount being reversed.
Plug-ins will invoke this method when supporting queries.
java.math.BigDecimal getReversingApprovedAmount()
This method gets the reversing deposit amount.
void setReversingDepositedAmount(java.math.BigDecimal reversingDepositedAmount)
This method sets the deposited amount being reversed.
Plug-ins will invoke this method when supporting queries.
java.math.BigDecimal getReversingDepositedAmount()
This method gets the deposited amount being reversed.
short getState()
This method gets the state of the Payment container.
These are the valid state values:
java.math.BigDecimal getTargetAmount()
This method gets the requested target amount.
void setExpirationDate(java.util.Date expirationDate)
This method sets the date the payment approval (authorization) is supposed to expire.
The expiration date is expressed on Greenwich Mean Time (GMT) standard time.
Plug-ins will invoke this method when supporting queries.
java.util.Date getExpirationDate()
This method gets the date the payment approval (authorization) is supposed to expire.
The expiration date is expressed on Greenwich Mean Time (GMT) standard time.
java.lang.String toString()
This method Prints a human-readable rendering of this container object.