com.ibm.commerce.payments.plugin

Interface Plugin

  • All Known Subinterfaces:
    QueryablePlugin
    All Known Implementing Classes:
    LOCPluginBean, SimpleOfflineBean

    public interface Plugin

    This interface is implemented by a payment plug-in.

    A payment plug-in (or simply plug-in) is a stateless session bean. It externalizes payment services for a particular payment back-end system, payment processor, or payment service provider (PSP). Plug-ins can be considered proxies to payment back-end systems and the methods herein should map directly to the related back-end financial transactions.

    Payment plug-ins are extensions to the IBM Payment Plug-in Controller. Payment Plug-in Controller provides a unified view of payment services to IBM WebSphere Commerce. Although the Payment Plug-in Controller concerns itself with persistence, database transaction management, and other facilities. It does not provide direct connectivity with payment back-end systems. Connectivity is the payment plugin's goal. Payment Plug-in Controller supports multiple plug-ins running at the same time and hides the complexity from WebSphere Commerce behind a unique payment service API.

    The Plugin specification defines a list of financial transactions that can be implemented by a plug-in:

    • Payment approval (or authorization)
    • Payment deposit (or capture)
    • Credit (or refund)
    • Reversals for the above transactions

    Some transactions might not make sense for some plug-ins if the equivalent functionality is not available by the payment back-end system. Under these circumstances, a plug-in writer should determine which transactions to implement. For the transactions not implemented by the plug-in, FunctionNotSupportedException should be thrown.

    As a guide, here is a list of financial transactions to be implemented based on the type of the plug-in. Please note that this list is not exhaustive:

    Financial transactionCredit cardElectronic checkGift certificate
    checkPaymentInstructionxxx
    validatePaymentInstructionxxx
    approveAndDepositxx-
    approvex-x
    reverseApprovalx--
    depositxxx
    reverseDepositx--
    creditx--
    reverseCreditx--

    A plug-in may implement more than one type of payment protocol. For instance, it can implement a protocol for credit card processing and also for electronic check processing. In that case, the plug-in should implement not only the recommended methods for credit card processing but also the recommended methods for electronic check transactions.

    TimeoutException

    To avoid resource contention a plug-in should not block a request for long periods of time. Whenever possible, a plug-in should throw TimeOutException when a configurable amount of time has elapsed.

    For example, during an approve() request, a plug-in could wait for at most 45 seconds. After that period of time, since if the plug-in hasn't received a response from the back end (payment service provider). It will throw a TimeOutException.

    Note that the plug-in should make the waiting period a configurable property in the plug-in deployment descriptor. What may be a short period for some applications, may be a long period for others.

    Since plug-ins are stateless session beans (SSB) (and as such are not supposed to spawn their own background threads). Plug-ins may not be able to detect a timeout by themselves. In these cases, the EJB transaction which contains the plug-in request will be rolled back automatically by the EJB container according to a pre-configurable timeout.

    Approve sequence diagram

    The diagram below shows the execution flow of the approve transaction. Similar flows happen for the other financial transactions.

    Approve Sequence Diagram
    1. The external application requests an approve transaction.
    2. The Payment Plug-in Controller looks up the PaymentInstruction that will service that request.
    3. The Payment Plug-in Controller looks up the Payment to which the approve transaction will be executed.
    4. The Payment Plug-in Controller creates a FinancialTransaction that describes the approve transaction.
    5. The Payment Plug-in Controller finds the target plug-in to process the financial transaction.
    6. The Payment Plug-in Controller creates a PluginContext with the plug-in deployment descriptor data.
    7. The Payment Plug-in Controller invokes Plugin.approve(...)
    8. The plug-in returns the updated FinancialTransaction or throws an exception.
    9. The Payment Plug-in Controller returns the results to the external application.

    • Field Detail

      • COPYRIGHT

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

    • Method Detail

      • getMessage

        java.lang.String getMessage(PluginContext pluginContext,
                            java.lang.String messageKey)

        This method gets the translated error message associated with the particular error key.

        Plug-ins are supposed to throw exceptions with translated error messages because the error messages need to be displayed and logged in a particular locale. However, the error messages might need to be referenced again later on a different locale. For that reason, error keys are stored by users of the payment subsystem instead of the error messages themselves.

        Error messages are usually known at plug-in deployment time. However, error codes may change by the PSP's protocol being implemented by the plug-in. If that is the case, this method will be used to obtain these error messages once the messages become available.

        If the plug-in cannot obtain the error message for the specified messageKey, the plug-in should return the messageKey itself.

        If this method is not implemented, the Payment Plug-in Controller will assume that the error message is unknown.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        messageKey - The error unique key.
        Returns:
        The translated error message if available; otherwise the messageKey itself.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.

      • approve

        FinancialTransaction approve(PluginContext pluginContext,
                             FinancialTransaction financialTransaction,
                             boolean retry)
                      throws CommunicationException,
                             PluginException

        This method approves an amount against a particular payment instruction.

        An approval reserves funds on a particular payment instruction without actually moving money from the payer to the payee. For instance, in credit cards, this should be mapped into a credit card authorization against the payment back-end system.

        This method is typically implemented for Credit Cards and gift cards or similar payment methods where funds are reserved and later on captured. For example: Merchants processing credit cards will often approve the ordered amount during order capture and deposit when packages are shipped. Nevertheless, this method is not typically implemented for electronic check processing.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        financialTransaction - The details of the transaction to be processed.
        retry - Indicates if the same transaction has been tried before by the Payment Plug-in Controller.
        Returns:
        The FinancialTransaction with the results of the transaction.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.
        CommunicationException

      • approveAndDeposit

        FinancialTransaction approveAndDeposit(PluginContext pluginContext,
                                       FinancialTransaction financialTransaction,
                                       boolean retry)
                                throws FunctionNotSupportedException,
                                       PluginException

        This method deposits a payment without a prior approval. Also called a "sale" transaction or "authorization with capture."

        For example, plug-ins which support electronic check processing, or immediate sale of credit card transactions in a single back-end system call may use this method.

        Executing a sale transaction might be advantageous for merchants because it minimizes the number of overall transactions and the total processing fees.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        financialTransaction - The details of the transaction to be processed.
        retry - Indicates if the same transaction has been tried before by the Payment Plug-in Controller.
        Returns:
        The FinancialTransaction with the results of the transaction.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.
        FunctionNotSupportedException

      • credit

        FinancialTransaction credit(PluginContext pluginContext,
                            FinancialTransaction financialTransaction,
                            boolean retry)
                     throws PluginException

        This method credits an amount against a specific PaymentInstruction.

        This method supports dependent (associated with a prior deposit) and independent (not associated with a prior deposit) credits. The PaymentInstruction associated with the Credit in the FinancialTransaction allows the plug-in to determine which type of credit this transaction represents.

        Independent Credit: the PaymentInstruction referenced by Credit will not have any Payments associated with it.

        Dependent Credit: PaymentInstruction referenced by Credit will have at least one Payment associated with it. If the associated Payment does not have an actual approved and deposited amount, this is not a real dependent credit transaction.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        financialTransaction - The details of the transaction to be processed.
        retry - Indicates if the same transaction has been tried before by the Payment Plug-in Controller.
        Returns:
        The FinancialTransaction with the results of the transaction.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.

      • deposit

        FinancialTransaction deposit(PluginContext pluginContext,
                             FinancialTransaction financialTransaction,
                             boolean retry)
                      throws PluginException

        This method deposits an amount against a previously approved Payment.

        This is typically invoked after the merchant has shipped the goods and is now entitled to receive payment.

        This method should be implemented if the method approve(PluginContext, FinancialTransaction, boolean) is implemented. This method is typically implemented for credit cards, gift cards or similar payment methods where funds are reserved and captured later on. For example: Merchants processing credit cards will often approve the total ordered amount and capture when packages are shipped.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        financialTransaction - The details of the transaction to be processed.
        retry - Indicates if the same transaction has been tried before by the Payment Plug-in Controller.
        Returns:
        The FinancialTransaction with the results of the transaction.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.

      • reverseApproval

        FinancialTransaction reverseApproval(PluginContext pluginContext,
                                     FinancialTransaction financialTransaction,
                                     boolean retry)
                              throws CommunicationException,
                                     PluginException

        This method cancels a payment that has been previously approved.

        The amount can be partial if the plug-in back-end supports it. If the plug-in does not support partial amounts then the InvalidDataException should be thrown.

        A reverse approval transaction is only requested against a plug-in if a previous approve transaction has been requested and is either in FinancialTransaction.STATE_SUCCESS or FinancialTransaction.STATE_FAILED.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        financialTransaction - The details of the transaction to be processed.
        retry - Indicates if the same transaction has been tried before by the Payment Plug-in Controller.
        Returns:
        The FinancialTransaction with the results of the transaction.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.
        CommunicationException

      • reverseDeposit

        FinancialTransaction reverseDeposit(PluginContext pluginContext,
                                    FinancialTransaction financialTransaction,
                                    boolean retry)
                             throws FunctionNotSupportedException,
                                    PluginException

        This method cancels a previously deposited amount.

        The amount can be partial if the plug-in supports partial amounts. If the plug-in does not support partial amounts, then the InvalidDataException should be thrown.

        A reverse deposit transaction is only requested against a plug-in if a previous deposit transaction has been requested and is either in FinancialTransaction.STATE_SUCCESS or FinancialTransaction.STATE_FAILED.

        Parameters:
        pluginContext - The plug-in context to be used in this request.
        financialTransaction - The details of the transaction to be processed.
        retry - Indicates if the same transaction has been tried before by the Payment Plug-in Controller.
        Returns:
        The FinancialTransaction with the results of the transaction.
        Throws:
        PluginException - Thrown when any exception conditions specified by the PluginException hierarchy are met; for more details, read the plug-in exceptions hierarchy Javadocs.
        RemoteException - Thrown by the EJB container as part of the EJB specification.
        FunctionNotSupportedException

      • checkHealth

        boolean checkHealth()

        This method checks whether XML configuration for the Plugin is available. For the SimpleOffline, if the XML file is missing, or renamed, or its content is invalid, then false is returned. Otherwise true is returned. And for other Plugin, always true is returned since no corresponding XML configuration file exists.

        This API is used by PluginFactory in accelerator. When false is returned, PluginFactory will not put this plugin into the available collection. And further it will not be listed in the available payment methods in accelerator.

        Returns:
        If the XML configuration for the Plugin is available.
        Throws:
        RemoteException - Thrown by the EJB container as part of the EJB specification.
Skip navigation links