Cassette for BankServACH

A BankServ purchase example

The following is an example of how a typical purchase using the Cassette for BankServACH would be processed by the overall system, including WebSphere Commerce Payments and the Cassette for BankServACH. This example assumes the use of the AutoApprove and the AutoDeposit options of the AcceptPayment command.

Note:

Other commands result in different messages being sent to the BankServ host, but the same general flow applies.

1. The merchant software presents the shopping catalog to the buyer. The buyer shops and then initiates a purchase, typically by clicking the Buy button on the page.
2. The merchant software then requests the electronic check information from the buyer over a secure (typically SSL protected) connection.
3. The merchant invokes WebSphere Commerce Payments with an AcceptPayment command with AutoAuth and AutoDeposit.
4. WebSphere Commerce Payments and the Cassette for BankServACH update the WebSphere Commerce Payments database with the information needed to perform the transaction.
5. The Cassette for BankServACH builds the Electronic Check request and sends it to the BankServ payment gateway using the HTTPS protocol.
6. The BankServ payment gateway validates the data and returns the transaction status to the cassette.
7. The Cassette for BankServACH updates the WebSphere Commerce Payments database to reflect this status.
8. At a predetermined time, the BankServ host sends all the requests it has accumulated to the ACH processor. Note that no indication of this action is passed back to the cassette.

WebSphere Commerce Payments object model implementation

This section describes how the Cassette for BankServACH supports the administrative and financial object models that the WebSphere Commerce Payments framework provides.

• Administration objects
• Financial objects

Administration objects

The WebSphere Commerce Payments administration objects are the entities that comprise the system and merchant configuration under which all financial transactions will be performed. The Cassette for BankServACH augments three of the framework administration objects with its own attributes. BankServ Administration objects are described in detail in Cassette for BankServACH object reference.

Cassette Admin object

The CassetteAdmin object represents the cassette itself and contains attributes that apply globally across the cassette. The Cassette for BankServACH extends this object with attributes that tell the cassette how to connect to the BankServ host.

Account Admin object

In the WebSphere Commerce Payments object model, the AccountAdmin object represents a relationship between a given merchant and a given financial institution. This is exactly the type of relationship that each BankServ merchant account represents. The cassette extends the WebSphere Commerce Payments AccountAdmin object with attributes that identify and describe the corresponding AccountAdmin merchant account.

PaySystem Admin object

Each PaySystemAdmin object represents configuration data that is different for each merchant, but common across all accounts for the given merchant. This term is synonymous with Merchant Cassette Settings. The Cassette for BankServACH allows the merchant to define a single account in the PaySystemAdmin object.

Financial objects

The WebSphere Commerce Payments financial objects are used to represent the financial transactions run by merchants. The Cassette for BankServACH provides extensions for each of these financial objects:

• Order objects
• Payment objects
• Batch objects

For details on how the Cassette for BankServACH extends these payment objects, see Cassette for BankServACH object reference.

Cassette-specific characteristics and behaviors

This section discusses characteristics of communication parameters and the WebSphere Commerce Payments command set that are unique to the Cassette for BankServACH.

Retry parameters

The Cassette for BankServACH extends the WebSphere Commerce Payments Cassette object with several parameters related to communicating with the BankServ host. Several of these parameters control the attempts of the cassette to recover after failed communications with the BankServ host. These parameters appear on the BankServ Cassette Settings screen as follows:

• Connect Retries
• Connect Timeout
• Read Timeout
• Immediate Retries
• Attempt Interval
• Max Attempts

You can modify any of the Cassette Settings values by using the user interface (select Cassettes under the navigation frame, then select the BankServ cassette icon, then select Advanced Settings) or by using the ModifyCassette API command. For more information about the ModifyCassette command, see ModifyCassette.

Connectivity information and retry information will be stored as cassette extensions.

• The $CONNECTRETRIES protocol data is related to establishing the connection. It indicates the number of attempts that will be made to establish a connection with the BankServ gateway.
• The $CONNECTTIMEOUT protocol data indicates the number of seconds to wait while attempting a connection to the BankServ gateway.

The following data relates to communications after the connection has been established.

• The $READTIMEOUT protocol data indicates the number of seconds to wait for a response while communicating with the BankServ gateway.
• The $MAXRETRIES protocol data indicates the maximum number of immediate retries that will occur before the delayed retries take effect.
• The $MAXATTEMPTS protocol data indicates the number of delayed retries that will be attempted.
• The $ATTEMPTINTERVAL protocol data indicates the number of seconds to wait before retrying the communications.

Under direction of these parameters, the cassette will attempt to recover as described in the following paragraphs.

For each command that requires communication with the BankServ server, a HTTPS connection must be established between WebSphere Commerce Payments and the BankServ server. If the initial connection to the server for a given command cannot be established, the cassette can immediately retry the connection. The number of immediate connection retries is specified by the ConnectRetries parameter (this parameter is called $CONNECTRETRIES on the ModifyCassette API command).

Once a connection is established to the server, the cassette sends an appropriate request message to the server and then waits for a predetermined period of time for a response. If the cassette receives a response message indicating that the request is complete before a timeout occurs, the message exchange is considered complete. Otherwise, this is considered one communication attempt, and the cassette will retry the operation $MAXRETRIES times. If the communication is unsuccessful after all immediate retries have been attempted, the cassette enters delayed retry logic.

Specifically, delayed retries work as follows:

• The cassette will return a return code that indicates the operation is pending (PRC_OPERATION_PENDING).
• The request message is queued and waits a predetermined amount of time as specified by the cassette setting called AttemptInterval (this parameter is called $ATTEMPTINTERVAL on the ModifyCassette API command).
• Once the attempt interval expires, the request is removed from the internal queue and is retried.
• The process of queuing the request and retrying the operation is repeated until the request is completed or until the maximum number of communication attempts is reached. The maximum number of communication attempts is specified by the MaxAttempts (this parameter is called $MAXATTEMPTS on the ModifyCassette API command) value in the cassette settings.

Security considerations

On workstation systems, the BankServ system uses 128 bit SSL encryption. In order to support this, the cassette uses the IBMJSSE.JAR file provided by the IBM^(R) version of the Java^(TM) Secure Socket Extension (JSSE). Three actions are required to use this file:

• A protocol package must be specified.
• A provider must be defined.
• The location of the certificates must be defined.

Within this jar file is a reference implementation of the protocol which has been configured within the cassette by setting the system property java.protocol.handler.pkgs to com.ibm.net.ssl.internal.www.protocol. The provider has been specified within the cassette via the following call:

Security.addProvider(new com.ibm.jsse.JSSEProvider()); 

Finally, the required certificates can be found in the cacerts file in the <java_home>jre/lib/security/ directory where <java_home> is the directory referenced by the JAVA_HOME environment variable. If these system provided certificates are satisfactory, no action is required.

If the system-provided certificates are not satisfactory, you can provide your own set of certificates by creating a jssecerts file in the cacerts file directory. The implementation firsts looks for a jssecerts file in this directory. If found, this file is used. If not found, the cacerts file is used. The jssecerts file can be created by using either the graphical IBM Key Management tool (ikeyman) or the command line tool (keytool). Refer to the Tools for managing certificates and keys section of the WebSphere documentation for instructions.

Performance considerations

The Cassette for BankServACH uses service threads when communicating with the BankServ host. Since there is a limited number of service threads available (three by default), resources may not be available to handle a communications request. If a service thread is not available, the request waits until one becomes available. Since service threads are also used by the cassette for retries, and by other cassettes, the number of service threads may have to be increased.

On a lightly loaded system, with no other cassettes using the service queue and a quickly responding server, the default value may suffice. On a heavily loaded system with many concurrent requests, a larger value will be required. This value is specified in the Payments instance's configuration by using the Configuration Manager (spool size field).

Cassette for BankServACH payment command summary

Table summarizes the way the Cassette for BankServACH handles each of the WebSphere Commerce Payments payment commands (that is the commands that carry out financial transactions). Specifically, for each payment command, the table shows:

• Not supported by cassette, meaning the cassette does not support that particular command. These commands will always receive return codes PRC_COMMAND_NOT_SUPPORTED, RC_NONE.
• Handled by WebSphere Commerce Payments; no message sent, meaning that the command is processed completely within WebSphere Commerce Payments without communicating with the BankServ payment gateway.
• In any other case, the primary BankServ command (or commands) used to accomplish the function will be shown.

Summary of state changes

The following table summarizes the state changes that Order, Payment, Credit and Batch objects undergo as a result of successful completion of each payment command. Only those objects whose states actually change as a result of the given operation are shown. Any other existing object states remain unchanged.