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:
approve
transaction will be issued against a
Payment
pending
for a given Payment
at the same time
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.
approvedAmount
- The approved amount to be set.getApprovedAmount().
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.
setApprovedAmount(BigDecimal).
void setApprovingAmount(java.math.BigDecimal approvingAmount)
Plug-ins will invoke this method when supporting queries.
approvingAmount
- The amount being approved.getApprovingAmount().
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.
setApprovingAmount(BigDecimal).
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:
avsCode
- The Address Verification Service code to be set.getAvsCode().
,
setAttentionRequired(boolean).
short getAvsCode()
This method gets the Address Verification Service code associated with the approve
transaction.
These are the possible Address Verification Service codes:
setAvsCode(short).
java.util.ArrayList getDepositTransactions()
This method gets a list of deposit
transactions.
Each element in the list is a
FinancialTransaction
.
FinancialTransaction
with deposits;
this list is potentially empty.getDepositTransactions().
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.
depositedAmount
- The targetAmount deposited by the back-end system.getDepositedAmount().
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.
Payment
.setDepositedAmount(BigDecimal).
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.
depositingAmount
- The amount being deposited.getDepositingAmount().
java.math.BigDecimal getDepositingAmount()
This method gets the amount being deposited.
setDepositingAmount(BigDecimal).
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.
isExpired
- Whether the Payment
approval has expired or not.isExpired().
,
getExpirationDate().
,
setExpirationDate(Date).
,
PluginConfiguration
boolean isExpired()
This method checks if the payment approval (authorization) has expired.
setExpired(boolean).
,
getExpirationDate().
,
setExpirationDate(Date).
java.lang.String getId()
This method gets the unique identifier of the Payment
container.
Payment
container.PaymentInstruction getPaymentInstruction()
This method gets the PaymentInstruction
container this Payment
is associated with.
PaymentInstruction
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:
AVS_COMPLETE_MATCH
during
approve
and approveAndDeposit
transactionssetAvsCode(short)
.
The plug-in might have other reasons to raise this flag that are specific to the payment protocol being implemented.
attentionRequired
- If the Payment
requires external intervention.isAttentionRequired().
,
setAvsCode(short).
boolean isAttentionRequired()
This method checks if the Payment
requires external intervention.
Payment
requires external intervention.setAttentionRequired(boolean).
java.util.ArrayList getReverseApprovalTransactions()
This method gets a list of reverse approval
transactions.
Each of the elements in the list is a FinancialTransaction
.
FinancialTransaction
with
reverse approve transaction.java.util.ArrayList getReverseDepositTransactions()
This method gets an array of reverse deposit transactions.
Each element in the list is a FinancialTransaction
.
FinancialTransaction
objects
that represent a reverse deposit
transaction.void setReversingApprovedAmount(java.math.BigDecimal reversingApprovedAmount)
This method sets the approved amount being reversed.
Plug-ins will invoke this method when supporting queries.
reversingApprovedAmount
- The approved amount being reversed.getReversingApprovedAmount().
java.math.BigDecimal getReversingApprovedAmount()
This method gets the reversing deposit amount.
setReversingApprovedAmount(BigDecimal).
void setReversingDepositedAmount(java.math.BigDecimal reversingDepositedAmount)
This method sets the deposited amount being reversed.
Plug-ins will invoke this method when supporting queries.
reversingDepositedAmount
- The deposited amount being reversed.getReversingDepositedAmount().
java.math.BigDecimal getReversingDepositedAmount()
This method gets the deposited amount being reversed.
setReversingDepositedAmount(BigDecimal).
short getState()
This method gets the state of the Payment
container.
These are the valid state values:
Payment
container.java.math.BigDecimal getTargetAmount()
This method gets the requested target amount.
Payment
container.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.
expirationDate
- The expiration date to be set.isExpired().
,
setExpired(boolean).
,
getExpirationDate().
,
PluginConfiguration
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.
isExpired()
,
setExpired(boolean).
,
setExpirationDate(Date).
java.lang.String toString()
This method Prints a human-readable rendering of this container object.
toString
in class java.lang.Object