The VirtualTerminal.ocx control may be acquired from Rossware, as one of a fewfiles contained in a .zip folder, obtainable at:

Download Virtual Terminal SDK

Like any ActiveX component, by design VT should be capable of incorporationwithin applications written in a wide variety of programming languages and environments. For purposes of simplicity within this Handbook, we will assumeyou are using VB6. If otherwise, please adapt as appropriate.

Steps for incorporation are as follows:

1. ‍Add VirtualTerminal.ocx to your c:\Windows\System32 (or otherappropriately applicable) folder.
2. ‍Add any other needed Windows runtimes. In particular, you will needmsxml3.dll (which is also provided in the vt_sdk folder). You will alsoneed standard VB6 runtimes, which most platforms already haveinstalled.
3. ‍Open or create the project in which you want to add VT.
4. ‍From the Add Components tab, find and add the previously installedinstance of VirtualTerminal.ocx.
5. ‍Open or create the form in which you want the VT interface to appear.From the VB6 Toolbox, select the VirtualTerminal, and add it to yourform.
6. ‍Position the control as desired, and size its dimensions as appropriate toaccommodate its contents.
7. ‍Write code to access the control’s methods, as per programmingpurposes and intent.

Details, as applicable to Step 7, are what we turn to now.

VirtualTerminal.ocx has just three methods, as follows:

1. ShowForGeneralOpen
   
   Use this method to activate the VT interface for general userinteraction. In other words, the interface is activated in a modewhere the user can run as many transactions and in whatever amountas wanted. There are no arguments in the call, and no information(i.e., regarding transactions conducted) comes back to the callingclient.
   This method makes the interface into the equivalent, more or less, ofa stand-alone terminal.
2. .ShowForParticularXaction
   
   Use this method to activate the VT interface for a particulartransaction that, typically, is advance-specified by the calling client asto Amount and Ticket Reference. The method is a Function, andreturns as True if the transaction is successful, False if it is not. Itincorporates the following arguments.

3. .EndOpenState
   
   This method (like the one just described) is also a Function. It is usedto assure VT closes, as a process, when it should, and that it does soin a good and proper manner. It returns as True when closing iscomplete. You should write your application so that neither it, nor 4any form that displays the VT closes until this method is first called,and returned as True.
   
   The reason this is important is because there is typically a period ofone to three seconds (sometimes more), after a transaction has beeninitiated by the user, and prior to the response being returned byMerchant Warehouse. Absent the precaution as provided by thismethod, it’s possible a calling client could close itself while the VirtualTerminal is still waiting for a response from MW. It’s possible,furthermore, the response could come back indicating a successfultransaction — while in the meantime the application (and/or itsapplicable processes) have already closed, and therefore fail toregister the transaction.
   
   Please follow good practices and assure you do not let your callinginterface close until after this call is successfully completed.
   

For programming with VirtualTerminal.ocx, all you must do is write the verysimple code as needed to call (and utilize per your own programming intent) thesemethods.

The Virtual Terminal has one event that’s deliberately provided and exposed. It isthe .Error event. The event will trigger when and if the Virtual Terminalencounters an error in execution. For optimum programming, you should place ahandler in the VirtualTerminal_Error procedure.

Also provided in the vt_sdk.zip folder is very simple VB6 project that invokes themethods of VirtualTerminal.ocx. It is a simple program. It has no modules, noclasses, and no user controls. There is only one, very basic form containing threeobjects: the VirtualTerminal (internally named “VT”), and two command buttons.There is so little code involved as to be nearly comical. Following is a snapshotthat shows (aside from what’s cutoff at the far-right) its entirety.

That’s right. The above is all the code as strictly required for an application thatharnesses all three VT methods, and appropriately responds to the .Error event.For a person with even minimal programming skills, it should be child’s play to seehow this code works, and to fathom how one might similarly implement within hisor her own application.

This sample program is also provided in compiled format (Test_VT.exe). Thisallows you — using just two files, Test_VT.exe and VirtualTerminal.ocx — to fullyrun the VT interface, and to experiment with functionality (at least assuming yourplatform is otherwise appropriately runtime-equipped and that you possess anappropriate MW merchant test account for testing purposes). In fact, with a realmerchant account you could even run real/live transactions — using nothing morethat’s specific to the purpose than the two files here described.

This section describes underlying structure and processes within the VT, and is notdirectly needed for programming integration. If your sole interest is in creatingthe integration, this section (indeed, the remainder of this handbook) may beskipped.

The VT GUI is divided into six functional areas.

The first provides textboxes for the user to insert his or her Merchant Credentials.

These are the particular strings that identify and authenticate the user/merchantto MW. Since there are no major security concerns as connected to MerchantCredentials, VT direct-stores them (i.e., without encryption) in the platform’ssystem registry.

The second section is where the user may type cardholder information for a keyed(card-not-present) transaction.

The user may activate this section by clicking on the provided button. Informationas typed here is never stored anywhere. It exists solely as text in the displayedtextboxes – meaning when removed from those boxes (or when the boxesthemselves are closed) the data is extinguished in its entirety — at least so far asany involvement by VT and/or its operating platform is concerned. This data’spresence in/on the platform is thoroughly transitory, in other words, and is neverin any circumstance written to non-volatile memory.

Of course, if used in a transaction with MW, the applicable text will be forwarded(as part of the transaction, and via a Secure Socket Layer connection) to thatentity, and presumably may persist in MW systems to whatever extent MW allows.

The third functional area is used in conjunction with connecting to an MCR devicefor card swiping.

If the device connects via USB, the end-user needs to check the applicable button.In reaction, the VT scans for and connects to the device. If the device connectsvia serial port, the end-user should provide the correct CommPort number withinthe dropdown provided (and in reaction the VT will appropriately connect). Thethird option in this section (provided by a button that contains rather small print)is used to initiate a swipe with any MCR device that mimics keyboard-based input.

Much like Merchant Credentials, settings in this section are saved in the platform’ssystem registry.

Though not visible as such in the illustration, the fourth functional area becomes amomentary-display textbox during and/or immediately after a swipe.

This textbox contains actual data as swiped from the card (albeit in disguised-tothe-userformat, with actual/true characters replaced by asterisks, much as in atypical password-input interface). Aside from when momentarily included in anactual transaction message (via Secure Socket Layer), this textbox is the onlyplace such swiped data is ever placed by VT.

Just like with keyed-in data, this data is never “stored” anywhere. As soon as itscontaining box is closed (an object that’s maintained purely in volatile ram), thedata is totally and thoroughly extinguished.

The fifth functional area is for specifying details about the desired transaction (i.e.,amount, type, etc.).

Though unrelated to security purposes, nothing in this section is stored. It is usedsolely for the duration (and as needed) for a particular transaction.

The sixth functional area contains two buttons.

One is for opening the user handbook (same as referenced on this document’s firstpage).

The other will activate, and turn to an operative green color, when other elementsin the GUI are appropriately setup for a transaction. The user clicks on it, ofcourse, to initiate a transaction.

The sixth functional area (note that when functionally appropriate, it willsupersede the area consumed by the third area) is used to communicate with theuser, indicating such matters as when the VT is scanning for an MCR device, whenone is located, when the setup is ready for a swipe, and so on.

Additionally, once a successful transaction has been conducted, this area displaysinformation concerning the result.

‍

This is another section that is not truly needed if your sole interest is in integrativeuse of VT. Much as it’s easy to drive a car without knowing how the engine works,details here are not required reading.

VT uses MW’s Merchantware 3.0 interface.

Under that system, communication between VT and MW (client and gateway) isconducted using web services via an https secure socket layer (ssl) connection.This connection encrypts the communication stream, assuring impossibility of anymeaningful interception.