Deprecated feature

Cassette for VisaNet

WebSphere Commerce Payments provides a unified interface which merchants can use multiple payment protocols in a common way. Each WebSphere Commerce Payments cassette attempts to extract protocol-specific differences so that merchants can ignore disparities between protocols.

This section describes how the Cassette for VisaNet presents the VisaNet services by the WebSphere Commerce Payments object model and API set. In addition, cassette-specific behaviors and requirements are discussed.

The Cassette for VisaNet implements the payment commands and the payment processing model of the WebSphere Commerce Payments framework, using the processing services of VisaNet. This implementation supports:

  • AcceptPayment creation of orders only. Wallet-driven purchases are not supported.
  • Traditional payment-oriented commands.
  • Multiple batches for each merchant.
  • Multiple batches for an account, one for each currency.

VisaNet purchase example

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

Note: Other commands result in different messages being sent to the VisaNet host, but the same general flow still applies.

Figures shows a typical purchase flow from the consumer's browser all the way to the merchant software as described in the numbered paragraphs that follow.
  1. A consumer has been shopping online at a merchant Web site. After choosing several items to purchase, the consumer initiates a purchase, typically by pressing a Buy button on the shopping page.
  2. The merchant software then requests card information from the consumer over a secure (typically SSL-protected) channel. This information includes the credit card number, the card expiration date, the card brand and possibly the cardholder's address.
  3. Once this cardholder information has been received, the merchant software invokes the WebSphere Commerce Payments AcceptPayment command with card information and parameters, requesting that the purchase be approved immediately.
  4. The WebSphere Commerce Payments and the Cassette for VisaNet record the information they need to run payment transactions.
  5. The Cassette for VisaNet sends an approve request to the VisaNet host.
  6. The VisaNet host forwards this request to the financial institution which processes the request and responds to the VisaNet host.
  7. The VisaNet host records the result, and sends a success response to the cassette.
  8. The Cassette for VisaNet, along with the WebSphere Commerce Payments update status in the database and return the success response to the merchant.
  9. The merchant software replies to the consumer with an indication that the order is accepted.

WebSphere Commerce Payments object model implementation

This section describes how the Cassette for VisaNet supports the administrative and financial object models provided by the WebSphere Commerce Payments framework.

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 VisaNet augments three of the framework administration objects with its own attributes. VisaNet Administration objects are described in detail in Object reference.

Cassette Admin object
The CassetteAdmin object represents the cassette itself and contains attributes that apply globally across the cassette. The Cassette for VisaNet extends this object with attributes that tell the cassette how to connect to the VisaNet 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 VisaNet 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 VisaNet allows the merchant to define multiple accounts in the PaySystemAdmin object.

Figure shows the relationship of the Cassette and Merchant to Merchant Cassette Settings, and to one or more Accounts.

Financial objects

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

  • Order objects
  • Payment objects
  • Credit objects
  • Batch objects

For details on how the Cassette for VisaNet extends these payment objects, see 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 VisaNet.

Retry parameters

The Cassette for VisaNet extends the WebSphere Commerce Payments Cassette object with several parameters related to communicating with the VisaNet host. These parameters appear on the VisaNet Cassette Settings screen as follows:

  • SSL Read Timeout
  • SSL Max Retries
  • Attempt Interval
  • Max Attempts

There are four connection methods: Vital and leased line, FHMS and leased line, Vital and SSL, and FHMS and SSL. The SSL Read Timeout field and SSL Max Retries field are applicable only to Vital and SSL, and FHMS and SSL.

The Attempt Interval field and Max Attempts field are applicable to all connection methods and control the attempts of the cassette to recover after failed communications with the VisaNet host. These parameters are used in pending operations and are not actually related to connection methods and communication protocol.

You can modify any of the Cassette Settings values by using the user interface (select Cassettes under the navigation frame, then select the VisaNet cassette icon, then select Advanced Settings) or by using the ModifyCassette API command. For more information about the ModifyCassette command, see Command reference. The cassette will attempt to recover communications failures under the direction of the preceding parameters.

For each command that requires communication with the VisaNet host, a connection must be established between WebSphere Commerce Payments and the VisaNet host. Once this connection is established, the Cassette for VisaNet attempts to send an appropriate request message and then waits for a period of time for a response. The amount of time the cassette will wait for a response is based on the ReadTimeout parameter (this parameter is called $READTIMEOUT on the ModifyCassette API command). 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 immediately retry the operation based on the Max Retries parameter (this parameter is called $MAXRETRIES on the ModifyCassette API command). 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 Attempt Interval.
  • 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 Max Attempts value in the cassette settings.

Guidelines for setting retry parameters

Care should be taken when setting up the cassette's communication retry parameters. If timeouts and or retries are excessive, the performance of the cassette could be adversely affected. It is strongly recommended that the following guidelines are followed:

  • The combination of the ReadTimeout and the MaxRetries should never equal or exceed 3 minutes. For example, if the ReadTimeout is specified as 60 seconds, and the MaxRetries is specified as 3, then the combined timeout value would be 3 minutes.
  • To ensure good cassette performance and throughput, keep the ReadTimeout as low as possible. It is recommended that the ReadTimeout be specified as 30 seconds or less.

Cassette for VisaNet payment command summary

The following table summarizes the way the Cassette for VisaNet 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:

  • Which payment card function will be performed by the command (using terminology more common to the payment card industry)
  • How the cassette processes the command:
    • Not supported by cassette means the cassette does not support that particular command. These commands will always receive return codes PRC_CASSETTE_ERROR, RC_COMMAND_NOT_SUPPORTED.
    • Handled by WebSphere Commerce Payments; no message sent means that the command is processed completely within WebSphere Commerce Payments without communicating with a VisaNet host.
    • In any other case, the primary VisaNet command (or commands) used to accomplish the function will be shown.
API command Payment card functions VisaNet message
AcceptPayment No comparable function Handled by WebSphere Commerce Payments; no message sent
AcceptPayment with AutoApprove Authorize Authorization
AcceptPayment with AutoApprove and AutoDeposit Authorize Authorization
Approve Authorize Authorization
Approve with AutoDeposit Authorize Authorization
ApproveReversal Authorize reversal Authorization with appropriate reversal information
BatchClose Close an existing batch Data Capture
BatchOpen Open a new batch Not supported by cassette (Cassette opens batches internally as needed.)
BatchPurge Purge an existing batch Handled by WebSphere Commerce Payments; no message sent
CancelOrder No comparable function Handled by WebSphere Commerce Payments; no message sent
CloseOrder No comparable function Handled by WebSphere Commerce Payments; no message sent
DeleteBatch No comparable function Handled by WebSphere Commerce Payments; no message sent
Deposit No comparable function Handled by WebSphere Commerce Payments; no message sent
DepositReversal No comparable function Handled by WebSphere Commerce Payments; no message sent
ReceivePayment No comparable function Not supported by cassette
Refund No comparable function Handled by WebSphere Commerce Payments; no message sent
RefundReversal No comparable function Handled by WebSphere Commerce Payments; no message sent

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.

API Command Object-State
AcceptPayment ORDER_REFUNDABLE
AcceptPayment with AutoApprove ORDER_REFUNDABLE PAYMENT_APPROVED
AcceptPayment with AutoApprove and AutoDeposit ORDER_REFUNDABLE PAYMENT_DEPOSITED
Approve PAYMENT_APPROVED
Approve with AutoDeposit PAYMENT_DEPOSITED
ApproveReversal, amount is non-0 PAYMENT_APPROVED
ApproveReversal, amount=0 PAYMENT_VOID
CancelOrder ORDER_CANCELED
CloseOrder ORDER_CLOSED
Deposit PAYMENT_DEPOSITED
DepositReversal PAYMENT_APPROVED
Refund CREDIT_REFUNDED
RefundReversal CREDIT_VOID
BatchClose BATCH_CLOSED PAYMENT_CLOSED CREDIT_CLOSED ORDER_REFUNDABLE
DeleteBatch Deletes the batch