TraPr Integration Document

Last edited: December 15, 2003 08:19 AM

TraPr (Transaction Processor) is a Windows server application that allows TouchPRO to authorize and capture credit card Transactions. This document is designed for the developer who wishes to integrate with TraPr from the perspective of the EditPRO application. It will not detail how to use TraPr or EditPRO. See the manuals for those products for that information.
What is needed?

To integrate with TraPr, the following items are needed:

    * At lease one workstation running TouchPRO version 6.5 or greater.
    * A Windows95 (or greater version of windows) workstation on the network.
    * An appropriate DataTran device programmed with the proper Network settings.
    * A Copy of TraPr installed on the Win95 workstation.

DataTran

See DataTran ML E-Payment Modem for current information on the model currently used.  The following paragraph is obsolete but retained for the purpose of providing information on older systems.

TraPr works with the DataTran model 162ND, which holds approximately 166 VisaNet transactions, and the DataTran model 162ND Plus which holds approximately 3.5 times as many VisaNet transactions.  Both models use the same DataTran programming from DataCap, of which the current program as of this writing is VISANet,AutoStore – TOS Version 1.50 – Network Version 3.82 (DataCap #50382).  TraPr will also work with the earlier VISANet, Autostore – TOS Version 1.47 – Network Version 3.61 (DataCap #47361).  Note that the TID sheet is different between the two versions.
Considerations

When integrating an existing TouchPRO application (styling and database) with TraPr, the following items will need to be considered:

    * Media’s in TouchPRO to correspond with TraPr Media’s (See the section about Media’s)
    * Card readers will need to be installed and used
    * The styling will need to accommodate the wide range of scenarios that are encountered during credit card processing, as well as reporting.

Architecture

This diagram shows the relationship between TraPr and TouchPRO. Because TraPr runs on a Win95 machine, it may reside on the same station as a running TouchPRO application. However this is not likely to be the case.

TraPr communicates with the TouchPRO application through a communication file that exists in the Application folder (for example: C:TouchnetJoesCafe). When it needs to process a transaction or run a report, it submits a request through this file. It then waits for up to 10 seconds for an Acknowledgment (ACK) for the request. This is to assure that TraPr is indeed operational in the network. If an ACK is not received then an error message in TouchPRO informs the user that TraPr is not responding.

TraPr also knows the formats for several of the native TouchPRO files. For instance, when a credit card is to be submitted for approval, TouchPRO first stores the check, with the TraPr variables loaded with all of the pertinent information. It then makes a request using the method described above, for TraPr to authorize the credit card. TraPr then opens and reads the Check file (.CHK) and processes the transaction. It places its response back into the .CHK file, and then communicates to TouchPRO that it has completed.

TraPr also makes updates to the Journal (.JOU) files and the Server Report (.CSI) files, whenever monetary transactions take place. This is to keep the reporting in synch.
Workload distribution

Who does what? The following table lists the tasks that may be performed, and whether they can be done up front on a TouchPRO workstation, or if they may only be done, using the TraPr software.

Actions that may be performed by TraPr are built into the user interface. Actions that may be performed by TouchPRO must be styled in using the appropriate instructions, variables and styling logic.
Action to be performed

TraPr

TouchPRO
Open/Close (Deposit) Batch

X

Batch Report

X

X
Server Report (for Batch Transactions)

X

X
Authorize a Credit Card Sale

X

X
Add a Gratuity

X

X
Enter a Pre-Authorized Transaction

X

Credit a Customer’s Account

X

Void a Credit Card transaction

X

X
Reprint a Sales Draft

X
Medias

The Media numbers in TouchPRO (as configured in EditPRO) are flexible. The Media numbers in TraPr are not (because of the DataTran device). Because every application may assign different numbers to different Media’s (i.e. 4=Visa, 5=AMEX), it is necessary to tell TouchPRO which TraPr Media a specific TouchPRO Media should represent.

This is done in EditPRO, under Maintain/Media Definitions. Select a Media that you wish to assign to a TraPr Media and press Enter to edit it. There are two new fields in version 6.5 that you will now see.

TraPr Media # is where you enter the corresponding Media number that TraPr will use for this Media. See the table below for a list of the Media numbers that TraPr recognizes.

Authorize at is a field that is not yet implemented. For now, ignore this and leave it set to 0.00.

Here are the Media’s TraPr recognizes along with their Media Number.

1
Checks

2
AMEX

3
Visa

4
Master Card

5
Discover

6
Private

7
Diners Club

8
JCB

9
Debit

If while attempting to authorize a Credit Card Transaction, you see the error “Media Not programmed” this is one place to start checking. Of course, you would also want to check Media Programming in the Network Programming section of TraPr. But that subject is covered in the TraPr manual.
Variables

In styling your integration with TraPr, you will be using the variables described below. These variables are all contained within the scope of a Check. This means that when a Check is Retrieved and Stored that the values in them will go with the check.

When TraPr takes a check that is to be approved, it reads the values from these variables. It alters them, and places them back into the check. Then when the user retrieves the check, it becomes the responsibility of the stylist to read the values, and determine the results of the transaction.

IMPORTANT: It should be noted, that when a check is stored, other then in the course of submitting it to TraPr for approval, all the values in these variables will be wiped clean. This is to assure that Credit Card Account numbers etc, do not carry over from previous transactions and cause an error.

Here are the variables, and what they are used for:

    TraPr: Track2
    This variable is used to contain the contents from the Credit Card’s Track number 2. If a card is hand entered, then the variable should be left empty.

    TraPr:Media Type
    Leave this variable set to 0 (zero). It may have application in future versions that accept Debit cards. But for today it is mostly resolved automatically based on the Credit Card account number.

    TraPr:Expiration
    This variable is for use when a Credit Card is hand entered. If the card is swiped the information is in the TraPr:Track2 variable. If used, the format should be mmyy. For example, an expiration of December 2005 would be keyed as 1205.

    TraPr:Account
    This variable is for use when a Credit Card is hand entered. If the card is swiped the information is in the TraPr:Track2 variable. If used this variable should contain the account number from the card.

    TraPr:Amount
    This variable is used to contain the amount that is being charged to the Customer’s card. If the amount entered is greater then the sale amount, then the difference will be subtracted from the Cash Media at reporting time. If the amount entered is less then the sale amount, then the remaining balance may be covered by additional Media’s (which may also be TraPr approved).

    TraPr:Gratuity
    This variable is used to specify a gratuity. It may be used during the authorization process, or left empty and later used to add a tip to an already approved transaction. This amount will be reduced from the Cash Media at reporting time, and will also appear on the Cashier/Server report as a Gratuity, in the appropriate Media.

    TraPr:Result
    This Read Only Variable is used to return with the result of the last TraPr operation. Here is a list of the possible values and what they mean.

0
Nothing. There is no TraPr transaction pending on this check.

2
TraPr Failure. The TraPr software failed. It may have gone down and been restarted. Resubmit, leaving the TraPr variables in tact.

3
Approved. The Transaction was approved. It was not auto-printed, so the stylist is now required to print the draft and respond accordingly.

4
Denied. The bank denied the transaction. The TraPr:Message variable will contain the exact text of the Bank generated error message.

5
Media not Recognized. This media is not programmed into the DataTran.

6
Bad or Missing Information. This may occur if a hand entered transaction (where TraPr:Track2 is empty) is missing the Account number or Expiration Date.

7
Not currently used.

8
Not Authorized. This transaction was not authorized, and the reason is not known. This is not generated by a Bank rejection, but for some unforeseen reason the TraPr software could not approve it.

9
Approved and Auto-Printed. Like #3, the transaction was approved. However it Was auto-printed, so the stylist does not need to send the draft to a printer.

    TraPr:Message
    This variable returns a more understandable message then the TraPr:Result variable. But because it may be unpredictable it should only be used for display purpose with certain error situations, and not for logical branching purposes.

    TraPr:Name
    This variable should be loaded with the name of the customer, as obtained from the credit card (The Name from Track1 instruction details how to do this). It is used to print the name on the sales draft, below the signature line.

    This information should NOT be hand entered, as it must be the name exactly as it appears on the card. It should only be extracted from the Track1 information.

    On a hand-entered transaction, this variable may be left blank.

Instructions

Starting with Version 6.5 of TouchPRO, 2 new instructions were added. The Main instruction TraPr Instructions contains a submenu of instructions that are all actions to be performed with TraPr.

    Submit and Store
    This instruction (or the one below) is the one that is used for obtaining approval on a Credit Card transaction. After first loading up the appropriate variables with the information about the transaction, this instruction may be executed, to start the approval process.

    TouchPRO will first go out and look for TraPr to make sure it is up and running. If it receives an ACK from TraPr it will store the check, and ask TraPr to approve the transaction in that check.

    The workstation is now free to perform other tasks.

    The Status variable will return from this instruction with one of the following values:

0 Indicates that TraPr was found, and the transaction successfully submitted.
1 Indicates that TraPr was not found. The Check will not be stored.
2 Indicates that the instruction was run without a valid check on the workstation.

    If the Check is stored successfully, it will not be able to be retrieved until TraPr has finished with it. On the Check retrieve screen, the check will appear as red, with a small TraPr Icon next to it, until the transaction is complete. Then it will be retrievable.

    The Instruction Chain that retrieves the check should check the TraPr:Result variable to see if it needs to take action.

    When TraPr approves a transaction, it will also add the Media information to that check. Multiple TraPr Media’s may be added to one check. These media will be locked, so that they cannot be canceled like a standard Media. The only way to remove a TraPr captured media from a check, is to use the TraPr Void Media instruction below.

    Submit and Wait
    This instruction works exactly like the Submit and Store instruction, except that execution on that workstation will be suspended (with a window of notification), until the transaction has completed.

    The purpose of this would be to let the user of the station have an instant visual cue that the transaction has been processed.

    This instruction also returns with the Status variable set with the same values as the Submit and Store instruction.

    Tip Open Check
    If a gratuity needs to be added to a check that is still Open, then this instruction will allow that to happen.

    To use this instruction, first load the check that the gratuity is to be added to on the workstation. Next, load the TraPr:Gratuity variable with the amount of the tip. Then execute this instruction.

    If there is more then 1 Media on the check, then the user will be asked to choose which Media the tip is to come from. The user should then select the Credit Card that the tip should be charged to.

    After selecting a Media, execution will be suspended for a brief moment while TraPr updates its database.

    The Status variable will return from this instruction with one of the following values:

0 Indicates that TraPr was found, and the transaction successfully submitted.
1 Indicates that TraPr was not found. The transaction did not take place.
2 Indicates that the instruction was run without a valid check on the workstation.
3 The user selected a Media, which was not captured by TraPr, or left the Gratuity variable empty.
4 The user selected Cancel from the Media Selection window.

    Resolve Media
    This instruction should not be needed at this time. What it will do, is take the account number from the TraPr:Account variable, and determine which type of Credit Card it belongs to. It will then set the TraPr:Media variable to the correct number.

    Void Media
    This instruction is used to remove a Media that was added to the check by TraPr. If more then one Media is on the check, the user will be presented with a list of them, and be asked to choose which one to void. The user may only void a Media that was captured by TraPr.

    The Status variable will return from this instruction with one of the values found under the Tip Open Check instruction.

    Name From Track1 (Memo1)
    This instruction is a tool to help extract the customer Name from the credit card swipe information. It assumes that the Track1 information is first loaded into the Memo1 variable. It will parse the information, and place the customer name into the TraPr:Name variable.

    Tip Closed Check
    Like the Tip Open Check instruction, this one will allow a gratuity to be entered after a transaction has been approved. However this instruction is for use on a check that has already been closed.

    The stylist could conceivably set up a routine to allow a night manager to rapidly enter in a stack of tips in one session.

    Before running the instruction, load the TraPr:Gratuity variable with the amount of the tip. Also load the TraPr:Media variable with the sequence number (found on the sales draft) of the credit card transaction that the tip amount should be added to.

    The Status variable will return from this instruction with one of the values found under the Submit and Store instruction (except for a value of 2).

    Batch Report
    This instruction will make a request to TraPr, to print a Batch Detail report. The report will be printed to the Report Printer defined within TraPr.

    The Status variable will return from this instruction with one of the values found under the Submit and Store instruction (except for a value of 2).

    Server Report
    This instruction will make a request to TraPr, to print a Server Detail report. The report will be printed to the Report Printer defined within TraPr.

    The Status variable will return from this instruction with one of the values found under the Submit and Store instruction (except for a value of 2).

    Void All Media
    This instruction is used to remove all Media’s that were added to the check by TraPr.

    The Status variable will return from this instruction with one of the values found under the Tip Open Check instruction.

    Reprint Draft (Chk=Number1)
    This instruction is to be used to reprint a sales draft. It does not communicate with TraPr to carry this out.

    Every time a transaction is approved, a .DFT file is created that contains the Sales Draft. It is stored in the checks folder, with the number of the check. TraPr will erase this file when the batch is closed. At any time prior to the depositing of a batch, it may be reprinted by loading the check number into the Number1 variable, and executing this instruction.

    If the check number does not have a sales draft available, an error message will appear to the user.

    The actual printing is still the responsibility of the Stylist. This instruction will create a Check.txt file. A Print To instruction will still need to be carried out.

    IF TraPr Media Exists
    This instruction is not part of the TraPr Instructions group like the ones above. It is it’s own instruction.

    It is used to determine if TraPr captured any of the Media’s on the check. This may be used in a routine to void a check, to determine if a Void All Media TraPr instruction is needed.

Sales Drafts

Every time a transaction is approved, a .DFT file is created that contains the Sales Draft. It is stored in the checks folder, with the number of the check. TraPr will erase this file when the batch is closed.

In the case of Auto-Draft (an Option in TraPr), the draft will be printed when the transaction is approved (or a slip indicating a failure will be printed instead).

If Auto-Draft is not used, or if Auto-Draft failed due to an off-line printer etc, the TraPr:Result variable will return with a 3 instead of a 9, indicating that the Draft still needs to be printed.

To accommodate this, a new Printer Template item has been added.

    TraPr:Sales Draft (Print Template item)
    Placing this in a printer template will put the entire sales draft at the specified location. When followed up with a Print to instruction, it can be printed to any printer in the system.

    Revisions

11/16/2000  dhk

  1. Added DataTran information to the What is Needed section.

6/11/01  rw

  1. Consolidated existing DataTran information in new DataTran section, and added specifics on how the DataTran was internally programmed.

12/11/02  rw

  1. Added link to new document with current DataTran information.