com.ibm.commerce.payments.plugin

Interface Payment

  • All Superinterfaces:
    java.io.Serializable
    All Known Implementing Classes:
    PaymentImpl


    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:

    • Only one single approve transaction will be issued against a Payment
    • Only one single transaction will be in 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

    Payment state machine
    • Field Summary

      Fields 
      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.
    • Method Summary

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

      • COPYRIGHT

        static final java.lang.String COPYRIGHT
        The IBM copyright notice field.
        See Also:
        Constant Field Values
      • AVS_UNKNOWN

        static final short AVS_UNKNOWN
        Address Verification Service Code: Address Verification Service code has not been set yet.
        See Also:
        Constant Field Values
      • AVS_COMPLETE_MATCH

        static final short AVS_COMPLETE_MATCH
        Address Verification Service Code: Street addresses and postal codes match.
        See Also:
        Constant Field Values
      • AVS_STREET_ADDRESS_MATCH

        static final short AVS_STREET_ADDRESS_MATCH
        Address Verification Service Code: Street addresses match, but postal codes do not.
        See Also:
        Constant Field Values
      • AVS_POSTALCODE_MATCH

        static final short AVS_POSTALCODE_MATCH
        Address Verification Service Code: Postal codes match, but street addresses do not.
        See Also:
        Constant Field Values
      • AVS_NO_MATCH

        static final short AVS_NO_MATCH
        Address Verification Service Code: Neither street addresses nor postal codes match.
        See Also:
        Constant Field Values
      • AVS_OTHER_RESPONSE

        static final short AVS_OTHER_RESPONSE
        Address Verification Service Code: Address Verification Service code cannot be mapped to the standard Address Verification Service codes.
        See Also:
        Constant Field Values
      • STATE_NEW

        static final short STATE_NEW
        State for credit container object.
        See Also:
        Constant Field Values
      • STATE_APPROVING

        static final short STATE_APPROVING
        State for a payment on a pending approve transaction.
        See Also:
        Constant Field Values
      • STATE_APPROVED

        static final short STATE_APPROVED
        State for payment on a successful approve transaction.
        See Also:
        Constant Field Values
      • STATE_FAILED

        static final short STATE_FAILED
        State for payment or credit when the transaction failed.
        See Also:
        Constant Field Values
      • STATE_CANCELED

        static final short STATE_CANCELED
        State for payment or credit when it has been canceled.
        See Also:
        Constant Field Values
      • STATE_EXPIRED

        static final short STATE_EXPIRED
        State for payment when the payment approval has expired.
        See Also:
        Constant Field Values
    • Method Detail

      • getApproveTransaction

        FinancialTransaction getApproveTransaction()

        This method gets the approve transaction container.

        Returns:
        Approve transaction container.
      • setApprovedAmount

        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.

        Parameters:
        approvedAmount - The approved amount to be set.
        See Also:
        getApprovedAmount().
      • 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.

        Returns:
        The amount that has been approved.
        See Also:
        setApprovedAmount(BigDecimal).
      • setApprovingAmount

        void setApprovingAmount(java.math.BigDecimal approvingAmount)
        This method sets the amount being approved.

        Plug-ins will invoke this method when supporting queries.

        Parameters:
        approvingAmount - The amount being approved.
        See Also:
        getApprovingAmount().
      • 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.

        Returns:
        The amount being approved.
        See Also:
        setApprovingAmount(BigDecimal).
      • setAvsCode

        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:

        Parameters:
        avsCode - The Address Verification Service code to be set.
        See Also:
        getAvsCode()., setAttentionRequired(boolean).
      • setDepositedAmount

        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.

        Parameters:
        depositedAmount - The targetAmount deposited by the back-end system.
        See Also:
        getDepositedAmount().
      • 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.

        Returns:
        The total deposited amount in for this Payment.
        See Also:
        setDepositedAmount(BigDecimal).
      • setDepositingAmount

        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.

        Parameters:
        depositingAmount - The amount being deposited.
        See Also:
        getDepositingAmount().
      • getDepositingAmount

        java.math.BigDecimal getDepositingAmount()

        This method gets the amount being deposited.

        Returns:
        The current amount being deposited.
        See Also:
        setDepositingAmount(BigDecimal).
      • setExpired

        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.

        Parameters:
        isExpired - Whether the Payment approval has expired or not.
        See Also:
        isExpired()., getExpirationDate()., setExpirationDate(Date)., PluginConfiguration
      • getId

        java.lang.String getId()

        This method gets the unique identifier of the Payment container.

        Returns:
        The unique identifier of the Payment container.
      • getPaymentInstruction

        PaymentInstruction getPaymentInstruction()

        This method gets the PaymentInstruction container this Payment is associated with.

        Returns:
        The PaymentInstruction this payment is associated with.
      • setAttentionRequired

        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:

        • Address Verification Service codes different from the code AVS_COMPLETE_MATCH during approve and approveAndDeposit transactions

        For a code example, see setAvsCode(short).

        The plug-in might have other reasons to raise this flag that are specific to the payment protocol being implemented.

        Parameters:
        attentionRequired - If the Payment requires external intervention.
        See Also:
        isAttentionRequired()., setAvsCode(short).
      • isAttentionRequired

        boolean isAttentionRequired()

        This method checks if the Payment requires external intervention.

        Returns:
        If the Payment requires external intervention.
        See Also:
        setAttentionRequired(boolean).
      • getReverseApprovalTransactions

        java.util.ArrayList getReverseApprovalTransactions()

        This method gets a list of reverse approval transactions.

        Each of the elements in the list is a FinancialTransaction.

        Returns:
        A list of FinancialTransaction with reverse approve transaction.
      • getReverseDepositTransactions

        java.util.ArrayList getReverseDepositTransactions()

        This method gets an array of reverse deposit transactions.

        Each element in the list is a FinancialTransaction.

        Returns:
        A list containing FinancialTransaction objects that represent a reverse deposit transaction.
      • setReversingApprovedAmount

        void setReversingApprovedAmount(java.math.BigDecimal reversingApprovedAmount)

        This method sets the approved amount being reversed.

        Plug-ins will invoke this method when supporting queries.

        Parameters:
        reversingApprovedAmount - The approved amount being reversed.
        See Also:
        getReversingApprovedAmount().
      • getReversingApprovedAmount

        java.math.BigDecimal getReversingApprovedAmount()

        This method gets the reversing deposit amount.

        Returns:
        The approved amount being reversed.
        See Also:
        setReversingApprovedAmount(BigDecimal).
      • setReversingDepositedAmount

        void setReversingDepositedAmount(java.math.BigDecimal reversingDepositedAmount)

        This method sets the deposited amount being reversed.

        Plug-ins will invoke this method when supporting queries.

        Parameters:
        reversingDepositedAmount - The deposited amount being reversed.
        See Also:
        getReversingDepositedAmount().
      • getReversingDepositedAmount

        java.math.BigDecimal getReversingDepositedAmount()

        This method gets the deposited amount being reversed.

        Returns:
        The deposited amount being reversed.
        See Also:
        setReversingDepositedAmount(BigDecimal).
      • getTargetAmount

        java.math.BigDecimal getTargetAmount()

        This method gets the requested target amount.

        Returns:
        The requested target amount for this Payment container.
      • setExpirationDate

        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.

        Parameters:
        expirationDate - The expiration date to be set.
        See Also:
        isExpired()., setExpired(boolean)., getExpirationDate()., PluginConfiguration
      • getExpirationDate

        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.

        Returns:
        The date the payment approval (authorization) expires.
        See Also:
        isExpired(), setExpired(boolean)., setExpirationDate(Date).
      • toString

        java.lang.String toString()

        This method Prints a human-readable rendering of this container object.

        Overrides:
        toString in class java.lang.Object
        Returns:
        A human-readable rendering of this container object.