PaymentInstruction

All Superinterfaces:: java.io.Serializable

All Known Implementing Classes:: PaymentInstructionImpl

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.

Field Summary

Fields
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.

Method Summary

All Methods Instance Methods Abstract Methods
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.

- 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 PaymentInstruction just after its creation and before validation.
    
    See Also:
    
    Constant Field Values
  - STATE_VALID
```
static final short STATE_VALID
```
    The state of PaymentInstruction after a successful validation.
    
    See Also:
    
    Constant Field Values
  - STATE_INVALID
```
static final short STATE_INVALID
```
    The state of PaymentInstruction after a failed validation.
    
    See Also:
    
    Constant Field Values
  - STATE_CLOSED
```
static final short STATE_CLOSED
```
    The state of PaymentInstruction after it has been closed.
    
    See Also:
    
    Constant Field Values
  - PURCHASEORDER_ID
```
static final java.lang.String PURCHASEORDER_ID
```
    The keyword for the buyer Purchase Order Number.
    
    See Also:
    
    Constant Field Values
  - ORDER_ID
```
static final java.lang.String ORDER_ID
```
    The keyword for the order unique identifier.
    
    See Also:
    
    Constant Field Values
  - RMA_ID
```
static final java.lang.String RMA_ID
```
    The keyword for the return merchandise authorization identifier.
    
    See Also:
    
    Constant Field Values
  - PAYMENT_METHOD
```
static final java.lang.String PAYMENT_METHOD
```
    The keyword for the payment method to be used: VISA, MasterCard, AMEX, Check, and so forth.
    
    See Also:
    
    Constant Field Values
  - ACCOUNT
```
static final java.lang.String ACCOUNT
```
    The keyword for the credit card number.
    
    See Also:
    
    Constant Field Values
  - EXPIREYEAR
```
static final java.lang.String EXPIREYEAR
```
    The keyword for the expiration year of the account.
    
    See Also:
    
    Constant Field Values
  - EXPIREMONTH
```
static final java.lang.String EXPIREMONTH
```
    The keyword for the expiration month of the account.
    
    See Also:
    
    Constant Field Values
  - EXPIREDAY
```
static final java.lang.String EXPIREDAY
```
    The keyword for the expiration day of the account.
    
    See Also:
    
    Constant Field Values
  - BILLTOFIRSTNAME
```
static final java.lang.String BILLTOFIRSTNAME
```
    The keyword for the account holder firstname.
    
    See Also:
    
    Constant Field Values
  - BILLTOMIDDLENAME
```
static final java.lang.String BILLTOMIDDLENAME
```
    The keyword for the account holder middle name.
    
    See Also:
    
    Constant Field Values
  - BILLTOLASTNAME
```
static final java.lang.String BILLTOLASTNAME
```
    The keyword for the account holder last name.
    
    See Also:
    
    Constant Field Values
  - BILLTOADDRESS1
```
static final java.lang.String BILLTOADDRESS1
```
    The keyword for the bill to street address 1.
    
    See Also:
    
    Constant Field Values
  - BILLTOADDRESS2
```
static final java.lang.String BILLTOADDRESS2
```
    The keyword for the bill to street address 2.
    
    See Also:
    
    Constant Field Values
  - BILLTOADDRESS3
```
static final java.lang.String BILLTOADDRESS3
```
    The keyword for the bill to street address 3.
    
    See Also:
    
    Constant Field Values
  - BILLTOCITY
```
static final java.lang.String BILLTOCITY
```
    The keyword for the bill to city.
    
    See Also:
    
    Constant Field Values
  - BILLTOSTATE
```
static final java.lang.String BILLTOSTATE
```
    The keyword for the bill to state or province.
    
    See Also:
    
    Constant Field Values
  - BILLTOZIPCODE
```
static final java.lang.String BILLTOZIPCODE
```
    The keyword for the bill to zipcode.
    
    See Also:
    
    Constant Field Values
  - BILLTOCOUNTRY
```
static final java.lang.String BILLTOCOUNTRY
```
    The keyword for the bill to country (ISO 3166 numeric code).
    
    See Also:
    
    Constant Field Values
  - BILLTOPHONENUMBER
```
static final java.lang.String BILLTOPHONENUMBER
```
    The keyword for the bill to phone number.
    
    See Also:
    
    Constant Field Values
  - CC_BRAND
```
static final java.lang.String CC_BRAND
```
    The keyword for the credit card brand Visa, AMEX, MasterCard, and so forth.
    
    See Also:
    
    Constant Field Values
  - CC_CVC
```
static final java.lang.String CC_CVC
```
    The keyword for the card verification code.
    
    See Also:
    
    Constant Field Values
  - CC_NAMEONCARD
```
static final java.lang.String CC_NAMEONCARD
```
    The keyword for the name on the card (cardholder).
    
    See Also:
    
    Constant Field Values
  - CAVV
```
static final java.lang.String CAVV
```
    The keyword for Cardholder Authentication Verification Value.It is used for Verified By Visa.
    
    See Also:
    
    Constant Field Values
  - XID
```
static final java.lang.String XID
```
    The keyword for Transaction Identifier.It is used for Verified By Visa.
    
    See Also:
    
    Constant Field Values
  - CHECK_ROUTING_NUMBER
```
static final java.lang.String CHECK_ROUTING_NUMBER
```
    The keyword for the unique identifier of the bank; in US, the American Bankers Association (ABA) routing number.
    
    See Also:
    
    Constant Field Values
  - CHECK_NUMBER
```
static final java.lang.String CHECK_NUMBER
```
    The keyword for the check number.
    
    See Also:
    
    Constant Field Values
  - SV_ISSUE_YEAR
```
static final java.lang.String SV_ISSUE_YEAR
```
    The keyword for the year the card/certificate was issued.
    
    See Also:
    
    Constant Field Values
  - SV_ISSUE_MONTH
```
static final java.lang.String SV_ISSUE_MONTH
```
    The keyword for the month the card/certificate was issued.
    
    See Also:
    
    Constant Field Values
  - SV_ISSUE_DAY
```
static final java.lang.String SV_ISSUE_DAY
```
    The keyword for the month the card/certificate was issued.
    
    See Also:
    
    Constant Field Values
  - SV_ISSUER
```
static final java.lang.String SV_ISSUER
```
    The keyword for the name of the company/organization issuing the card/certificate.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - setAccount
```
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.
    
    Parameters:
    
    account - The account identifier associated with this container.
    
    See Also:
    
    getExtendedData()., getAccount().
  - getAccount
```
java.lang.String getAccount()
```
    This method gets the account identifier associated with the PaymentInstruction.
    
    Returns:
    
    The account identifier of the PaymentInstruction.
    
    See Also:
    
    setAccount(String).
  - getAmount
```
java.math.BigDecimal getAmount()
```
    This method gets the target amount to be processed by associated financial transactions.
    
    Returns:
    
    The target amount.
  - getApprovedAmount
```
java.math.BigDecimal getApprovedAmount()
```
    This method gets the currently approved amount on this PaymentInstruction.
    
    Returns:
    
    The currently approvedAmount.
  - getApprovingAmount
```
java.math.BigDecimal getApprovingAmount()
```
    This method gets the amount being approved.
    
    Returns:
    
    The amount being approved.
  - getCreditedAmount
```
java.math.BigDecimal getCreditedAmount()
```
    This method gets the currently credited amount on this PaymentInstruction.
    
    Returns:
    
    The currently creditedAmount
  - getCreditingAmount
```
java.math.BigDecimal getCreditingAmount()
```
    This method gets the amount being credited.
    
    Returns:
    
    The amount being credited.
  - getCredits
```
java.util.ArrayList getCredits()
```
    This method gets the list of associated Credit containers.
    
    Returns:
    
    The list of associated Credit containers; this list might be empty.
  - getCurrency
```
java.lang.String getCurrency()
```
    This method gets the currency of the PaymentInstruction as specified by ISO 4217.
    
    Returns:
    
    The currency associated with the PaymentInstruction as specified by ISO 4217.
  - getDepositedAmount
```
java.math.BigDecimal getDepositedAmount()
```
    This method gets the currently deposited amount on this PaymentInstruction.
    
    Returns:
    
    The currently depositedAmount.
  - getDepositingAmount
```
java.math.BigDecimal getDepositingAmount()
```
    This method gets the amount being deposited.
    
    Returns:
    
    The amount being deposited.
  - getExtendedData
```
ExtendedData getExtendedData()
```
    This method gets the extra protocol data associated with this PaymentInstruction.
    
    Returns:
    
    The extra protocol data associated with this PaymentInstruction.
  - getId
```
java.lang.String getId()
```
    This method gets the unique identifier of the PaymentInstruction container.
    
    Returns:
    
    The identifier for the PaymentInstruction.
  - getOrderId
```
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.
    
    Returns:
    
    The associated order; null if there is no order associated with the PaymentInstruction .
  - getRmaId
```
java.lang.String getRmaId()
```
    This method gets the Return Merchandizing Authorization ID associated with the PaymentInstruction.
    
    Returns:
    
    The associated Return Merchandizing Authorization ID; null if not present .
  - getPaymentSystemName
```
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.
    
    Returns:
    
    The name of the payment system used to process the PaymentInstruction.
  - getPayments
```
java.util.ArrayList getPayments()
```
    This method gets a list of Payment containers associated with this PaymentInstruction.
    
    Returns:
    
    The list containing the associated Payment containers; this list might be empty.
  - getState
```
short getState()
```
    This method gets the current state of the PaymentInstruction.
    
    Valid values:
    Returns:
    
    The state of the PaymentInstruction.
  - getStore
```
java.lang.String getStore()
```
    This method gets the merchant's store to which the PaymentInstruction belongs.
    
    Returns:
    
    The unique identifier of the merchant's store.
  - getTimeCreated
```
long getTimeCreated()
```
    This method gets the time when the PaymentInstruction was created.
    
    Returns:
    
    The time in milliseconds when the PaymentInstruction was created.
  - getTimeUpdate
```
long getTimeUpdate()
```
    This method gets the most recent time when the PaymentInstruction was last updated.
    
    Returns:
    
    The time in milliseconds when the PaymentInstruction was last updated.
  - toString
```
java.lang.String toString()
```
    This method obtains a human-readable representation of the PaymentInstruction financial container.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    A human-readable representation of the PaymentInstruction container.

COPYRIGHT

STATE_NEW

STATE_VALID

STATE_INVALID

STATE_CLOSED

PURCHASEORDER_ID

ORDER_ID

RMA_ID

PAYMENT_METHOD

ACCOUNT

EXPIREYEAR

EXPIREMONTH

EXPIREDAY

BILLTOFIRSTNAME

BILLTOMIDDLENAME

BILLTOLASTNAME

BILLTOADDRESS1

BILLTOADDRESS2

BILLTOADDRESS3

BILLTOCITY

BILLTOSTATE

BILLTOZIPCODE

BILLTOCOUNTRY

BILLTOPHONENUMBER

CC_BRAND

CC_CVC

CC_NAMEONCARD

CAVV

XID

CHECK_ROUTING_NUMBER

CHECK_NUMBER

SV_ISSUE_YEAR

SV_ISSUE_MONTH

SV_ISSUE_DAY

SV_ISSUER

setAccount

getAccount

getAmount

getApprovedAmount

getApprovingAmount

getCreditedAmount

getCreditingAmount

getCredits

getCurrency

getDepositedAmount

getDepositingAmount

getExtendedData

getId

getOrderId

getRmaId

getPaymentSystemName

getPayments

getState

getStore

getTimeCreated

getTimeUpdate

toString