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:

*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:

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

 

Specification description

 

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:

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:

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
certificate 		Description
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:

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:

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:

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:

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:

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:

 

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:

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

 

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.

Related tasks

(C) Copyright IBM Corporation 1996, 2006. All Rights Reserved.