Payment plug-in specification
Version: 1.0
Purpose: This specification accompanies the Java API information for the IBM payment plug-in. The goal of this information is to provide an overview of the payment plug-in specification and to describe the basic concepts of payment plug-ins.
Target audience and skill requirements: The target audience for this information is application developers for payment service providers, e-commerce solutions, or external payment systems.
Related information: This payment plug-in API specification is intended to be used with the following API information: com.ibm.commerce.payments.plugin.
Features: The payment plug-in specification has these features:
- It supports a variety of payment methods:
- Credit cards*
- Electronic checks*
- Gift cards
- Gift certificates
- Stored value cards
- Bill Me Later*
- Cash on Delivery (COD)*
- Credit line* (with typical back-end integration with account receivable systems)
- It supports both dependent and independent credits when they are permitted by the back-end payment system. Note: Although the WebSphere Commerce Payments supports both types of credits, the Payment Rules subcomponent in WebSphere Commerce supports only independent credits.
- It supports multiple captures of funds per authorization when permitted by the back-end payment system.
- It enables skilled plug-in developers to produce a working plug-in in a short time (a few weeks).
*Plug-ins are provided in IBM WebSphere Commerce to support these methods. You might want to develop your own payment plug-in for use in a particular commerce situation. If you want to write your own plug-in, follow this specification for developing a payment plug-in.
Organization of this specification: This specification information includes a description of terms used in the specification, specification details that supplement the API information, examples of the plug-in deployment descriptor and related XSD file, and diagrams that help to illustrate important concepts. It also contains information about error handling and security considerations.
Topics included in this specification:
- Terminology
- Specification description
- Plug-in deployment descriptor
- Understanding the plug-in interfaces
- Plugin interface
- TimeOutException in the Plugin interface
- QueryablePlugin interface
- PluginConfiguration interface
- PluginContext interface
- PaymentInstruction interface
- FinancialTransaction interface
- Payment interface
- Credit interface
- Understanding the plug-in classes
- Extended data class
- NamedValueObject
- PluginMessages
- Payment plug-in error handling
- Security considerations for payment plug-ins
For information about how to configure a plug-in in WebSphere Commerce, refer to the WebSphere Commerce information topics related to payment plug-ins.
Terminology used in this specification
- Container - A value object that contains financial information and can aggregate or relate to other containers. The containers defined in the plug-in specification are: PaymentInstruction, Payment, and Credit.
- Financial transaction - A transaction (object) that validates or authenticates payment information, reserves funds in accounts, and transfers funds from one account to another. The ExtendedData value object of the financialTransaction provides plug-ins with a mechanism to store protocol data used during financial transactions.
- Payment protocol - A payment protocol is the convention that governs the exchange of data between a payment plug-in and a payment back-end system (payment service provider or payment processor). A payment protocol can involve online or offline processing to allow financial transactions to be carried out. Online processing or the online protocol refers to the processing of financial transactions that do not require external intervention for successful execution. The complete processing of the financial transaction is done electronically and automatically without the need for any external or human intervention. Offline processing or the offline protocol 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 because external intervention by a human is needed to process the transaction.
Specification description
- The WebSphere Commerce Payments delegates the execution of financial transactions to payment plug-ins.
- A payment plug-in is a stateless session bean with a remote interface that externalizes one or more payment protocols through a common interface. A payment plug-in can implement a payment protocol directly or it can use libraries that provide the actual implementation of a payment protocol.
- A processing agreement exists between the WebSphere Commerce Payments and payment plug-ins. This agreement specifies the packaging, APIs, and plug-in metadata information.
- Plug-ins describe themselves to the WebSphere Commerce Payments by means of a plug-in deployment descriptor.
- The WebSphere Commerce Payments persists all the protocol data used by plug-ins as encrypted name-value pairs.
- The plug-in specification identifies predefined keywords that the WebSphere Commerce system will use to pass protocol data details down to the WebSphere Commerce Payments and then to plug-ins. These protocol data keywords define a common dictionary but are not mandatory. The advantage of using common keywords is to minimize the impact on storefronts when the protocol data is collected from multiple sources and for multiple payment methods. These keywords are defined in the PaymentInstruction API information, in the ExtendedData class.
The objects defined by the plug-in specification are:
- PaymentInstruction - (Java interface) Container object. Contains detailed information required by plug-ins to process financial transactions. A payment instruction represents an instance of a payment; for example, use credit card brand X, with an expiration date of November of this year, to make a payment in the amount of $100 U.S. dollars. A PaymentInstruction keeps references to all Payment containers and all Credit containers associated with it.
- ExtendedData - (Class) Value object. Contains all data related to a payment instruction that is not defined as an attribute in the PaymentInstruction container object. The ExtendedData object can also be used in a FinancialTransaction value object to store any data that plug-ins might need to keep in the database.
- Payment - (Java interface) Container object. Contains information about financial transactions associated with payments. Payments are always associated with a PaymentInstruction container.
- Credit - (Java interface) Container object. Contains information about financial transactions associated with credits or refunds. Credits are always associated with a PaymentInstruction container.
- FinancialTransaction - (Java interface) Value object. Represents a particular type of financial transaction (approve, deposit, approveAndDeposit, credit, reverseApproval, reverseDeposit, and reverseCredit).
- The WebSphere Commerce Payments will enforce or control maximum amounts to be consumed from the PaymentInstruction, Credit, and Payment containers.
Plug-in deployment descriptor
A plug-in deployment descriptor enables a plug-in to integrate with WebSphere Commerce. It is an XML file that contains information about a plug-in and describes to the WebSphere Commerce Payments how the plug-in should be deployed. It contains common properties that are used by the WebSphere Commerce Payments during system initialization to launch and send requests to the plug-in. It is used by the WebSphere Commerce installation and configuration programs to enable the payment plug-in within the WebSphere Commerce Payments and the WebSphere Commerce instance.
The plug-in deployment descriptor describes the specific configuration requirements that must be resolved for the plug-in to work correctly. The descriptor must contain the plug-in home interface name.
Plug-in deployment descriptors are named PluginDeployment.xml and reside in the deployed instance's EAR directory in WebSphere Application Server. For example, on an AIX platform, the descriptor for the SimpleOffline plug-in provided with WebSphere Commerce is found in the following location:
- WC_eardir/xml/config/ payments/ppc/plugins/SimpleOffline/PluginDeployment.xml
A plug-in deployment descriptor must exist for every plug-in, and can be used to define additional properties specific to a particular plug-in. A Plug-in deployment descriptor XSD file example and Plug-in deployment descriptor example are included in this specification.
The following table lists the set of standard properties that a plug-in must have specified in its deployment descriptor.
Plug-in property Description jndi The Java Naming and Directory Interface (JNDI) lookup name for the home of the plug-in's stateless session bean home The fully qualified name of the home class for the plug-in's stateless session bean name The name of the plug-in implementation version The version of the plug-in implementation vendor The vendor providing the plug-in implementation supportIndependentCredit Indication of whether the plug-in supports independent credits virtualTerminal The URL of the payment back-end system administration user interface. If additional unique properties must exist for a plug-in, they can be added to the plug-in deployment descriptor as plug-in properties using the <PluginProperty> element.
The following example shows the deployment descriptor for the WC Payments Cassette plug-in provided in WebSphere Commerce:
<?xml version="1.0" encoding="UTF-8"?> <Plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../PaymentPlugin.xsd"> <PluginInformation jndi="ejb/com/ibm/commerce/payments/plugin/wcpayments/bean/WCPaymentsPluginHome" home="com.ibm.commerce.payments.plugin.wcpayments.bean.WCPaymentsPluginHome" name="WCPaymentsPlugin" version="1.0.0" vendor="IBM" independentCredit="true" virtualTerminal="http://black.cn.ibm.com:5432/webapp/PaymentManager"> <PluginProperty name="hostName" value="black.cn.ibm.com"/> <PluginProperty name="port" value="5433"/> <PluginProperty name="useSSL" value="true"/> <PluginProperty name="userid" value="wcsadmin"/> <PluginProperty name="maxWCOrderCreationRetries" value="5"/> </PluginInformation> </Plugin>
Understanding the plug-in interfaces
For more details about these interfaces, see the related API information.
Plugin interface
The Plugin interface is a stateless session bean with a remote interface that 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 in this interface should map directly to the related back-end financial transactions.
Payment plug-ins are extensions to the WebSphere Commerce Payments, which provides a collective view of payment services to IBM WebSphere Commerce. The WebSphere Commerce Payments does not provide direct connectivity to a payment back-end system. Such connectivity is the goal of a payment plug-in.
The financial transactions that can be implemented through a Plugin interface are:
- Payment approval (or authorization)
- Payment deposit (or capture)
- Credit (or refund)
- Reversals for the above transactions
As a plug-in writer, you decide what methods in the Plugin interface will be implemented based on the payment protocol and the back-end system capability. Because some transactions will not apply for some plug-ins, you should determine what transactions to implement. For transactions not implemented by a plug-in, the exception FunctionNotSupportedException should be thrown.
The following table provides a list of the financial transactions to be implemented based on the type of plug-in. For updates to this list, refer to the API information for the Plugin interface.
Financial transaction Credit card Electronic check Gift
certificateDescription checkPaymentInstruction X X X Ensures all required parameters exist and are syntactically correct. Does local validation only (no communication with a payment back-end system takes place.) This transaction is always performed. validatePaymentInstruction X X X Validates any account associated with a payment instruction. Potentially performs a remote validation with a payment back-end system. approveAndDeposit X X X Approves and deposits a payment at the same time. approve X - X Approves an amount against a particular payment instruction reverseApproval X - - Cancels a previously approved payment deposit X X X Deposits an amount against a previously approved payment reverseDeposit X - - Cancels a previously deposited amount credit X - - Credits an amount against a specific payment instruction reverseCredit X - - Cancels the specified credit TimeOutException in the Plugin interface
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, if the plug-in has not 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 might be a short period for some applications can 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 might 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.
QueryablePlugin interface
The Queryable Plugin interface extends the Plugin interface and supports financial queries. As plug-in writer, you should decide if the plug-in should implement this interface. The decision to implement or not will depend on the query capability of the back-end system. It is the responsibility of the plug-in to determine whether it uses information received by querying the back-end system.
In general, the Payment Plugin Controller manages the state of financial objects for plug-ins. However, if the payment back-end system supports real-time queries, you might want to leverage this capability by implementing this interface.
By implementing this interface, you can have real-time and up-to-date status of financial objects (payments and credits). However, use of this interface will cause the need for greater network connectivity than if no querying was required.
If the payment back-end system does not support real-time queries, do not implement this interface.
When a Plugin implementation uses this interface and some of the query methods are not supported by the back-end system, the plug-in should throw the exception FunctionNotSupportedException.
PluginConfiguration interface
The PluginConfiguration is an in-memory image of the plug-in deployment descriptor. The plug-in deployment descriptor describes a plug-in implementation (plug-in metadata and configuration information). It also provides plug-in-specific properties that can be used by the plug-in during the processing of financial transactions.
PluginContext interface
The PluginContext interface provides the context of the request used in processing financial transactions and queries. For example, it provides the plug-in configuration information and the locale to be used for processing.
PaymentInstruction interface
The PaymentInstruction is a value object containing detailed information required by plug-ins to process financial transactions. It contains information including the account number, and payment or credit amounts. It does not contain information used to track a particular transaction with a payment back-end system. (Tracking information is obtained through the Payment, Credit, and FinancialTransaction interfaces.)
For an illustration of the relationship of the PaymentInstruction value object container to the Payment, Credit, and FinancialTransaction containers, see the Payment plug-in containers class diagram.
The amounts section in the PaymentInstruction represents the maximum target amount that the WebSphere Commerce Payments can collectively consume on the payment instruction.
The Payment approvedAmount attribute identifies how much has been approved (authorized) and limits how much can be deposited (captured).
The Payment depositedAmount attribute identifies how much has been deposited.
The WebSphere Commerce Payments ensures that the PaymentInstruction amount is always equal to or greater than the total amount of all requests. The WebSphere Commerce Payments will allow approve and credit financial transactions to occur up to that amount.
For example: A PaymentInstruction is created with an amount of $100.00 U.S. dollars, followed by an approve transaction of $40.00, and then another approve of $65.00. The WebSphere Commerce Payments will not allow the second approve amount to happen since it exceeds the maximum PaymentInstruction amount. The caller of the WebSphere Commerce Payments will have to decide whether to increase the PaymentInstruction's amount to permit the larger aggregated approve (authorization) amount.
Plug-ins require extra protocol data that goes beyond the standard attributes defined in the PaymentInstruction definition. These extra attributes are passed down from the WebSphere Commerce Payments to the plug-in by means of the ExtendedData class. Use the protocol parameters in the ExtendedData class to supply your own back-end system definitions so that all information related to a PaymentInstruction can be passed to the WebSphere Commerce Payments and to the plug-in. For example, use cc_brand for Credit Card and check_routing_number for Check. In addition, if your plug-in has specific needs during the invocation of the checkPaymentInstruction or validatePaymentInstruction methods, the plug-in can add specific keywords that the WebSphere Commerce Payments can store and use in subsequent transactions against the PaymentInstruction. For example, keywords can be added to represent information generated or obtained by the plug-in, such as random IDs, or external data queried by the plug-in.
Because this container is a value object, no financial transactions actually occur through this object. This object contains information about the financial transactions before, during, and after the transactions are processed.
FinancialTransaction
The FinancialTransaction interface is a value object container representing a financial transaction. This container represents all possible type of financial transactions that can be processed by a plug-in. The actual attributes used will depend on the type of transaction taking place.
A flow diagram showing an example of how a financial transaction is executed is shown in Financial transaction execution flow example.
The transaction types supported in this specification are:
- approve
- deposit
- approveAndDeposit
- credit
- reverseApproval
- reverseDeposit
- reverseCredit
The financial transactions involving reversals apply to currently approved amounts. The amount currently approved might not be obvious; for example, an approve transaction for $50 U.S. dollars can be followed by a reverse approval of $25 and another reverse approval of $25. In this case, the currently approved amount is $0. The transactions involving reversals are: reverseApproval, reverseDeposit, and reverseCredit. Reversal amounts can be equal to or less than the approvedAmount, depositedAmount, and creditedAmount.
A plug-in must update the FinancialTransaction container while processing financial transactions. Several attributes are predefined in this container. A plug-in can also add additional information to the FinancialTransaction container by using the ExtendedData class.
Response codes and reason codes
In this interface, the response code is a back-end-specific representation of a financial transaction result. It is typically used by the back-end to indicate if the financial transaction was successful or not. For example, the response code might indicate that a credit card authorization failed.
The reason code is a back-end specific representation of an error condition. It is typically used by the back-end system to indicate why a financial transaction failed. For example, it might indicate that a credit card has expired. When the response code alone cannot identify what has happened in a financial transaction, the reason code can be used to determine more precisely the financial transaction error.
The response code and reason code attributes can be viewed as primary and secondary error codes. Use them to perform problem determination when the standard plug-in exceptions that can be thrown back to the WebSphere Commerce Payments in the Plugin or QueryablePlugin interface are insufficient to determine the source of a problem.
The response code and reason codes are helpful when performing problem determination. For example, if a plug-in throws FinancialException during a credit card approve transaction, the response code and reason code might indicate whether the credit card is stolen or expired.
For successful transactions, plug-ins should always set response code "0" (String type) and reason code "0" (String type). For pending transactions, plug-ins do not have to set these two codes. For failed transactions, a list of predefined codes exist.
Note: The WC Payments Cassette plug-in provided with WebSphere Commerce sets the primary return code (PRC) of the WebSphere Commerce Payments system to a response code. It also sets the "PRCxxxSRCxxx" to the reason code.
Tracking IDs
The tracking ID is an optional attribute used by the plug-in to identify the financial transaction in the payment back-end system. It is set by the plug-in during the processing of a financial transaction, and is unique to the plug-in and in the back-end system. Although this attribute is optional, it might be the only way to track a financial transaction in the back-end system should an error occur. For example, if network connectivity is lost during a financial transaction, the plug-in would not be able to tell if the back-end system actually processed the transaction. The tracking ID is the only mechanism available to query the back-end system later on after connectivity is established again.
The reference number is an ID generated by the payment back-end system during the processing of financial transactions. It is usually required by the payment back-end system to process subsequent and related transactions. For example, during a deposit transaction, the reference number of a previous approve transaction is required. In this case, the reference number is the authorization code returned by the back-end system during the approve transaction.
While the tracking ID is used to identify a financial transaction from the plug-in perspective, the reference number is used to identify a financial transaction from the payment back-end system perspective. The tracking ID is the first identifier of the transaction to exist. After the reference number is obtained from the back-end system, the plug-in might not need the tracking ID anymore since the reference number is known by both parties, the plug-in and the payment back-end system.
Because this container is a value object, no financial transactions actually occur through this object. This object contains information about the financial transactions before, during, and after the transactions are processed.
Payment interface
The Payment interface defines a value object container for payment-related transations. This container can hold a single payment approval (authorization) and multiple deposits (captures) for the same approval. However, multiple deposits for a single approval might not be supported by all payment back-end systems.
This container is created before the approval transaction and is used on subsequent transactions such as deposits and reversals. The WebSphere Commerce Payments ensures that only one approve transaction is issued against a Payment. It also ensures that only one transaction is in a pending state 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.
The states associated with a Payment are:
- New - for a payment container object when newly created
- Approving - on a pending approve transaction
- Approved - on a successful approve transaction
- Canceled - when a payment is canceled
- Expired - when the approval has expired
- Failed - when a transaction failed
For an illustration of how a Payment moves from state to state when financial transactions or edits are executed against it, see the Payment state machine.
Because this container is a value object, no financial transactions actually occur through this object. This object contains information about the financial transactions before, during, and after the transactions are processed.
Credit interface
The Credit interface is a value object container for credit-related transactions. Credits are sometimes referred to as refunds when associated with a return merchandise authorization. Possible transactions associated with a Credit are:
- Credit
- Credit reversal
A Credit container supports only one credit transaction during its life span. However, multiple reversals can be supported for the same credit transaction.
Because this container is a value object, no financial transactions actually occur through this object. This object contains information about the financial transactions before, during, and after the transactions are processed.
The states associated with a Credit are:
- New - for a credit container object when newly created
- Crediting - when a credit transaction is pending
- Credited - when a successful credit transaction has been completed
- canceled - when a credit has been fully reversed
- Failed - when a transaction failed
For an illustration of how a Credit moves from state to state when financial transactions, queries, or edits are executed against it, see the Credit state machine.
Two types of credit transactions can occur:
- Dependent credit
Dependent credits are transactions associated with a PaymentInstruction where deposits have already taken place. For example, after a deposit of $100 U.S. dollars, a credit up to $100.00 would be considered a dependent credit.
- Independent credit
Independent credits are transactions associated with a PaymentInstruction where no previous deposits have taken place, or the amount of credit goes beyond the previously deposited amount. For example, after a deposit of $100.00, a credit of $150.00 is an independent credit. Also, without any previous deposit, a credit of any amount would be an independent credit.
Support for dependent and independent credits can vary among payment back-end systems.
A plug-in can access the associated Payment containers to determine if a credit transaction depends on a previous deposit transaction. If that is the case, the credit transaction can be handled as a dependent credit and the plug-in can proceed accordingly. Otherwise, the transaction is an independent credit and the plug-in has to deal with it as such.
Understanding the plug-in classes
ExtendedData class
In a payment plug-in context, extended data is non-standard protocol data required in financial transactions. The ExtendedData class collects non-standard protocol data required by a financial transaction. Plug-ins require extra protocol data that goes beyond the standard attributes defined in a PaymentInstruction container. These extra attributes are passed from the WebSphere Commerce Payments to a plug-in through the ExtendedData class.
When associated with a PaymentInstruction, the ExtendedData class is potentially used by all financial transactions executed against the same PaymentInstruction.
However, ExtendedData can also be attached to a particular FinancialTransaction container so that the additional attributes are used only in the same FinancialTransaction container. Subsequent financial transactions can reuse the contents of the ExtendedData class if they are related to a previous FinancialTransaction container.
NamedValueObject
The NamedValueObject class represents a data attribute with a name, a value, and an encryption flag. These objects are typically used to store information about a protocol, and make up the ExtendedData class. If the encryption flag is set on the name-value pair, the attribute values will be encrypted while stored in the WebSphere Commerce database.
PluginMessages
The PluginMessages class defines standard translated messages and the utility to retrieve the messages. For a list of the standard plug-in messages, see the API information for this class. Plug-in messages are included in logged exception messages. The predefined WebSphere Commerce tracing component, WC_PPC_PLUGIN, is used as the WebSphere Application Server logger name for plug-in messages.
The properties file for messages is located in the following directory:
- WC_eardir/properties/com/ibm/commerce/negotiation/properties/com/ibm/commerce/payments/plugin/PluginMessages *.properties
- WCDE_installdir\properties\com\ibm\commerce\payments\plugin\PluginMessages *.properties
Payment plug-in error handling
The payment plug-in specification identifies a set of predefined exceptions. If a plug-in does not implement a particular method, the plug-in should throw the exception FunctionNotSupportedException. If additional exceptions need to be added for a plug-in, the exception PluginException should be extended. However, the WebSphere Commerce Payments will not be able to process these exceptions in any particular way. Although all exceptions are caught, plug-in-specific errors cannot be handled properly. For example, a FinancialException informs the WebSphere Commerce Payments that some financial error occurred and the WebSphere Commerce Payments can act accordingly (it can inform other software layers such as Payment Rules that the payment instruction is not good). However, if an ABCException occurs, it is wrapped as a generic plug-in exception.
Exceptions thrown by a plug-in should contain as much contextual information as possible to allow convenient error handling and problem determination. Information can include the result codes from the payment back-end system, and container reference to the payment instruction, payment, and credit.
WebSphere Commerce provides a hierarchy of plug-in related exceptions:
There is a common exception PluginException. There are six exceptions extending from PluginException to identify various kinds of exception scenarios:
Note: Besides the exception listed here, when you are developing your own plug-in, you can define you own exception for your special case, but this exception should extend from PluginException to facilitate the handling of WC Payments.
- InvalidDataException
- This exception is thrown when invalid parameters are passed in or out of the plug-in specification interfaces. The class name and method name, message key, previous exception (if any) and invalid parameters should be set in the attributes of the exception. For example, a payment service provider requires the division number registered by the merchant, but the plug-in does not get this attribute, then the InvalidDataException is thrown.
- CommunicationException
- This exception is thrown when it experiences a connectivity problem while communicating with the payment back-end system. The class name and method name, message key, previous exception (if any) and the parameters/reason resulting in this exception should be set in the attributes of the exception. For example, when the plug-in fails to connect to the host of the payment service provider, the CommunicationException is thrown.
- FinancialException
- This exception is thrown whenever a transaction against the back-end system fails with a financial error. The class name and method name, message key, previous exception (if any) and the parameters or reason resulting in this exception should be set in the attributes of the exception. There are three sub-exception of this exception:
- ApprovalExpiredException
- This Exception is thrown when the payment approval (authorization) has expired.
- InvalidPaymentInstructionExcepiton
- This exception is thrown to indicate the PaymentInstruction is invalid.
- PaymentInstructionBlockedException
- This exception is thrown when a financial transaction cannot be processed against a PaymentInstruction. This is a temporary situation. The financial transaction can be tried again after some time, against the same PaymentInstruction. For example, the credit card associated with a payment instruction might have been put on hold.
- FunctionNotSupportedException
- This exception is thrown when a type of financial transaction is not supported by the plug-in implementation. The class name and method name, message key, previous exception (if any) and the parameters or reason resulting in this exception should be set in the attributes of the exception. For example, if the plug-in does not support approveAndDeposit API but the merchant tries to call this API, then the FunctionNotSupportedException is thrown.
- ConfigurationException
- This exception is thrown by a plug-in when it cannot find required information in the plug-in configuration. The class name and method name, message key, previous exception (if any) and the parameters/reason resulting in this exception should be set in the attributes of the exception. For example, if the configuration in the plug-in deployment xml file is invalid, then the ConfigurationException is thrown.
- InternalErrorException
- This exception is thrown when an unexpected error happened in the plug-in implementation. The class name and method name, message key, previous exception (if any) and the parameters/reason resulting in this exception should be set in the attributes of the exception. For example, if the plug-in receives the response from the gateway of payment service provider with invalid format, then the InternalErrorException is thrown.
- TimeoutException
- This exception is thrown if a plug-in times out waiting for a response. The class name and method name, message key, previous exception (if any) and the parameters or reason resulting in this exception should be set in the attributes of the exception. For example, if the plug-in is configured such that the time out waiting for a response is over and there has been no response, then TimeoutException is thrown.
Security considerations for payment plug-ins
Payment plug-ins are responsible for the security of the communication with their payment back-end systems. Since payment information is sensitive data, the plug-ins should encrypt all data going back and forth through network connections. The WebSphere Commerce Payments does not provide encryption services for this type of communication with the payment back-end system.
All sensitive data in a PaymentInstruction container is encrypted by the WebSphere Commerce Payments.
If the plug-in persists sensitive data on its own, either in the file system or using databases, this sensitive data should be encrypted. The WebSphere Commerce Payments does not provide encryption services for this persistence.
If, as a plug-in writer, you decide to use J2EE/EJB access control, the plug-in documentation you produce needs to be clear about what user roles and permissions are required to use the plug-in implementation so that the plug-in can be deployed accordingly.
Transient sensitive data should be removed by the plug-in whenever it is necessary and as soon as possible; for example, if the Card Validation Code is only required during the first authorization, the plug-in implementation should remove it during the Plugin.approve( ) invocation.
(C) Copyright IBM Corporation 1996, 2006. All Rights Reserved.