public interface PaymentInstruction
extends java.io.Serializable
This interface is a value object containing detailed information required by plug-ins to process financial transactions (FinancialTransaction).
The PaymentInstruction(PI) is a container that aggregates the data the plug-ins need to execute financial transactions while processing payment-related and credit-related transactions. It contains account, billing address, amounts, and so forth. It does not contain any specific information used to track a particular financial transaction with the back-end system, though. For tracking purposes, the Payment, Credit and FinancialTransaction are used instead.
The amount on the PaymentInstruction can be used by plug-ins to determine what is the maximum target amount the Payment Plug-in Controller intends to consume collectively. PPC often compares the amount in the PaymentInstruction with the requested amount for approve and credit transactions. PPC has to make sure that the PaymentInstruction amount is always equal to or greater than the requested amount.
The ExtendedData contains all the data related to a payment instruction that is not defined as an attribute in the PaymentInstruction interface. This is required because all the protocol parameters for a plug-in are not known beforehand by the Payment Plug-in Controller. WebSphere Commerce defines a number of keywords to identify common protocol parameters that are not part of the PaymentInstruction set of attributes. The plug-in should take these keywords and map them to their own back-end system definitions. Because it is not possible to define all the possible keywords for all potential plug-ins, additional keywords might need to be defined by the plug-ins. Plug-in writers are responsible for documenting these additional keywords. So that a merchant may be able to pass these attributes down to the Payment Plug-in Controller and then to the plug-in. The ExtendedData class, in summary, is the mechanism by which WebSphere Commerce passes all information related to a PaymentInstruction and required for financial transactions. In addition, if the plug-in has specific needs during checkPaymentInstruction and validatePaymentInstruction, the plug-in can add specific keywords and the Payment Plug-in Controller will store those keywords and use them in subsequent transactions against that PaymentInstruction.
Containers: Class Diagram
Plug-in predefined keywords
This is a list of predefined keywords that plug-ins may receive in ExtendedData associated with the PaymentInstruction. Notice that plug-ins may require more (or fewer) keywords for a given payment protocol.
------------------------------------------------------------------------------- Optional parameter for all payment methods ------------------------------------------------------------------------------- purchaseorder_id - the buyer Purchase Order Number order_id - the order unique identifier rma_id - the return merchandise authorization identifier ------------------------------------------------------------------------------- Credit Card specific ------------------------------------------------------------------------------- payment_method = [ VISA | MasterCard | AMEX | Discovery | ... ] account - the credit card number expire_year - the expiration year of the account expire_month - the expiration month of the account expire_day - the expiration day of the account billto_firstname - the account holder first name billto_middlename - the account holder middle name billto_lastname - the account holder last name billto_address1 - the bill to street address 1 billto_address2 - the bill to street address 2 billto_address3 - the bill to street address 3 billto_city - the bill to city billto_stateprovince - the bill to state or province billto_zipcode - the bill to zipcode billto_country - the bill to country (ISO 3166 numeric code) billto_phone_number - the bill to phone number cc_brand - the credit card brand Visa, AMEX, MasterCard, etc cc_cvc - the card verification code, this is used at store front not TSR/CSR applications. cc_nameoncard - the name on the card (cardholder) CAVV - the cardholder authentication verification value. XID - the transaction identifier. ------------------------------------------------------------------------------- Electronic Check specific ------------------------------------------------------------------------------- payment_method = check account - the gift certificate/card (stored value) number billto_firstname - the account holder first name billto_middlename - the account holder middle name billto_lastname - the account holder last name billto_address1 - the bill to street address 1 billto_address2 - the bill to street address 2 billto_address3 - the bill to street address 3 billto_city - the bill to city billto_stateprovince - the bill to state or province billto_zipcode - the bill to zipcode billto_country - the bill to country (ISO 3166 numeric code) billto_phone_number - the bill to phone number check_routing_number - the unique identifier of the bank; in US, the American Bankers Association (ABA) routing number check_number - the check number ------------------------------------------------------------------------------- Gift Certificates (GCt), Gift Cards (GCd) and Stored value (SV) cards in general ------------------------------------------------------------------------------- payment_method = [ storedValue | giftCertificate | giftCard ] account - the gift certificate/card (stored value) number expire_year - the expiration year of the account expire_month - the expiration month of the account expire_day - the expiration day of the account sv_issue_year - the year the card/certificate was issued sv_issue_month - the month the card/certificate was issued sv_issue_day - the month the card/certificate was issued sv_issuer - the name of the company/organization issuing the card/certificate ------------------------------------------------------------------------------- Cash on deliver (COD) or Bill me later ------------------------------------------------------------------------------- payment_method = [ COD | BillMe ] billto_firstname - the account holder first name billto_middlename - the account holder middle name billto_lastname - the account holder last name billto_address1 - the bill to street address 1 billto_address2 - the bill to street address 2 billto_address3 - the bill to street address 3 billto_city - the bill to city billto_stateprovince - the bill to state or province billto_zipcode - the bill to zipcode billto_country - the bill to country (ISO 3166 numeric code) billto_phone_number - the bill to phone number ------------------------------------------------------------------------------- Credit Line or Line of Credit ------------------------------------------------------------------------------- payment_method = creditLine account - the credit line account
Sensitive data
All the name-value pairs in the ExtendedData container are encrypted by the Payment Plug-in Controller during the creation of PaymentInstruction. However, plug-ins can add more attributes to ExtendedData container as necessary. When extra attributes are added by the plug-in, it is the plug-in responsibility to mark which attributes need to be encrypted by using the encrypted parameter in the set methods of ExtendedData.It is also the plug-in responsibility to remove sensitive data from a PaymentInstruction container when it is not required any longer. For example, cc_cvc, the credit card verification code, should be removed from the ExtendedData associated with the PaymentInstruction after the first successful approve transaction. Some payment protocols may require cc_cvc in every approve transaction, though. If that is the case, the plug-in should not remove this information from the PaymentInstruction.
The Payment Plug-in Controller will remove the complete set of name-value pairs from the ExtendedData container associated with the PaymentInstruction container whenever the payment instruction is closed or canceled. Any name-value pairs added by the plug-in will also be removed.
Modifier and Type | Field and Description |
---|---|
static java.lang.String | ACCOUNT
The keyword for the credit card number.
|
static java.lang.String | BILLTOADDRESS1
The keyword for the bill to street address 1.
|
static java.lang.String | BILLTOADDRESS2
The keyword for the bill to street address 2.
|
static java.lang.String | BILLTOADDRESS3
The keyword for the bill to street address 3.
|
static java.lang.String | BILLTOCITY
The keyword for the bill to city.
|
static java.lang.String | BILLTOCOUNTRY
The keyword for the bill to country (ISO 3166 numeric code).
|
static java.lang.String | BILLTOFIRSTNAME
The keyword for the account holder firstname.
|
static java.lang.String | BILLTOLASTNAME
The keyword for the account holder last name.
|
static java.lang.String | BILLTOMIDDLENAME
The keyword for the account holder middle name.
|
static java.lang.String | BILLTOPHONENUMBER
The keyword for the bill to phone number.
|
static java.lang.String | BILLTOSTATE
The keyword for the bill to state or province.
|
static java.lang.String | BILLTOZIPCODE
The keyword for the bill to zipcode.
|
static java.lang.String | CAVV
The keyword for Cardholder Authentication Verification Value.It is used for Verified By Visa.
|
static java.lang.String | CC_BRAND
The keyword for the credit card brand Visa, AMEX, MasterCard, and so forth.
|
static java.lang.String | CC_CVC
The keyword for the card verification code.
|
static java.lang.String | CC_NAMEONCARD
The keyword for the name on the card (cardholder).
|
static java.lang.String | CHECK_NUMBER
The keyword for the check number.
|
static java.lang.String | CHECK_ROUTING_NUMBER
The keyword for the unique identifier of the bank; in US, the American Bankers Association (ABA) routing number.
|
static java.lang.String | COPYRIGHT
The IBM copyright notice field.
|
static java.lang.String | EXPIREDAY
The keyword for the expiration day of the account.
|
static java.lang.String | EXPIREMONTH
The keyword for the expiration month of the account.
|
static java.lang.String | EXPIREYEAR
The keyword for the expiration year of the account.
|
static java.lang.String | ORDER_ID
The keyword for the order unique identifier.
|
static java.lang.String | PAYMENT_METHOD
The keyword for the payment method to be used: VISA, MasterCard, AMEX, Check, and so forth.
|
static java.lang.String | PURCHASEORDER_ID
The keyword for the buyer Purchase Order Number.
|
static java.lang.String | RMA_ID
The keyword for the return merchandise authorization identifier.
|
static short | STATE_CLOSED
The state of PaymentInstruction after it has been closed.
|
static short | STATE_INVALID
The state of PaymentInstruction after a failed validation.
|
static short | STATE_NEW
The state of the PaymentInstruction just after its creation and before validation.
|
static short | STATE_VALID
The state of PaymentInstruction after a successful validation.
|
static java.lang.String | SV_ISSUE_DAY
The keyword for the month the card/certificate was issued.
|
static java.lang.String | SV_ISSUE_MONTH
The keyword for the month the card/certificate was issued.
|
static java.lang.String | SV_ISSUE_YEAR
The keyword for the year the card/certificate was issued.
|
static java.lang.String | SV_ISSUER
The keyword for the name of the company/organization issuing the card/certificate.
|
static java.lang.String | XID
The keyword for Transaction Identifier.It is used for Verified By Visa.
|
Modifier and Type | Method and Description |
---|---|
java.lang.String | getAccount()
This method gets the account identifier associated with the PaymentInstruction.
|
java.math.BigDecimal | getAmount()
This method gets the target amount to be processed by associated financial transactions.
|
java.math.BigDecimal | getApprovedAmount()
This method gets the currently approved amount on this PaymentInstruction.
|
java.math.BigDecimal | getApprovingAmount()
This method gets the amount being approved.
|
java.math.BigDecimal | getCreditedAmount()
This method gets the currently credited amount on this PaymentInstruction.
|
java.math.BigDecimal | getCreditingAmount()
This method gets the amount being credited.
|
java.util.ArrayList | getCredits()
This method gets the list of associated Credit containers.
|
java.lang.String | getCurrency()
This method gets the currency of the PaymentInstruction as specified by ISO 4217.
|
java.math.BigDecimal | getDepositedAmount()
This method gets the currently deposited amount on this PaymentInstruction.
|
java.math.BigDecimal | getDepositingAmount()
This method gets the amount being deposited.
|
ExtendedData | getExtendedData()
This method gets the extra protocol data associated with this PaymentInstruction.
|
java.lang.String | getId()
This method gets the unique identifier of the PaymentInstruction container.
|
java.lang.String | getOrderId()
This method gets the order associated with the PaymentInstruction.
|
java.util.ArrayList | getPayments()
This method gets a list of Payment containers associated with this PaymentInstruction.
|
java.lang.String | getPaymentSystemName()
This method gets the payment system name the PaymentInstruction is associated with.
|
java.lang.String | getRmaId()
This method gets the Return Merchandizing Authorization ID associated with the PaymentInstruction.
|
short | getState()
This method gets the current state of the PaymentInstruction.
|
java.lang.String | getStore()
This method gets the merchant's store to which the PaymentInstruction belongs.
|
long | getTimeCreated()
This method gets the time when the PaymentInstruction was created.
|
long | getTimeUpdate()
This method gets the most recent time when the PaymentInstruction was last updated.
|
void | setAccount(java.lang.String account)
This method sets the account identifier of the PaymentInstruction.
|
java.lang.String | toString()
This method obtains a human-readable representation of the PaymentInstruction financial container.
|
static final java.lang.String COPYRIGHT
static final short STATE_NEW
static final short STATE_VALID
static final short STATE_INVALID
static final short STATE_CLOSED
static final java.lang.String PURCHASEORDER_ID
static final java.lang.String ORDER_ID
static final java.lang.String RMA_ID
static final java.lang.String PAYMENT_METHOD
static final java.lang.String ACCOUNT
static final java.lang.String EXPIREYEAR
static final java.lang.String EXPIREMONTH
static final java.lang.String EXPIREDAY
static final java.lang.String BILLTOFIRSTNAME
static final java.lang.String BILLTOMIDDLENAME
static final java.lang.String BILLTOLASTNAME
static final java.lang.String BILLTOADDRESS1
static final java.lang.String BILLTOADDRESS2
static final java.lang.String BILLTOADDRESS3
static final java.lang.String BILLTOCITY
static final java.lang.String BILLTOSTATE
static final java.lang.String BILLTOZIPCODE
static final java.lang.String BILLTOCOUNTRY
static final java.lang.String BILLTOPHONENUMBER
static final java.lang.String CC_BRAND
static final java.lang.String CC_CVC
static final java.lang.String CC_NAMEONCARD
static final java.lang.String CAVV
static final java.lang.String XID
static final java.lang.String CHECK_ROUTING_NUMBER
static final java.lang.String CHECK_NUMBER
static final java.lang.String SV_ISSUE_YEAR
static final java.lang.String SV_ISSUE_MONTH
static final java.lang.String SV_ISSUE_DAY
static final java.lang.String SV_ISSUER
void setAccount(java.lang.String account)
This method sets the account identifier of the PaymentInstruction.
The account is typically represented by a number, but it can also be an alphanumeric string.
If the standard keyword account is not used, the plug-in is responsible for setting the account based on the name-value pairs in extended data.
java.lang.String getAccount()
This method gets the account identifier associated with the PaymentInstruction.
java.math.BigDecimal getAmount()
This method gets the target amount to be processed by associated financial transactions.
java.math.BigDecimal getApprovedAmount()
This method gets the currently approved amount on this PaymentInstruction.
java.math.BigDecimal getApprovingAmount()
This method gets the amount being approved.
java.math.BigDecimal getCreditedAmount()
This method gets the currently credited amount on this PaymentInstruction.
java.math.BigDecimal getCreditingAmount()
This method gets the amount being credited.
java.util.ArrayList getCredits()
This method gets the list of associated Credit containers.
java.lang.String getCurrency()
This method gets the currency of the PaymentInstruction as specified by ISO 4217.
java.math.BigDecimal getDepositedAmount()
This method gets the currently deposited amount on this PaymentInstruction.
java.math.BigDecimal getDepositingAmount()
This method gets the amount being deposited.
ExtendedData getExtendedData()
This method gets the extra protocol data associated with this PaymentInstruction.
java.lang.String getId()
java.lang.String getOrderId()
This method gets the order associated with the PaymentInstruction.
This is an optional field because there may not be an order associated with the PaymentInstruction.
java.lang.String getRmaId()
This method gets the Return Merchandizing Authorization ID associated with the PaymentInstruction.
java.lang.String getPaymentSystemName()
This method gets the payment system name the PaymentInstruction is associated with.
The payment system name is typically the name of the plug-in implementation defined in the plug-in configuration. However, since multiple payment systems can be associated with the same plug-in. The payment system name can be used by the plug-in to distinguish which back-end or protocol the plug-in needs to use. This n-to-1 mapping is relevant only to plug-ins that support multiple payment protocols.
java.util.ArrayList getPayments()
This method gets a list of Payment containers associated with this PaymentInstruction.
short getState()
This method gets the current state of the PaymentInstruction.
Valid values:
java.lang.String getStore()
This method gets the merchant's store to which the PaymentInstruction belongs.
long getTimeCreated()
This method gets the time when the PaymentInstruction was created.
long getTimeUpdate()
This method gets the most recent time when the PaymentInstruction was last updated.
java.lang.String toString()
This method obtains a human-readable representation of the PaymentInstruction financial container.