SAP Enterprise POS EFT User Exit Technical Reference

SAP®

© 2009 SAP AGDietmar-Hopp-Allee 16D-69190 Walldorf

of 90

SAP Enterprise POSEFT User ExitTechnical Reference

Version 1.04

SAP®


Title: SAP Enterprise POS EFT User Exit Technical ReferenceVersion: 1.04Date: 1/30/2010

of 90

Copyright

© Copyright 2009 SAP AG. All rights reserved.

SAP Library document classification: PUBLIC

No part of this publication may be reproduced or transmitted in any form or for any purpose without the ex-press permission of SAP AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software compo-nents of other software vendors.

Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390,OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, andInformix are trademarks or registered trademarks of IBM Corporation in the United States and/or othercountries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks orregistered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML, and W3C are trademarks or registered trademarks of W3C®, World Wide Web Con-sortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology in-vented and implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and servicesmentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG inGermany and in several other countries all over the world. All other product and service names mentionedare the trademarks of their respective companies. Data contained in this document serves informationpurposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its af-filiated companies ("SAP Group") for informational purposes only, without representation or warranty ofany kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The onlywarranties for SAP Group products and services are those that are set forth in the express warrantystatements accompanying such products and services, if any. Nothing herein should be construed as con-stituting an additional warranty.

SAP®



of 90

Icons

Icon Meaning

Caution

Example

Note

Recommendation

Syntax

Tip

SAP®



of 90

Contents1 History ................................................................................................... 62 Introduction .......................................................................................... 73 Glossary ................................................................................................ 83.1 More Definitions ............................................................................................ 10

4 Overview and Architecture ................................................................ 124.1 Business Context .......................................................................................... 124.1.1 EFT Device Use - Sales: ............................................................................... 134.1.2 Architecture in the SAP Enterprise POS Environment ................................... 14

5 Sample Payment Flow ....................................................................... 155.1.1 Different Sample Payment Flows................................................................... 15

6 EFT User Exit API ............................................................................... 216.1 IEFTDeviceUserExit Interface/Methods ......................................................... 236.1.1 Authorize ....................................................................................................... 246.1.2 Admin ............................................................................................................ 246.1.3 Get Card Info ................................................................................................. 256.2 IEFTUserExitCallback Interface/Methods ...................................................... 256.2.1 Display - Notify .............................................................................................. 266.2.2 Get Operator Input ........................................................................................ 316.2.3 Print Receipt .................................................................................................. 326.2.4 Get Transaction Info ...................................................................................... 34

7 Use Cases ........................................................................................... 357.1.1 Paying with Unknown Card Type ................................................................... 357.1.2 Paying with Known Card Type ....................................................................... 357.1.3 Reading Card ................................................................................................ 367.1.4 Refunding with Known Card Type ................................................................. 367.1.5 EFT - Void ..................................................................................................... 367.1.6 Cancel/Abort Request ................................................................................... 377.1.7 Manual Authorization/Voice Authorization ..................................................... 377.1.8 Poweron/Failover/StartUp ............................................................................. 387.1.9 Settlement ..................................................................................................... 397.1.10 Total Snapshot .............................................................................................. 397.1.11 Reprint last EFT receipt ................................................................................. 397.1.12 EFT Logon/Logoff .......................................................................................... 397.1.13 Release Card ................................................................................................ 407.1.14 Get Software Version .................................................................................... 407.1.15 Get Terminal ID ............................................................................................. 407.1.16 Phone Card (Item Authorization) ................................................................... 41

SAP®



of 90

7.1.17 Gift Card ........................................................................................................ 437.1.18 Banking Payin/Payout ................................................................................... 447.1.19 German Debit – Pin Based vs. Signature Based ........................................... 457.1.20 Training Mode ............................................................................................... 467.1.21 Administration Functions ............................................................................... 467.1.22 Inserting EFT Receipt Text As Is in the Customer Receipt ............................ 477.1.23 EFT Status Indicator ...................................................................................... 487.1.24 Cheque Authorization .................................................................................... 497.1.25 Balance Inquiry.............................................................................................. 497.1.26 Testing Printer Availability ............................................................................. 507.1.27 Swiped/Keyed Indicator ................................................................................. 507.1.28 Printing Prepaid Card Logo specified by EFT User Exit ................................. 507.1.29 Saving Receipt Without Printing .................................................................... 527.1.30 Print Unmasked Receipts and Reprint Masked Receipts (EVoucher Receipt) 527.1.31 Allow/Disallow Manual Card Entry ................................................................. 537.1.32 Force Online/Offline Authorization (ELV @ POS) .......................................... 537.1.33 Allow / Disallow Refund, Void & Post Void ..................................................... 537.1.34 Handling Multiple EFT User Exits .................................................................. 53

8 Configuration ...................................................................................... 548.1 POS Client Configuration .............................................................................. 548.2 POS Profile Configuration ............................................................................. 558.3 EFT Device Configuration ............................................................................. 568.4 Sample Implementation - Virtual EFT Device Properties ............................... 578.4.1 Request Properties ........................................................................................ 588.4.2 Response Properties ..................................................................................... 628.4.3 Card Information Properties........................................................................... 668.5 Logging ......................................................................................................... 698.5.1 Using the SAP Proprietary Logging API......................................................... 698.5.2 SAP Proprietary Logging API ....................................................................... 69

9 Standard EFT User Exit Data Keys ................................................... 7710 Limitations .......................................................................................... 8210.1.1 Pre-Authorization and Allocated Features ..................................................... 8210.1.2 Request PIN .................................................................................................. 8210.1.3 PreAuthorization and Completion of Item Authorization ................................. 82

11 PCI Considerations ............................................................................ 8312 Development Environment Setup ..................................................... 8313 Virtual EFT Amounts .......................................................................... 84

SAP®



of 90

1 History

Version Date Status (Comments)

1.0 11/15/2008 Initial

1.04 12/12/2009 Added “Return function” for Item authori-zation

Clarifications

SAP®



of 90

2 Introduction

This document describes the interface a Java programmer has to develop to communicate with SAP EnterprisePOS on one side, and communication with an EFT device on the other side to process card payments.

EFT User Exit provides options to develop/implement specific EFT device outside the CORE code.

EFT integration can be done by SAP, SAP customer, or SAP partner.

Can be integrated with various EFT devices and/or EFT localization requirements in different countrieswithout impacting CORE code.

Fig. 1: EFT Integration

SAP®



of 90

3 GlossaryEnglish Term English

AbbreviationGermanTerm

German Ab-breviation

Definition Entry

TRX Transaction

CVM Cardholder verification me-thod – PIN or signature

CVC2 Cardholder Verification Code:This determines whether acard present transaction wasfulfilled – or whether a ma-nual card entry was done.This field is part of the mag-netic stripe information onTrack 2 (or Track 3)

German PINBased Debit

ec-cash ec-cash German PIN based onlinedebit transaction

Payment warranty for mer-chant – most expensivetransaction fee– chip or Track3 based

German Signa-ture BasedDebit

ELV German signature based of-fline debit transaction -– chipor Track 3 based -– offlinetransaction with settlement –low transaction fee

German Signa-ture BasedDebit

Online Last-schriftverfa-hren

OLV Payment type based on eccards – using a signaturebased CVM – checking on-line against a blacklist at theservice provider

MAESTRO German Debit card – the eccard is used internationally asa Maestro card -Maestro isbased on Track 2

POSREGISTER

This is the cash register –simplified Point-of-Sale(POS)

EFT Acronym for Electronic FundTransfer. This is a processwhere a device reads thecard and typically handles thefinancial payment flow. Thedevice is connected/attachedto the POS.

SAP®



of 90

English Term EnglishAbbreviation

GermanTerm

German Ab-breviation

Definition Entry

PIN Acronym for Personal Identi-fication Number. The PIN hasto be entered by the con-sumer into the EFT POS/PinPad – The Pin Pad uses thePINpad’s encryption key toencrypt the customer-enteredPIN which is then sent up tothe provider. The providercompares the calculated PINwith the entered PIN (online)- In some Smart Card Scena-rios there is an offline com-parison of the PIN in thesmart card.

PAN Primary Account Number,that is the Card Number.

STAN Systems Trace Audit Number

TLOG Transaction LOG – The LOGFile where all activities likeSALES, are stored.

The TLOG represents asummary of activities carriedout during the POS transac-tion and can be used as adata feed to other systems.”

Floorlimit Below this limit an authoriza-tion of an external party doesnot need to happen – abovethis value an authorization ofan external party is neces-sary.

Blacklist Sperrliste The cards in this list are notallowed for ELV.

Whitelist The cards in this list are al-lowed for ELV

Device Imple-mentation

DI This is the SW Part thatcommunicates to the EFTdevice

UDF User defined function in SAPEnterprise POS

SAP®



of 90

3.1 More Definitions

POS Line VoidA line void reverses the effect of a previous line in a transaction. It leaves the transaction in a stateas if the line being voided was never included.

POS Transaction VoidA transaction void is applied before a transaction is completed. It reverses the effect of all lines in atransaction to leave the state of the terminal and store in a state as if the transaction had not beenprocessed. (A Transaction number is still created)

POS Post VoidA post void is applied after a transaction is completed. The post void reverses the effect of all lines ina transaction to leave the state of the terminal and store in a state as if the transaction had not beenprocessed. . (A Transaction number is still created)

POS Auto VoidAn auto-void is used by the POS to void a line in a transaction for internal implementation reasonsand not because the user requested it.

POS ReturnA return is the action when an item is brought/sent back to the store by a customer. It can be used torefer to a line in the transaction representing the item being returned, or to the transaction as awhole.

POS RefundA refund is the return of money to a customer by the store. It is typically used to refer to a line in atransaction that represents this, but it is also a type of EFT transaction that coordinates the return offunds to the customer via an EFT provider.

AuthorizationAn authorization is an EFT transaction that is used to authorize the EFT provider to transfer fundsfrom the customer's account to the store's account and authorize the POS to accept the tender aspayment for a specified amount. For a successful authorization, this is often the first step in authoriz-ing the transfer of funds. A settlement process is often needed to complete the authorization.

EFT ProviderThe EFT provider is the system the POS uses to perform EFT transactions, such as authorizationsand reversals. This may be implemented in an EFT device at the POS terminals or by a financialhost system. The EFT provider typically communicates with a third-party system that interacts withthe appropriate banks and other agencies to provide EFT services for the retailer. This is a simplifiedview that can be implemented differently by different regions and retailers.

EFT DeviceAn EFT device is an EFT provider implemented in a device connected to each POS terminal. This istypically used in Europe, and incorporates an MSR (Magnetic Stripe Reader), a chip reader, a PINpad, a user display, and sometimes a signature capture device.

Financial HostA financial host is an EFT provider (a centralized system with which the POS communicates).

SAP®



of 90

POS and EFT DeviceWith this combination, the EFT device is communicating directly to the EFT provider. The EFTdevice is responsible for the communication to the financial host. This is the European way -typically a stand-beside terminal.

POS and Financial HostWith this combination, the POS is communicating directly (or via head office) to the EFT provider(the POS is responsible for the communication to the financial host). The POS gets authorizationfrom the financial host to apply a tender. This is the current North American way (using CEFT).

Void EFT VoidThis action removes a sale transaction. No funds are received from this transaction. Use the voidsale action to correct mistakes and for same-day returns. This action can only be performed beforethe end of day batch settlement/close.

The system allows users with the appropriate security settings to void certain transactions by select-ing either the last transaction entered, or a specific transaction number that has been processed dur-ing the current business day (also known as POST VOID).

An EFT Void happens after an EFT Transaction takes place.

Reversal

o Advice to an acquirer to discard a specific authorization request, that had been received andnot to proceed with a transaction

o Name of message/message flow between the EFT device and the financial host for reversingthe action of a previous authorization. (ISO 8583 message type)

o The electronic message that serves to cancel all or part of a previously authorized transaction

There is no reversal between POS and EFT device. The EFT device handles reversals.

EFT Transaction Cancel/Abort

If the EFT communication to the financial host has not started, the financial transaction cancels thetransaction. The POS screen goes back to the Tender menu.

(Depending on the EFT device, a CANCEL/ABORT can only happen before the EFT device hasstarted communication to the financial host.

Some EFT devices do allow a CANCEL/ABORT after communication to the financial host has started.The EFT device sends a REVERSAL to the financial host.

In this document, the command to the EFT device ABORT Transaction is used for canceling a fi-nancial transaction.

RefundThis action authorizes a transfer of funds from the merchant account to the cardholder's account.This is usually performed when a customer returns an item on a different day to the initial purchase.

Suspend/Resume

The system allows employees to suspend transactions and resume them at a later time during thesame business day.

For example, transactions are suspended when a customer realizes that they forgot their wallet, orcannot complete the transaction at the time. Once the customer returns to the register, the transactioncan be resumed and completed by appropriate tender.

SAP®



of 90

4 Overview and Architecture

4.1 Business ContextA number of localization efforts need to be made to promote worldwide acceptance of credit and debit cards withSAP Enterprise Point-of-Sale (SAP Enterprise POS).

To accept card payments a separate EFT terminal is adapted/integrated with SAP Enterprise POS. (These EFTterminals are certified with the credit card and banking organizations of the above mentioned countries. TheseEFT terminals/PIN pads/devices are mostly connected via serial or TCP/IP connection and communicate ontheir own with the financial institutions.

Each of the European countries has separate protocols from the EFT device to the financial host and has differ-ent protocols for an SAP Enterprise POS connection. Most of this EFT Connection between SAP EnterprisePOS and the EFT Device may even vary within a country.

This generic interface connects to the EFT device implementation interface, which handles the detailed countryspecific, device specific messages.

Any change in the country specific part/device implementation is possible without recompiling the complete codeof SAP Enterprise POS as long as the interface is not changed

SAP®



of 90

4.1.1 EFT Device Use - Sales:There are three ways of making a sales payment with an EFT terminal using the message flow/command.

See also, the Use Cases Section- chapter 7

The SALES using any card/Pay with unknown card type command

The POS is configured to allow a cashier to use a card button on the POS screen.

The EFT decodes the card information and authorizes it to the financial host. At the end of thetransaction the EFT device informs the POS about the card used.

See also, Section 7.1.1

Pay with known card/this card (if the tender is known before) command

The POS is configured so that a cashier uses a known tender/card option, for example, Visa orMastercard.

The EFT decodes the card information and authorizes it if the card matches the tender type.

See also Section 7.1.2

The command flow :

1. Get /Read Card MAGSTRIPE/CHIP

The POS is configured so that a cashier uses a card button on the POS screen.

The EFT reads the card and sends the card information to the POS.

2. POS Internal Card Decode Logic

The POS decodes the card information and uses internal business policies to determine the authoriza-tion type (also known as tender).

3. Pay with known card –using this card

The EFT authorizes this card to the financial host. The tender is known for the POS.

See also, Section 0

SAP®



of 90

4.1.2 Architecture in the SAP Enterprise POS Environment

Fig. 2: Overview/Relationship between Centralized EFT and EFT User Exit including EFT Devices

SAP®



of 90

5 Sample Payment Flow5.1.1 Different Sample Payment FlowsFlowchartsSome scenarios are illustrated on the next page.

Australian payment processing uses EFT for card decoding:

1. Function: Sales/Pay with unknown card2. Function: Direct Display/Display Callback3. Function: Direct Display/Display Callback4. Function: Direct Display/Display Callback– Customer to enter PIN“5. Function: Direct Display/Display Callback– Failure - use other Tender

Return of Sales/Pay with unknown card -Failure

6. Function: Printer Direct callback printing – immediate printout7. Function: Direct Display/Display callback - Check signature8. Function: Direct Input Key– Signature OK? - Enter Y/N9. Function: Function Printer callback is been used to print the article receipts….

Return of Sales/Pay with unknown card - Success

SAP®



of 90

Fig. 3: Sample Payment Flows

SAP®



of 90

Fig 4: EC Card Authorization using the POS for Card Decoding/POS determines the payment type.The ELV transaction is handled/processed by the POS.

SAP®



of 90

Fig. 5: An Offline Scenario EFT to the Financial Host – the interface is not shown.

SAP®



of 90

Fig. 6: The EFT Device Processes ELV Transaction (Authorization and Settlement of the Transaction).

SAP®



of 90

Fig. 7: Major Credit Card Processing - Online to Authorizer

SAP®



of 90

6 EFT User Exit APIThe EFT User Exit API consists mainly of 2 interfaces, IEFTDeviceUserExit and IEFTUserExitCallback,which are used to implement an EFT User Exit.

An EFT User Exit implementation must implement the IEFTDeviceUserExit interface in order for the POSclient to load the EFT User Exit implementation. The EFT User Exit implementation can get access to the POSclient functionality through the IEFTUserExitCallback interface.

POS client will call one of the following methods of the IEFTDeviceUserExit interface depending on the POSconfiguration:

Authorize

Admin

getCardInfo

For function types TenderPayment, TenderRefund, SellNonMerch, ReturnNonMerch, SellMerch, andNonFinancialEFT, the Authorize method is called.

For the EFTUserExitAdmin function type, the Admin method is called.

If the CARD_NUMBER datatype is configured to be prompted either through the PromptOverride key func-tion, or in a UDF data form as a required prompt, the getCardInfo method is called.

When any of these three methods are called, the EFT User Exit implementation first checks if it can handle therequest and if so returns true immediately, or otherwise false. No processing is done when it is invoked; rather aseparate thread within the User Exit processes the request. The POS waits until it receives a response and assuch the POS is unresponsive until the method returns.

To send a response back to the POS client once a response has been received for the request, the EFT UserExit implementation sends a data event using the Notify method of the IEFTUserExitCallback interface.

A request response flow is shown on the next page:

SAP®



of 90

Fig. 8: A Request Response Flow

A POS client sends request data as Map objects to the EFT User Exit. Similarly, the EFT User Exit implementa-tion will send response data as Map objects to the POS client. This implies that in order to get access to requestdata or set response data, a data key needs to be specified. All the standard EFT User Exit data keys are docu-mented in section Standard EFT User Exit Data Keys.

The EFT User Exit implementation can set any key in the response data and they is present in the sup-plemental data in the TLOG.

POS Client IEFTUserExitCallback

authorize / admin / getCardInfo

(return Immediately)

Notify (EFTDeviceUserExitDataEvent)

notify (EFTDeviceUserExitDataEvent)

IEFTDeviceUserExit

EFT User Exit Implementation Implements

SAP®



of 90

6.1 IEFTDeviceUserExit Interface/MethodsThe EFT User Exit interface declares methods that an EFT User Exit implementation implements to support re-quest processing.

This interface is used to implement a concrete POS driven EFT handler for a specific EFT device (DI).

Depending on the type of request, the POS Client will call one of three methods. If an authorization request istriggered then the authorize method is called. If an administration request is triggered then the admin methodis called. If a card read request is triggered then the getCardInfo method is called.

All three methods have two Map arguments, namely header data and request data. The EFT User Exit imple-mentation can obtain all information by accessing the header and request Map objects. Since the data is in theform of Map objects, in order to retrieve the data a key of type String is required.

Header data contains standard data that is not request specific, for example, store number, register number, andtransaction number. Request data contains request specific data that has different data depending on the type ofrequest. For example, IDataTypes.DT_EFT_USER_EXIT_AUTHORIZATION_TYPE are present only in autho-rization requests; IDatTypes.DT_EFT_USER_EXIT_ADMIN_FUNCTION_TYPE are present only in administra-tion requests.

Note that both these maps will have any sensitive data decrypted and provided to the implementation in cleartext (for example customer information that may be present in the header data, and card data that may be in-cluded in the request information). Care must be taken if and when this data is written to disk where legal restric-tions may prohibit the writing of sensitive (personal) data to disk.

All the request data keys are present in com.triversity.transactionware.util.IDataTypes. Whenone of the three methods are called, the EFT User Exit implementation first checks if it can process the requestand immediately returns true if it can, and false if it cannot. The EFT User Exit implementation returnsimmediately or the POS client is blocked. It produces another thread to process the request:

public interface IEFTDeviceUserExit {

public static final int EFT_USER_EXIT_INTERFACE_MAJOR_VERSION = 1;

public static final int EFT_USER_EXIT_INTERFACE_MINOR_VERSION = 0;

public boolean authorize(Map<String, Object> aHeaderInfo, Map<String, String> aRequestInfo);

public boolean admin(Map<String, Object> aHeaderInfo, Map<String, String> aRequestInfo);

public boolean getCardInfo(Map<String, Object> aHeaderInfo, Map<String, String> aRequestInfo);}

SAP®



of 90

6.1.1 Authorize

Method Name authorizeEvent class/Event None Visibility Public

Description Perform authorization processing based upon the request parameters in the supplied map aRequestInfo. Everyrequest should contain the following keys in the aRequestInfo map: IData-Types.EFT_USER_EXIT_AUTHORIZATION_TYPE; value is one of IAuthorizationTypeConstants IDa-taTypes.DT_TENDER_AMOUNT, amount being authorized.

Preconditions

Result True if we can perform the authorization request, false otherwise

Exceptions None

Parameter Name Parameter Type Description

aHeaderInfo Map<String, Ob-ject>

Generic variables associated with the transaction in process HeaderData.

aRequestInfo Map<String,String>

Data associated with the request. Entries in the map are populated from the request beingprocessed (data from the function's dataform gathered thus far), a menu's parameter field, amenu's detail settings, entries in a request's property map populated by the server (authoriza-tion related parameters), or entries populated as a result of processing the function (data-source, pre-authorized permissions, and so on).

6.1.2 Admin

Method Name adminEvent class/Event None Visibility Public

Description Performs administration processing based on the request parameters in the supplied map aRequestInfo. Everyrequest should contain at a minimum, the following key in the aRequestInfo map: IData-Types.DT_EFT_USER_EXIT_ADMIN_FUNCTION_TYPE

Preconditions

Result True if the administrative request can be performed, false otherwise

Exceptions None


aHeaderInfo Map<String, Object> Generic variables associated with the transaction in process HeaderData

aRequestInfo Map<String, String> Data associated with the request. Entries in the map are populated from the request be-ing processed (data from the function's dataform gathered thus far), a menu's parameterfield, a menu's details settings, entries in a request's property map populated by the serv-er (administration related parameters), or entries populated as a result of processing thefunction (datasource, pre-authorized permissions, and so on).



aRequestInfo Map<String, String> Data associated with the request. Entries in the map are populated from the request be-ing processed (data from the Function's dataform gathered thus far), a Menu's Parameterfield, a Menu's detail's settings, entries in a request's property map populated by theserver (administration related parameters), or entries populated as a result of processingthe Function (datasource, pre-authorized permissions, and so on.).

SAP®



of 90

6.1.3 Get Card Info

Method Name getCardInfoEvent class/Event None Visibility Public

Description Attempt to retrieve card information via an MSR, chip reader, or other. Method should not block, for example,when waiting for a card to be swiped/inserted. If the EFT device can provide card data, return (true), then fire adata event with the card data when it becomes available.

Preconditions

Result True if the device attached has the capability of providing card information

Exceptions None



aRequestInfo Map<String, String> Data associated with the request. Entries in the map are populated from the request be-ing processed (data from the function's dataform gathered thus far), a menu's parameterfield, a menu's details settings, entries in a request's property map populated by the serv-er (administration related parameters), or entries populated as a result of processing thefunction (datasource, pre-authorized permissions, and so on).



aRequestInfo Map<String, String> Data associated with the request. Entries in the map are populated from the request be-ing processed (data from the Function's dataform gathered thus far), a Menu's Parameterfield, a Menu's detail's settings, entries in a request's property map populated by theserver (administration related parameters), or entries populated as a result of processingthe Function (datasource, pre-authorized permissions, and so on.).

6.2 IEFTUserExitCallback Interface/MethodsThe EFT User Exit callback interface defines the methods an EFT User Exit implementation can invoke to gainaccess to existing POS logic. This interface is made available to the EFT User Exit implementation when theEFT User Exit implementation constructor is called by the POS client. This implies that the EFT User Exit im-plementation will need to define a constructor havingcom.triversity.transactionware.eftuserexit.IEFTUserExitCallBack as an argument. The EFTUser Exit implementation then needs to save the callback for later reference.

For example, the VirtualEFTDevice constructor is defined as below:

public VirtualEFTDevice(IEFTUserExitCallBack anEFTUserExitCallBack) {

callBack = anEFTUserExitCallBack;

}

When the EFT User Exit implementation calls the getOperatorInput or printReceipt method, the currentthread is blocked until the method returns. Since these two methods typically take a long time to return, theyshould not be called in threads that also need to do some other processing, such as reading from socket, port,for example.

SAP®



of 90

6.2.1 Display - NotifyEvents are used to update the POS display (status update events), and to signal the completion of an authoriza-tion/administrative request (data events).

Method Name NotifyEvent class/Event None Visibility Public

Description Notifies all registered listeners of a status update or a data event. Status update events are used to update the cus-tomer display, provide connection details, and so on. Data Events are used to provide card details, authorizationprocessing result, or administrative request processing results.

Preconditions None

Result None

Exceptions EFTUserExitException if there is an error with a known value in the Map


anEvent IEFTDeviceUserExitEvent Event to forward to all listeners

Method Name NoneEventclass/Event

EFTDeviceUserExitDataEvent Visibility Public

DescriptionNotifies the application that the response data is available from the device. This event can be used when an EFT UserExit device needs to deliver the response data to the application.Examples are admin, authorize, or getCardInfo response data.

This event is used with the notify() callback method as parameter.

The response data for Admin or Authorize should present result code.

The response data for cancel request should present DT_CANCELLED_PROMPT

The variable value can contain the new line characters specified as ‘@@@’

Preconditions None

Result None

Exceptions EFTUserExitException if there is an error with a known value in the Map

See also com.triversity.transactionware.util.IDataTypes for aDataMap key

com.triversity.transactionware.eftuserexit.EFTUserExitResult for result code

Arguments

ConstructorParameterName

ParameterType

Description

aDataMap Map<String,String>

Map of admin, authorize, or getCardInfo response data associated with this event to be used to

populate the current request’s property.

The key in aDataMap may be one of the following:

SAP®



of 90

Constant Use

DT_EFT_USER_EXIT_AUTH_RESULT

Indicates the result of EFT User Exit authorization request and as a requiredfield when sending authorization response data to the client.

DT_EFT_USER_EXIT_ADMIN_RESULT

Indicates the result of EFT User Exit administrative request and as a requiredfield when sending administrative response data to the client.

DT_CANCELLED_PROMPT Indicates to the application that a prompt was canceled.

DT_APPROVED_AMOUNT Supported for card types of StoredValueCard and ThirdPartyCard for Itemauthorizations.If the User Exit returns an authorization result of APPROVED, the system as-sumes the request is fully authorized for the requested amount, unless the cardtype associated with the request is one of the above. When the card type is oneof these two types, the system will check for the existence of theAPPROVED_AMOUNT property to determine the amount the request was au-thorized for (with the exception of Reload authorization types). An approvedamount of zero is treated as not set, therefore if a request was authorized withan approved amount of zero, the implementation should provide a value ofDECLINED for the authorization result, and not APPROVED.

When authorizing a TenderPayment request, if the balance remaining on thecard was less than the amount to be authorized, the authorized amount wouldbe set to the value remaining on the card, and the balance due remaining in thetransaction would be reduced by the approved amount.

DT_BALANCE_AMOUNT For card types that support balances (StoredValueCards), this is the balanceavailable on the card after the transaction has been performed.

The valid result codes value in the data map may be with one of the following:

Result Value Description

APPROVED Indicates that the EFT User Exit successfully processed or approved the re-quest

APPROVED_WITH_VERIFICATION

Indicates that the EFT User Exit successfully processed the request, but the

authorizer requested the cardholder’s identity to be verified first. This will trig-ger identity verification processing (if configured and supported for the request)at the POS. Upon completion of the verification process, the User Exit is noti-fied of the result.

DECLINED Indicates that the EFT User Exit failed to process or declined the request.

SAP®



of 90

REFERRED Indicates that the EFT User Exit has successfully processed the request butauthorizer requested to call for authorization. This will trigger the manual autho-rization process at the POS (if configured and supported for the request) If au-thorization is obtained, the User Exit is notified of the authorization number.

TIMED_OUT Indicates that the EFT User Exit has timed out while processing the re-quest.This will trigger the manual authorization process at the POS (if confi-gured and supported for the request). If authorization is obtained, the User Exitis notified of the authorization number.

CANCELED Indicates that the EFT User Exit has canceled the request

If there is any data, such as receipt data, that contains new lines, this will cause an XML transformation er-ror.new lines need to be present in the data, they should be replaced with the string “@@@”. The XMLU-til.toXML method can be used to convert new line characters to @@@. The XMLUtil class is present in thePOS client’s TEF.jar file

SAP®



of 90

Method Name NoneEventclass/Event

EFTDeviceUserExitStatusEvent Visibility Public

Description Notifies the application when a device has detected an operation status change.

This event can be used when an EFT User Exit device needs to alert the application of a device status change.Examples are a change in the EFT User Exit device connected or disconnected.

This event is used with the notify() callback method as parameter.

EFT User Exit status missing literal displays in the system frame detail window if there is no valid (see above) va-riables populated in the data map for EFT_USER_EXIT_STATUS status event.Display a translatable message on the system frame. The message to display is specified by the status code. Sta-tus code must be greater than 1000 for translatable messages. The literal file would need to be configured with thespecified status code as:

EFT_USER_EXIT_STATUS_100x=S:translatable text

where:

‘x’ is the number

‘S’ is the severity code.

Severity code:

A - Display the error until you get an EFT_USER_EXIT_OK from the device.

B - Display until another message comes in, or the cashier clears it.

C – Do not display

The translatable text may contain variables which is populated from the data map.

For example, if status code is 1001, the following should be present in the literal file:

EFT_USER_EXIT_STATUS_1001=B:Bankmesage:%bankmessage%

If a variable is used, it can be inserted in the message by enclosing the variable name in % marker. If status codeliteral was not found in the literal file, then display EFT_USER_EXIT_UNKNOWN_STATUS message like an Un-known EFT User Exit status XXXXX .

Preconditions None

Result None

Exceptions EFTUserExitException - If there is an error with a known value in the Map

See also com.triversity.transactionware.eftuserexit.IEFTUserExitConstants for status code constants

Argument:

ConstructorParameterName

ParameterType

Description

aStatus int Device category-specific status, describing the type of status change.

Constant Value Use

EFT_USER_EXIT_OK 0 Clears any EFT User Exit generated errors from thescreen

EFT_USER_EXIT_CONNECTED 1 Indicates that the EFT User Exit is connected andcan be displayed in EFT User Exit indicator statusarea

EFT_USER_EXIT_DISCONNECTED 2 Indicates that the EFT User Exit is no longer con-nected and can be displayed in EFT User Exit indi-cator status area

EFT_USER_EXIT_DETAIL_DATA 3 Displays data in Detail window

SAP®



of 90

EFT_USER_EXIT_CANCELLED 4 Indicates that the EFT User Exit was canceled

EFT_USER_EXIT_CUSTOMER_DISPLAY 103 Displays message in customer display device

EFT_USER_EXIT_STATUS 1000 Displays eftUserExitDisplayMessage messageevent in system frame detail window and the mes-sage in eftUserExitDisplayMessage is dis-played as is.

EFT_USER_EXIT_STATUS_1001

EFT_USER_EXIT_STATUS_1002

.

.

.

1001

1002

.

.

.

User defined message allows for translatable mes-sages along with variable and parameter substitutionto be displayed in system frame detail window.

When status code is EFT_USER_EXIT_STATUS, the data map needs contain variable with one of the follow-ing:

Variable Name Description

EFT_USER_EXIT_STATUS_DISPLAY_KEY_AUTO_CLEAR

Value as eftUserExitDisplayMessage_B

The display message is automaticallycleared by the POS client, either whenanother EFT_USER_EXIT_STATUSmessage comes in, or the cashier clearsit.

EFT_USER_EXIT_STATUS_DISPLAY_KEY_USER_EXIT_CLEAR

Value as eftUserExitDisplayMessage_A

The display message must be clearedby the EFT User Exit implementation bysending a status event with status codeEFT_USER_EXIT_OK

aDataMap Map<String,String>

Map of variables associated with this event is used to update the display, control which properties to retrieve fora getTransactionInfo callback, or variables to be used in document formatting in a printReceipt call-back.

SAP®



of 90

6.2.2 Get Operator Input

Method Name getOperatorInputEvent class/Event None Visibility Public

Description Callback method to allow a device to get some input from the operator based on a variety of parameters.

Calling this function will return true if we have input from the user, false if the user selected to cancel the operation.

Calling this function will block the calling thread until a response is ready.

If OPERATOR_INPUT_CHOICES list is present, a menu choice list is activated. Each list entry can contain eithersimple code (like YES, NO) or a series of a combination of a code and displayable text (like Y=YES, N=NO..). If thereis no displayable text, the code is looked up in the active literals.properties to find any possible text. If thatdoes not exist, the code itself is displayed. The code is always the value used when the function returns. If a combi-nation of a code and displayable text does not exist, this becomes a text entry prompt.

If OPERATOR_INPUT_CHOICES is not present or empty, it becomes a text entry prompt. The prompt format can bechanged based on provided values of operator input FORMAT, MINLENGTH, MAXLENGTH and DEFAULT valuecan be set as an optional default value to display.

if parameter aRequest is null, calling this function will return with a false.

To cancel an operator input, a cancel timer thread is set up that will call the getOperatorInput(null) after so manyseconds and the previous call will return false.

Preconditions None

Result The return code of the function is a boolean. If it is false, the user pressed the ‘Clear- Button ’ to escape from enter-ing the operator input. If it is true, the result is returned in the same Map<String, Object>.

Key Type Description

RESULT String Either the code selected, or the text that was entered.

Exceptions None

Also see com.triversity.transactionware.eftuserexit.IEFTUserExitConstants for parameter aRequestkey

ParameterName

Parameter Type Description

aRequestIn-fo

Map<String,Object>

Parameters to define the required operator input required.

Valid key values that can be present in the map are:


OPERATOR_INPUT_PROMPT_TEXT String Text to show in Prompt window

OPERATOR_INPUT_INFO_TEXT String Text to show in Information window

OPERATOR_INPUT_DETAIL_TEXT String Text to show in Detail window. This is a muti-line window

OPERATOR_INPUT_CHOICES List<String> List of strings of choices to be shown inmenu pushbuttons

OPERATOR_INPUT_DEFAULT String A default value to show to the user

OPERATOR_INPUT_FORMAT String Any, Digits, Numeric, Integer, Money, Alpha

SAP®



of 90

Alphanumeric, or a string with a date or timeindicator (that is, YYYYMMDD, HHMM,YYMM). Note when using a format of Money,the POS Client application returns the en-tered value as a String with no delimiters.This includes the removal of the decimal se-parator if applicable to the systems locale.

OPERATOR_INPUT_MINLENGTH String Minimum length of input. If unspecified, thereis no minimum.

OPERATOR_INPUT_MAXLENGTH String Maximum length of input. If unspecified,there is no maximum length.

OPERATOR_INPUT_ALLOW_CANCEL String T, F, or not present. If T, the user can hit theCancel pushbutton to get out of the choice,in which case the function will return with afalse.

6.2.3 Print Receipt

Method Name printReceiptEvent class/Event None Visibility Public

DescriptionPrint Receipt callback invoked by an EFT User Exit implementation. Documents configured for the current UDFbeing processed with a timing of “EFT User Exit Printer CallBack “ processed with the provided map of va-riables.

Calling this function, all documents attached to the current UDF with a timing of EFT_USER_EXIT is processed andwill return true if we have documents printed, and false if no document can be printed

Calling this function will block the calling thread until the result of the printing is known.

If a printer is required to be functional in order to process an authorization request, then this call back should beused to trigger the printing of a single line document to ensure the printer is available.

Print a receipt using variables included in aPrintInfo map. Documents from the current UDF with a timing ofEFT_USER_EXIT are used to format the variables. If a variable with EFT_USER_EXIT_FORMNAME_KEY key ispresent in the map, then the value determines which form within a document is used as the entry point into the doc-ument, if the variable is not present, then a default form name of eftUserExit is used.

The variable string value can contain new line characters specified as “@@@” and present by using the functionformattedText(%variable%) in EFT User Exit documents.

A sample EFT User Exit document could be as follows:

.testPrinterAvailability

.blank

.eftUserExitFullReceipt

.blank

~formattedText(%fullReceipt%)

SAP®



of 90

.blank

.eftUserExitPartialReceipt

.insert HeaderDoc, header

.blank

%partialReceipt%

.insert FooterDoc, footer

Preconditions None

Result True if one or more documents were printed successfully; false if printing document failed

Exceptions None

See also com.triversity.transactionware.eftuserexit.IEFTUserExitConstants for parameter aPrintInfo key

Parameter Name ParameterType

Description

aPrintInfo Map<String,String>

Map of variable name, value pairs which can be included in a document to be included in a receipt. Ex-pected keys are as follows:

_eftFormName_ = name of form to be printed (document must have this form name, if not specified, de-fault form name of eftUserExit is used)

The parameter aPrintInfo may contain one of the following keys:


EFT_USER_EXIT_FORMNAME_KEY String Key used when specifying a form name to beused when formatting a document with the prin-tReceipt callback method. If this property is in-cluded in the aPrintInfo map when performinga printReceipt callback, its value is used asthe entry point into a document. For exampletestPrinterAvailability, eftUserExit-FullReceipt, and so on.

fullReceipt String Variable containing fully formatted EFT receipt.

partialReceipt String Variable containing partially formatted EFT re-ceipt.

SAP®



of 90

6.2.4 Get Transaction InfoThis function/method is typically used for Australia/Field 48.

Method Name getTransactionInfoEvent class/Event None Visibility Public

Description Callback method to retrieve transaction details.

Retrieves a list of maps containing the requested variables for the specified line type from the current transaction.Each line in the current transaction is examined, if the line type is of the requested type, the specified variablesare included in a map returned to the EFT device.

Note: This method may take some time to return depending on how long it takes to get a response from the oper-ator. The current thread is blocked until the method returns.

The document editor could be utilized to determine the valid line type values (in the form’s table, the FORM col-umn corresponds to the line types, and the variables column lists all valid variable names for the line type.

For example, to retrieve the item number, department, and price for item lines in the current transaction, the call-back would set the aLineType to lineitem and have three entries in the returned aLineProperties list con-sisting of code, department and price.

Handling of voided lines - Only returns non-voided lines, unless the User Exit explicitly asks for voided lines by in-cluding the voidstatus variable in the list of requested line variables.

getTransactionInfo("lineitem", {"code", "description", "price"})

will get all non-voided lineitems

getTransactionInfo("lineitem", {"code", "description", "price", "voidstatus"}) will getall lineitems.

When "norolledupdata" variable provided in the list variable, the amount for item lookup but not current actual sell-ing price (after mixmatch, promotions, discounts, etc) returns. The default will get actual item price

Preconditions None

Result List of maps, a map for each line of aLineType in the current transaction. Each map will contain the requestedvariables (if present in the line) and their value.

Exceptions A EFTUserExitException may be thrown if aLineType is null or aVariables is null or empty.


aLineType String Specifies which line types to retrieve the specified properties for (that is, .lineitem, tenderline,and so on).

aLineVariables List<String> Specifies properties needed to be retrieved for specified line type (that is, Code, department,price, and so on).

SAP®



of 90

7 Use Cases7.1.1 Paying with Unknown Card TypeThe EFT decodes/determines which card was used.

With an unknown card type configuration, the card type or any card info is not known at the time the paymentfunction is triggered. EFT User Exit determines the card type.

This also implies that the tender ID is not known at the time of payment. For this configuration, the tender pay-ment function is configured without a tender ID. The EFT User Exit implementation should set the tender ID indata event once the tender payment is done.

Since no tender ID is set, POS business logic will use default tender rules using the tender specified inthe Invalid Tender configuration defined in terminal operations.

When the unknown card type menu is selected from the menu, the authorize method of the IEFTDeviceU-serExit is called. EFT_USER_EXIT_CARD_TYPE is set to be the CardType of the Invalid Tender.EFT_USER_EXIT_AUTHORIZATION_TYPE is set to Authorization-Purchase.

After the EFT User Exit implementation has authorized the request, it sends the TENDER_ID (if known) in thedata event.

7.1.2 Paying with Known Card TypeWith a known card type configuration, the card type (Tender ID) is known at the time the payment function istriggered but not card number. EFT User Exit will do a card read and obtain all the card info.

When the known card type is selected from the menu, the authorize method of the IEFTDeviceUserExit iscalled. EFT_USER_EXIT_CARD_TYPE is set to the CardType of the known tender.EFT_USER_EXIT_AUTHORIZATION_TYPE is set to Authorization-Purchase.

The EFT User Exit implementation checks if the configured tender ID matches the tender ID of the card read,and if not decline the request. For example, if Visa is selected from the menu and if a Mastercard is read, thenthe request should be declined.

In some cases, this check may not be required and the EFT User Exit implementation can send a different ten-der ID than was requested by configuration. For example, if user selected ecCash then the EFT User Exit im-plementation can change the tender ID to ELV.

After the EFT User Exit implementation has authorized the request, it may send all the card info in the dataevent (if required).

SAP®



of 90

7.1.3 Reading CardOne of the ways to trigger a tender payment function is using the read card configuration. This configuration isused when the EFT User Exit reads the card and the POS DEP rules need to be used to trigger a tender pay-ment based on the card number.

To trigger a card read, POS is configured with a Prompt Override key function on the menu. The Prompt Over-ride key function is set to use a card number prompt having data type CARD_NUMBER. When the menu is se-lected, the getCardInfo method of the IEFTDeviceUserExit interface are called to trigger a card readthrough the EFT User Exit.The EFT User Exit implementation reads the card from the device and sends a dataevent with all the card properties set. The CARD_NUMBER property has to be sent in the data event.

Some other card properties are CARD_NUMBER, EXPIRY_DATE, TRACK_1, for example. See Section 9 for allthe card related properties.

In most cases, the track data of the card read is sent by the EFT device. The EFT User Exit implementationmust parse the track data and set the CARD_NUMBER property in the data event. The card number set is used bythe POS Client’s DEP rules processor to identify the UDF to trigger.

For cases where the card bin range cannot be checked but the card type is known, theEFT_USER_EXIT_DEP_KEY property can be set to be the card type. For example, it can be set to ecCard andthen in the DEP rule configuration, the Data Field can be set to DEP Key. A validation rule would then have to beset up that validates the DEP key to be ECCard.The _datasource_ property also needs to be set to EFTUserEx-it.

To cancel the card read, see the use case for cancel/abort request.

7.1.4 Refunding with Known Card TypeA tender refund may be triggered automatically or manually depending on whether a return with receipt or returnwithout receipt is being done.

With a known card type configuration, the card type (tender ID) is known at the time the refund function is trig-gered but not card number. EFT User Exit will do the card read and obtain all the card info.

When the known card type is selected from the menu, the authorize method of the IEFTDeviceUserExit is called.EFT_USER_EXIT_CARD_TYPE is set to be the CardType of the known tender.EFT_USER_EXIT_AUTHORIZATION_TYPE is set to Authorization-Refund.

After the EFT User Exit implementation has authorized the request, it may send all the card info in the dataevent (if required).

7.1.5 EFT - VoidWhen performing a void (line void or post void) of a request that supports voiding, the User Exit authorize me-thod is invoked. This method is invoked with a standard set of authorization keys (authorization type, requestedamount), plus additional information in the request data map to further qualify the void request. These additionalkey value pairs include REQUEST_MODIFIER with a value of VOID to indicate the request is a void request. Ad-ditionally, a number key prefixed with ORIGINAL_ with values being set to the value of the key for the originalrequest, for example, ORIGINAL_AUTHORIZATION_NUMBER are included with the value of the authorizationnumber of the original request being voided.

SAP®



of 90

7.1.6 Cancel/Abort RequestA request can be canceled either by the operator by pressing the ESC/Clear key or by the EFT User Exit imple-mentation. This command is used by the cashier to stop a financial transaction flow.

When the operator cancels the request, the admin method is called withEFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to one of the following, CANCEL_GETCARDINFO,CANCEL_ADMIN, or CANCEL_AUTHORIZE.

The cancel request is in a different thread than the auth/admin/cardread thread. The cancel request threadchecks if canceling is allowed. If it is, the auth/admin/cardread thread is notified to stop processing. The Cancelthread completes after notifying the auth/admin/cardread thread, and the auth/admin/cardread thread should al-so handle the cancel request appropriately as explained below. It then returns.

If cancel is not allowed/possible, then a message is displayed saying that cancel is not allowed.

If card read is in progress, then admin method is called with EFT_USER_EXIT_ADMIN_FUNCTION_TYPE set toCANCEL_GETCARDINFO. The EFT User Exit implementation disables the card reader on receiving the cancel forgetCardInfo and stops the card read thread if there was one running. There is no need to send any responseto the POS for the cancel request. If there is a card read thread running then the card read thread stops readingand it should return without sending any response (data event) to The POS client.

If an authorize request is in progress, CANCEL_AUTHORIZE is called. When the EFT User Exit implementationreceives the cancel authorization, it checks to see if the current status can be canceled and if it is allowed to stopit should stop the authorize thread if there was one running. There is no need to send any response to the POSfor the cancel request. If there is an authorize thread running, the authorize thread should stop processing andsend a data event with a CANCELED result code.

The admin method is handled the same as an authorization, but in most cases there is no need to handle acancel request and the cancel request thread should just send a display message saying that cancel is not al-lowed.

7.1.7 Manual Authorization/Voice AuthorizationIf manual authorization is processed within the User Exit, no additional processing is performed at the POS. TheUser Exit sets the EFT_USER_EXIT_AUTH_RESULT to APPROVED along with the other relevant authorizationproperties, for example the authorization number that was not a result of the online authorization process. If youwant to use the manual authorization business logic of the POS, the User Exit sets theEFT_USER_EXIT_AUTH_RESULT key to a value of TIMED_OUT or REFERRED (depending on the circums-tances), which triggers manual authorization processing on the POS client and server.

If manual authorization is successful, either via floor limits or a call, the authorization method is invoked one ad-ditional time to the User Exit to allow the User Exit to make note of the approved manual authorization. The UserExit checks for a key of MANUAL_AUTH and a value of true to determine if manual authorization was successfullyacquired. Additionally, keys of EFT_USER_EXIT_MANUAL_AUTH_SOURCE and AUTHORIZATION_NUMBER areincluded in the request data map.

SAP®



of 90

7.1.8 Poweron/Failover/StartUpThis function is called after POWERON reset of the POS device if the POS restarts in the middle of a financialtransaction. The EFT device needs to do whatever is necessary to complete the transaction.

To do this, the EFT device needs to check whether a message was already sent to the financial Host. An auto-matic void could be sent out – this is dependant on the financial host and the terminal what needs to be done.

The POS Client can be configured to automatically send a POWERON request to the EFT User Exit implemen-tation. This can be configured in Terminal Operations Menu Option, under the EFT User Exit options, set Ad-min UDF To Trigger on PowerOn to be a UDF of function of type EFTUserExitAdmin and having the adminfunction type as POWERON.

When the POS client starts up after it has obtained the configuration and performed a client state sync, it willtrigger the power on request. It will call the admin method with the EFT_USER_EXIT_ADMIN_FUNCTION_TYPEset to POWERON.

If for some reason the POS client was abnormally shut down, then the POWERON request sent by the POSclient includes an indication that an authorization was in progress before the shutdown. If there was an authori-zation in progress then HAS_WAITING_AUTH status is present in the request map and is set to true. Otherwisethis property will not be present. The EFT User Exit implementation should check its own state and decide if theauthorization should be triggered. It should send a TRIGGER_WAITING_AUTH set to true if it wants to trigger thepending authorization after the power on request is done. Otherwise it should not sendTRIGGER_WAITING_AUTH or set it to false.

If TRIGGER_WAITING_AUTH is set to true, the POS will trigger the pending authorization and will set theEFT_USER_EXIT_ADMIN_TRIGGER_SOURCE in the request map of the triggered authorization request to bePOS.POWERON. The EFT User Exit implementation must always check this property to know if the authoriza-tion is a result of the power on.

The EFT User Exit implementation saves the last authorization response (and receipts, if required) in its presentstate and saves to a file only if the EFT device does not have a capability to get the last authorization details.

Typically there is only one authorization being processed at a time and so the EFT User Exit implementation cansend the last authorization as a response to the pending authorization. If it is necessary to verify the authoriza-tion saved in POS with that saved in the EFT device, additional checks can be made. For example, the transac-tion number and sequence number could be used to find a match. The POS can be configured to generate aunique sequence number for each authorization by setting the User Exit Sequence Number Algorithm in theUDF configuration in the Configurator. If set, the sequence number is present in theEFT_USER_EXIT_SEQUENCE_NUMBER property.

If the POS client fails over to another server, it will trigger the failover request. It will call the admin method withthe EFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to FAILOVER.If there was an authorization in progress be-fore the failover, that transaction is abandoned and the EFT User Exit implementation should reset the device toa usable state.

SAP®



of 90

7.1.9 SettlementA POS client can be configured to automatically send a SETTLEMENT request to the EFT User Exit implemen-tation on a store close (end of day). In Terminal Operations, under the EFT User Exit options, Set Admin UDFTo Trigger on Store Close to be a UDF of function of type EFTUserExitAdmin and having the admin functiontype SETTLEMENT. It can also be configured to manually trigger a SETTLEMENT from the menu.

When the store close is done either from POS or POS Manager, the POS client gets the settlement notificationfrom the next poll request and then calls the admin method with EFT_USER_EXIT_ADMIN_FUNCTION_TYPEset to SETTLEMENT in the request map.

Since the settlement transaction is sent after store close, the settlement transaction is not accounted for in theEOD audit (the XML message sent out after store close that lists out the transaction count for each terminal forthe business date). The settlement transaction has the same business date as the store close business date andis marked Late.

When a settlement is triggered automatically after store close, you can choose to not print a receipt, but to saveit in the ElectronicJournal.

This can be achieved by configuring the settlement UDF with the EFTUserExitNoPrintReceipt documentwith Destination set to None, Timing set to EFT User Exit Print receipt callback, and archive and countchecked. (see EFT_USER_EXIT_SETTLEMENT_EOD in the default config). If the EFTUserExitNoPrintReceiptdocument is used to save the partial receipt the form name is eftUserExitPartialNoPrintReceipt andreceipt text variable is partialNoPrintReceipt.

7.1.10 Total SnapshotTotal Snapshot (or Reconciliation) is configured as an EFT User Exit administration function with the admin func-tion type set to TOTAL_SNAPSHOT in the request map.

POS client calls the admin method with the EFT_USER_EXIT_ADMIN_FUNCTION_TYPE set toTOTAL_SNAPSHOT in the request map.

7.1.11 Reprint last EFT receiptReprint last EFT receipt is configured as an EFT User Exit administration function with the admin function typeset to REPRINT_LAST_RECEIPT in the request map.

POS client calls the admin method with the EFT_USER_EXIT_ADMIN_FUNCTION_TYPE set toREPRINT_LAST_RECEIPT in the request map.

7.1.12 EFT Logon/LogoffA POS client can be configured to automatically send a LOGON/LOGOFF request to the EFT User Exit imple-mentation. In Terminal Operations, under the EFT User Exit options, set Admin UDF To Trigger on CashierLogon”/ “Admin UDF To Trigger on Cashier Logoff” to be a UDF of function of type EFTUserExitAdminand having the admin function type as LOGON/LOGOFF.

After the cashier logs on to the POS, the EFT Logon request is sent to the EFT User Exit implementation. Theadmin method is called with the EFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to LOGON.

Similarly, after the cashier logs off from the POS, the EFT Logoff request is sent to the EFT User Exit implemen-tation. The admin method is called with the EFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to LOGOFF.

If the EFT User Exit implementation does not send a data event to respond to the EFT logon / log off requestthen the cashier logon/logoff will also fail.

In the TLOG, the cashier logon/logoff and EFT logon/logoff are in the same transaction.

SAP®



of 90

7.1.13 Release CardTo send a Release Card message to the EFT device, an EFT User Exit administration UDF should be confi-gured with the administration function type set to Release Card and a menu configured to trigger the ReleaseCard UDF.

When the Release Card UDF is triggered from the menu, the POS client calls the admin method with theEFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to RELEASE_CARD.

7.1.14 Get Software VersionTo send a Get Software Version message to the EFT device, an EFT User Exit administration UDF is confi-gured with the administration function type Get Software Version and a menu configured to trigger the Get Soft-ware Version UDF.

When the Get Software Version UDF is triggered from the menu, the POS Client calls the admin method with theEFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to GET_SOFTWARE_VERSION.

7.1.15 Get Terminal IDTo send a Get Terminal ID message to the EFT device, an EFT User Exit administration UDF is configured withthe administration function type Get Terminal ID and a menu configured to trigger the Get Terminal ID UDF.

When the Get Terminal ID UDF is triggered from the menu, the POS client calls the admin method with theEFT_USER_EXIT_ADMIN_FUNCTION_TYPE set to GET_TERMINAL_ID.

SAP®



of 90

7.1.16 Phone Card (Item Authorization)When performing a SellMerch function, Item Authorization can take place immediately or at the end of the trans-action (deferred). ReturnMerch functions only support immediate authorization.

Item authorization is similar to gift card authorization with respect to the authorization type. Both activation andreload authorizations are supported by the selling of an item, and CashOut and Authorization-Refund are sup-ported when returning an item. Unlike gift card authorization where the authorization type is specified in the non-merchandise function configuration, item authorization is triggered by item attributes within an item maintenanceimport message. The relevant item attributes as extracted from a sample ItemMaintenance import messageare:

<AttributeList><Attribute Action="AddUpdate">

<AttributeID>ItemCardType</AttributeID><AttributeValue>ThirdPartyCard</AttributeValue>

</Attribute><Attribute Action="AddUpdate">

<AttributeID>ItemProductCode</AttributeID><AttributeValue>ATT</AttributeValue>


<AttributeID>ItemAuthAction</AttributeID><AttributeValue>ACTIVATE</AttributeValue>


<AttributeID>AllowVoid</AttributeID><AttributeValue>false</AttributeValue>

</Attribute><AttributeList>Supported values for ItemCardType are ThirdPartyCard and StoredValueCard. Item attribute ItemPro-ductCode is an optional attribute and if present is included in the authorize method’s request map under the keyEFT_USER_EXIT_CARD_TYPE_ID. Supported values for item attribute ItemAuthAction are ACTIVATE andRELOAD. The AllowVoid attribute is used to control whether or not the item (once successfully authorized)can be voided, by default items can be voided and therefore this attribute should be included with an Attribu-teValue of false if voiding should be disallowed.

New with 3.1 SP4:

This authorization was originally only supported as part of the processing of a sales item, and not for an item re-turn request. SAP Enterprise POS has been enhanced to support item authorization when returning items thatwere authorized when sold. Supported item return authorization types are Cashout and Authorization-Refund. For a sales transaction, the current valid authorization types are ACTIVATE and RELOAD. It is ex-pected that a Cashout is the return authorization type for items that are activated and potentially for those thatare configured for Reload. If this is not appropriate, the Authorization-Refund can be utilized.

SAP®



of 90

Item Master Data:

As described above, the attribute value can be either ACTIVATE or RELOAD. A new well-known attribute hasbeen added to determine the return item authorization action code:

<Attribute Action="AddUpdate"

<AttributeID>ReturnItemAuthAction</AttributeID>

<AttributeValue>CASHOUT</AttributeValue>

</Attribute>

Valid values are Cashout or Authorization-Refund. Items that are authorized when sold must have a cor-responding ReturnItemAuthAction property, or the item cannot be returned.

Return Without a Receipt

The processing of item returns without a receipt is exactly the same as processing item sell requests. A ReturnMerch request is sent to the server for processing. If the function is configured for authorization

(via the Authorization Type setting), the function initiates the authorization process in two scenarios:o If specified by Item Attributes and the item has a ReturnItemAuthAction property, the value of

the property is the authorization type (if either of the two valid types).o If the UDF is configured with an authorization type of Cashout or Authorization-Refund,

authorization is performed.

The User Exit implementation can provide an APPROVED_AMOUNT property in the data sent back tothe client after processing a request. If this property is included and is not zero, then this is the price ofthe returned item (for example, an item may have been originally activated for 100.00, but the cashoutvalue may be 40.00. In this scenario, 40.00 would be the amount returned to the customer.

Quantity item returns configured for authorization are allowed.

Return with a Receipt

When you perform a return with a receipt, the request sent to the server for processing is either a ReturnAll or aReturnLines function type (not a ReturnMerch function). To support return item authorization, the ability to asso-ciate a ReturnMerch function with these request types is required. This is achieved by supporting a well knowndetail type AuthorizedItemReturnUDF. The value of this detail type is set to the ReturnMerch UDF ID to triggerwhen an item is returned that was originally authorized. To process the actual authorization request, UDF menuoptions ReturnAll or ReturnLines that support item authorization require a detailed value specifying the Return-Merch UDF to launch.

The following screen shot shows the detailed setting associated with the RecallAll_ItemsforReturn UDF. Withthis setting, the ITEM_RETURN function is processed (to enable authorization) for any line that was originallyauthorized and is configured to be authorized when returned).

SAP®



of 90

Fig. 9: The Detailed Setting Associated with the RecallAll_ItemsforReturn UDF

The general processing flow for an item return via the Return with Receipt option is: A previous transaction is recalled for return purposes Select lines to be returned. A request is sent to the server for processing. This request includes the Au-

thorizedItemReturnUDF key and value if one is configured with the menu option selected by a detailproperty.

If the lines selected for return were authorized, the AuthorizedItemReturnUDF property is present in therequest data, and an authorization type is specified (by item attributes or configuration), the function asspecified by the AuthorizedItemReturnUDF value is triggered back to the client for processing.

At this point, processing is exactly the same as the Return without Receipt scenario described above.

Notes: Return item authorization is not supported if the line was not originally authorized If an item was authorized when it was sold, it must be configured for authorization when returning, or the

item return is not allowed.

7.1.17 Gift CardGift card authorizations are similar to tender authorizations, but in addition to the authorization types of Authori-zation-Purchase and Authorization-Refund, valid values also include Activate, Reload, Cashout, and Bal-ance_Inquiry. Cashout responses must include the DT_APPROVED_AMOUNT data type (key value ofAPPROVED_AMOUNT) for the POS to determine the amount owing to the customer.

If the authorization request is for a gift card, the system looks at the authorized amount but may treat zero as NotSet. If a gift card has a value of zero, the request should be DECLINED and not APPROVED. If the result is setas DECLINED, it functions correctly.

SAP®



of 90

For gift cards, if the balance remaining on the card is less than the amount to be authorized, the authorizedamount is set to the remaining balance. The system approves the amount remaining on the card, and therewould still be an amount owing for the transaction.

7.1.18 Banking Payin/PayoutBanking PAYIN and PAYOUT functions are configured as tender exchange functions.

It is better to use a new transaction for all banking related functions. This is so that the menus, documents, andother transaction level rules can be configured for banking functions. Another benefit is that the EFT User Exitcan identify if the request is a banking related request or not by checking the udtid property present in theheader map.

In the default configuration, the following functions are configured:

1. Payin Cheque

This is a tender exchange function that deposits a cheque to a bank account.

The from tender is a cheque and the to tender is Debit.

In the default configuration, the cheque payment function does not prompt for cheque information but thedebit refund function does. This is mainly to avoid sending two requests to the EFT User Exit.

In a real implementation, the configuration would depend on how a cheque is authorizedIf the cheque authoriza-tion and deposit bank function are done at the same time, the above configuration could be used. But if chequeauthorization is done by a different provider, the exchange cheque payment function would be configured toprompt for cheque information and sent to the provider (either through EFT User Exit or through EFT Manag-er/Transnet).

In the default configuration, when the Payin Cheque is selected, then theEFT_USER_EXIT_AUTHORIZATION_TYPE is set to Authorization-Refund and EFT_USER_EXIT_CARD_TYPE isset to DebitCard. The UDF_ID property could be used to check what type of banking function is being per-formed.

2. Payout Cash

This is a tender exchange function that withdraws cash from a bank account.

The from tender is Debit and the to tender is Cash (in the primary currency).

In the default configuration, when Payout Cash is selected, the EFT_USER_EXIT_AUTHORIZATION_TYPE isset to Authorization-Purchase and the EFT_USER_EXIT_CARD_TYPE is set to DebitCard. The UDF_ID propertycould be used to check what type of banking function is being performed.

3. Account Balance Inquiry

This is a non-financial balance inquiry EFT function which displays and prints the balance of a bank account.

In the default configuration, when the A/C Balance Inquiry is selected, theEFT_USER_EXIT_AUTHORIZATION_TYPE is set to Balance_Inquiry and EFT_USER_EXIT_CARD_TYPE is setto DebitCard. The UDF_ID property could also be used to check what type of banking function is being per-formed.

SAP®



of 90

7.1.19 German Debit – Pin Based vs. Signature BasedEc Card Processing and Different Scenarios

The German ec Card can be used with different Tenders/payment types.

As ec Cash with PIN:

Typically an online authorization

Most expensive transaction for the merchant

Payment warranty for the merchant

As ELV with signature

Typically an offline authorization

Cheapest transaction for the merchant

Highest risk

As OLV with signature

Typically a check against ONLINE blacklist at the service provider

Moderate transaction fee

The merchant decides which payment types to accept based on transaction costs and risk.

Some Business Intelligence (BI) has a preference for using an ELV transaction as opposed to an ec transaction.In this way the merchant reduces costs and risk. Another way of doing this is by using a blacklist for ELV and awhite list for ELV.An ec Card, which is in the blacklist for ELV, is processed as an ec Cash transaction. An ecCard, which is in the white list for ELV, is processed as an ELV Transaction. The black/white list is maintainedwith the existing validation maintenance data maintenance import message, the creation of this import file is theresponsibility of an external application.

Another example of criteria for forcing an ELV transaction is the location of the store compared to the areawhere the card is issued. If it is a local card and the customer has been in that store a number of times, then anELV transaction is triggered.

Processing the ELV transaction

Two scenarios are possible, both types are implemented:

a) Processing at an EFT device

The EFT device is responsible for uploading the ELV transaction to the payment provider.

b) Processing within the POSThe POS is responsible for uploading the ELV transaction to the payment provider and the processing ofthe ELV. This is typically done by populating the TLOG and based on the TLOG Information third-partysoftware handles the communication to the payment provider.

Example for ec Card Processing in Germany - Card Decoding using a Black/Whitelist

If blacklist checking is enabled, the account number is checked against the blacklist. If the number is listed, thePOS choices are to reject the card or send the authorization to EFT device as ec Cash. If the account is not inthe blacklist, the choices are to check the account number against the white list, or determine authorization type

SAP®



of 90

by comparing the total amount to the floor limits defined in the Configurator. The blacklist contains the banknumber, the account number, and the Card following/sequence number.

This Scenario is covered by:

Existing functionality provided by Data Entry Processing/Validation rules. WhiteList and BlackList validation isprovided via Positive DB checks, and floor limit checks is provided via Secondary Data Type in the Linked Ruleconfiguration setting of the Validation Rules component.

The Secondary Data Type allows the specification of a data type. Based on the specified data type, the valida-tion field is retrieved from the property map in the current UDF data. If it is not present, the validation returnsfailed as FAILED_SECONDARY_DATATYPE. The default selection is Same, which the current prompt datatype uses for the validation.

When the floor limit amount data type is provided in the Secondary Data Type setting, the total amount is usedto validate against the validation rules.

Positive DB validation provided at prompt level via ValidationMaintenance.xml data maintenance importfile.

The ItemMaintenance import message for the blacklist and whitelist is:

<DB name="BLACKLIST" type="Single" sign="Positive"><Single action="Add">4001000000000001</Single><Single action="Add">4001000000000002</Single>

</DB><DB name="WHITELIST" type="Single" sign="Positive">

<Single action="Add">4001000000000003</Single><Single action="Add">4000000000000005</Single>

</DB>

With this sample, the Positive DB Name configuration setting in the ELV WhiteList validation rule is set toWHITELIST to check if the account number is listed in WHITELIST.

7.1.20 Training ModeWhen the POS is in training mode, a training mode flag is sent in the header data. The training key can be usedto identify if the POS is in training mode.This flag must be checked by the EFT device implementation and theEFT Device implementation has to make sure that no Authorization has been sent to the financial Host

See Also: Virtual EFT Sample Implementation code for more details.

7.1.21 Administration FunctionsIn addition to the well known administration functions that have already been defined, the POS can be confi-gured to add any number of administration functions. In the Configurator, new EFT User Exit administration func-tions can be created with a custom admin function type. The custom admin function type that is defined is thevalue that gets sent in EFT_USER_EXIT_ADMIN_FUNCTION_TYPE key in the request map.

Examples of Administration Functions: Initialization, Diagnosis, and Download of Keys.

SAP®



of 90

7.1.22 Inserting EFT Receipt Text As Is in the Customer ReceiptIf there is a requirement to insert EFT receipt text obtained from the financial host into the customer receipt, thenthe IDataTypes.DT_RECEIPT_MESSAGE property can be set to contain the receipt text. The customer receiptdocument needs to check for the receiptLine variable that contains the receipt txt.

A sample configuration present in the customer receipt document in the default configuration:

.tenderregular~doublehigh~%description%|%action%|%tender%^ :2^.insert rounding.insert exchangeline.insert cardnumber.insert cardexpiry.insert swipedorkeyed.insert eftauth.insert eftsequence.insert eftplannumber.insert receiptline.insert eftsignature

.receiptline,~length(%RECEIPT_MESSAGE%)>0,onfail=noreceiptline~formattedText(%RECEIPT_MESSAGE%).noreceiptline

If new lines need to be inserted, the “@@@” characters must be used to separate each line.

The toXML method present in VirtualEFTDeviceCommon should be called on the data map of the data eventto convert the receipt text to be XML compliant.

Refer to Virtual EFT Sample Implementation Code for more details of the methods: sendAuthorizeResponseand sendAdminResponse.

SAP®



of 90

7.1.23 EFT Status IndicatorAn EFT Status frame can be set up on the POS Client UI to display the EFT connection status.

By default, layout.properties contains the following configuration regarding the position and formatting ofthe EFT status frame. This can be modified to suit clients’ requirements.

eftuserexit.form=eftuserexit # this makes it look in statusfor EFT User Exit device

eftuserexit.frame=0.13875,0.9716666666666667,0.13375,0.03#.540,.187,.065,.028

eftuserexit.backgroundcolor=0xCCCCCC

eftuserexit.hilightbackgroundcolor=0x000000

eftuserexit.hilighttext.color=0x00000

eftuserexit.text.color=0x000000

eftuserexit.text.font=Default

eftuserexit.text.height=0.6

eftuserexit.text.style=bold

eftuserexit.text.horizontal=right

To send a connected EFT status notification, the following status event should be sent:

new EFTDeviceUserExitStatusEvent (IEFTUserExitCons-tants.EFT_USER_EXIT_CONNECTED, null);

To send a disconnected EFT status notification, the following status event should be sent:

new EFTDeviceUserExitStatusEvent (IEFTUserExitCons-tants.EFT_USER_EXIT_DISCONNECTED, null);

(Refer to displayConnectedStatus method in VirtualEFTDeviceCommon class for an example)

SAP®



of 90

The UILayout Document in the Configurator should be modified to configure the text to display these statusevents. By default, EFT OFF is displayed on a disconnected status event, and EFT ON is displayed on a con-nected status event.

UI Layout configuration:

.eftuserexit,%status%=true,onfail=eftcleanconnect

EFT ON

.eftcleanconnect,%status%=false,onfail=eftreconnect

EFT OFF

.eftreconnect

%status%

7.1.24 Cheque AuthorizationFor cheque authorization, the authorize method is called with the EFT_USER_EXIT_CARD_TYPE set to Che-que.

In addition, the following cheque properties are also set:

TRANSIT_NUMBER

CHEQUE_NUMBER

BANK_ACCOUNT_NUMBER

7.1.25 Balance InquiryWhen a balance inquiry function is triggered, the authorize method is called with the

EFT_USER_EXIT_AUTHORIZATION_TYPE set to Balance_Inquiry.

The EFT_USER_EXIT_CARD_TYPE can be checked to find the type of card the balance inquiry is being per-formed on. For example, DebitCard, StoredValueCard, and PrivateLabelCard.

SAP®



of 90

7.1.26 Testing Printer AvailabilityTo check if the printer is available a blank line can be printed. This has been used for some debit systemsaround the world to activate an EFT authorization only if a printer is available - in other words a receipt can beprinted.

Printing a blank line:

Map<String, String> printInfo = new HashMap<String, String>();

printInfo.put(IEFTUserExitConstants.EFT_USER_EXIT_FORMNAME_KEY,"testPrinterAvailability");

callback.printReceipt(printInfo);

(Refer to Virtual EFT Sample Implementation code for more details: testForPrinterAvailability method in Virtua-lEFTDeviceCommon.)

A document EFTUserExitCheckPrinter should be configured as shown above:

.testPrinterAvailability

.blank

Also, No Paper Cut check box should be checked and the archive check box should be unchecked.This docu-ment should be attached to every UDF that checks for printer availability.

7.1.27 Swiped/Keyed IndicatorThe EFT User Exit implementation has control over the input mode, that is the swiped or keyed indicator.

The EFT_USER_EXIT_CARD_SOURCE can be set to Swiped or Keyed. This value is stored in the EntryMethodfield in the TLOG.The EFT_USER_EXIT_CARD_SOURCE should be set when the card is read and should there-fore be sent in the GetCardInfo response.

In the authorize method, if the card information is already present, the EFT_USER_EXIT_CARD_SOURCEshould not be set since the card information may have been obtained from EFT User Exit or some other devicelike the keyboard or MSR. If the card information is not present, EFT_USER_EXIT_CARD_SOURCE should be set.

7.1.28 Printing Prepaid Card Logo specified by EFT User ExitThe EFT User Exit implementation can print the logo of the prepaid card company when performing a prepaidfunction.

To do this, the EFT User Exit implementation sets a property identifying the logo file name in the document con-figuration to display the graphic using the property name as the file name. One way to do this is to set the logofile name to use the EFT_USER_EXIT_CARD_TYPE_ID property. Since the EFT_USER_EXIT_CARD_TYPE_IDis used to uniquely identify the different types of phone cards, this property can be used to specify the logo filename.

SAP®



of 90

For example, if EFT_USER_EXIT_CARD_TYPE_ID is set to ATT, the logo file name would be ATT.jpg (or anyother extension as specified in the document configuration). The EFT User Exit implementation can also use itsown property and does not have to use the EFT_USER_EXIT_CARD_TYPE_ID property.

In the code, modify the print receipt callback to set the EFT_USER_EXIT_CARD_TYPE_ID:


printInfo.put(aReceiptPropertyName, aReceiptTxt);

printInfo.put(IEFTUserExitConstants.EFT_USER_EXIT_FORMNAME_KEY,aFormName);

printInfo.put("EFT_USER_EXIT_CARD_TYPE_ID", getRequest-Map().get("EFT_USER_EXIT_CARD_TYPE_ID"));

getCallBack().printReceipt(printInfo);

Alternatively, a generic way is to add all request map (and header map) properties to the print receipt callback asshown below (EFT_USER_EXIT_CARD_TYPE_ID is present in the request map):


printInfo.put(aReceiptPropertyName, aReceiptTxt);

printInfo.put(IEFTUserExitConstants.EFT_USER_EXIT_FORMNAME_KEY,aFormName);

printInfo.putAll(getHeaderMap());

printInfo.putAll(getRequestMap());

getCallBack().printReceipt(printInfo);

The next step is that the voucher document configuration needs to be modified to include the logo.

SAP®



of 90

If the EFTUserExitEVoucherReceipt document is being used to print the EVoucher receipt and if eftUse-rExitPartialVoucherReceipt form name is being used, the following could be used to print the logo:

eftUserExitPartialVoucherReceipt

|~graphic(ReceiptLogo.jpg,.75)

.insert HeaderDoc,printheader

.blank

|~graphic(%EFT_USER_EXIT_CARD_TYPE_ID%.jpg,.75)

.blank

~formattedText(%partialVoucherReceipt %)

.blank

.insert FooterDoc, footer

Finally, the logos should be placed in the following folders:

te\custom\client\config\images (logos used to print on receipt)

te\custom\ear\pos-manager\images (so logo can be viewed in POS Manager EJ)

7.1.29 Saving Receipt Without PrintingSee section 7.1.30 for information on how masked receipts are saved without printing.

7.1.30 Print Unmasked Receipts and Reprint Masked Receipts (EVoucher Receipt)EVouchers immediately print an unmasked receipt containing the serial number and an unmasked PIN. ThisEVoucher can be considered as money and therefore only the receipt printed immediately should be unmasked.The EVoucher receipt should also be saved in the EJ but the serial number and the PIN should be masked.

This can be achieved as follows:

In the default configuration, two documents - EFTUserExitEVoucherReceipt and EFTUserExitNoPrin-tReceipt are attached to the ITEM_SELL UDF. EFTUserExitEVoucherReceipt prints the receipt un-masked but in the ITEM_SELL UDF, this document has been configured not to archive. So the unmasked re-ceipt is printed on receipt immediately but is not saved in the EJ. The EFTUserExitNoPrintReceipt document hasbeen configured not to print a receipt but to just archive it.

Note: Appropriate form name and receipt text variable should be used.

For EFTUserExitEVoucherReceipt, the partial receipt form name is eftUserExitPartialVoucherRe-ceipt and receipt variable name is partialVoucherReceipt.

SAP®



of 90

For EFTUserExitNoPrintReceipt, the partial receipt name is eftUserExitPartialNoPrintReceiptand receipt variable name is partialNoPrintReceipt.

7.1.31 Allow/Disallow Manual Card EntryManual card entry can be enabled or disabled by configuring the Prompt and DataEntryProcessing (DEP) rulesin the Configurator. If manual card entry is not allowed, the keyboard source device in the card number prompt isnot checked.

If using the Card@POS configuration, and if the card number prompt can accept data from keyboard as well asEFT User exit, the DEP rules need to be configured to check only the card types that can be manually entered.

Also, a DEP rule can be set up that checks for the card type that cannot be manually entered. It triggers aTriggerDocInputError document, similar to the way the InvalidKeyInPayment rule is configured.

7.1.32 Force Online/Offline Authorization (ELV @ POS)The auto-authorize floor limit can be used to identify if an authorization should be done online or offline.

The Auto Authorize Max. Amount for Offline configuration setting in the POS Profile’s User Defined Functions(UDF) for the ELV@POS Function should be configured with the floor limit and then theEFT_USER_EXIT_AUTO_AUTH_AMOUNT property is set to this value.

The EFT User Exit implementation checks if the requested amount is below the floor limit and if so it can author-ize it offline; otherwise it authorizes it online.

For an example, see how the floor limit is checked in the doPurchaseOrRefund method in the VirtualEFT-DeviceRequestProcessor class.

7.1.33 Allow / Disallow Refund, Void & Post VoidThe Tender component in the Configurator can be used to control if refund, void, or post void is allowed.

7.1.34 Handling Multiple EFT User ExitsSAP Enterprise POS can be configured to support more than one EFT User Exit implementation.The following should be considered in a multiple EFT User Exit environment:

One of the EFT User Exit implementations has to respond to the authorize or admin methods. So,each EFT User Exit implementation should check if it can handle the request, and if so return true.

If none of the EFT User Exits return true to the admin or authorize method call, the POS client ap-pears to be stuck since it is waiting for one of the EFT User Exits to respond.

POWERON requires some special handling. If all the EFT User Exits require the POWERON message,they should coordinate who responds to the POWERON request.

If there is a waiting authorization, the authorization type should be checked and the EFT User Exit re-sponsible for the authorization type should handle the request.

But if there is no waiting authorization, the POWERON request should be sent to all the EFT User Exits.All the EFT User Exits should return false to the admin method except the last EFT User Exit whichshould return true.

When an authorization, admin or a card read request is canceled from the POS, the cancel request issent only to one EFT User Exit that is handling the request.

SAP®



of 90

8 Configuration

8.1 POS Client ConfigurationThe startpos.cmd and startpos.sh should be updated to include the location of the EFT User Exit imple-mentation JAR file in the POS client classpath. Below is an example of how the VirtualEFT JAR file is addedto the POS client path (shown in bold). The VirtualEFT provides a sample implementation of an EFT User Ex-it.

:REM Add Triversity Jars to classpathSET CP=%CP%;.\securitySET CP=%CP%;.\lib\tw-security.jarSET CP=%CP%;.\lib\was-stubs.jarSET CP=%CP%;.\lib\client-updates.jarSET CP=%CP%;.\lib\client.jarSET CP=%CP%;.\lib\editor.jarSET CP=%CP%;.\lib\te_clientsrvr.jarSET CP=%CP%;.\lib\loaderutil.jarSET CP=%CP%;.\lib\EFTUserExit.jarSET CP=%CP%;.\lib\VirtualEFT.jarSET CP=%CP%;.\lib\dsl.jarSET CP=%CP%;.\lib\dsllocal.jarSET CP=%CP%;.\lib\tef_logging.jarSET CP=%CP%;.\lib\tef.jarSET CP=%CP%;.\lib\ext\j2ee.jarSET CP=%CP%;.\lib\ext\jpos17.jarSET CP=%CP%;.\lib\ext\ib6core.jar:

The device.properties (present in custom/client/config folder) should be modified to load the EFTUser Exit implementation as shown below:

device.controls.1=com.triversity.transactionware.framework.deviceservices.triversitydevice.controls.2=com.triversity.transactionware.framework.deviceservices.ingenicodevice.controls.3=com.triversity.transactionware.framework.deviceservices.eftuserexit

EFTUserExit1=com.saptrv.te.userexit.virtualeft.VirtualEFTDevice

The EFTUserExit property should be set with the fully qualified class name of the EFT User Exit implementationclass. The EFTUserExit property name is suffixed with a number starting from 1. This implies that multiple EFTUser Exits can be loaded in the POS clients.

In the above example, com.saptrv.te.userexit.virtualeft.VirtualEFTDevice class should be re-placed with the fully qualified class name of the EFT User Exit implementation class.

If the EFT User Exit has been successfully loaded, on POS client startup, the screen receipt shows the numberof EFT User Exits loaded. Below is a sample of how the screen receipt will look:

SAP®



of 90

Fig. 10: A Screen Receipt Showing the Number of EFT User Exits Loaded

In addition, some property definitions in the custom/client/config/layout.properties file are required by the EFTUser Exit to display the EFT connection status EFT ON or EFT OFF if logged on or logged off. Those propertydefinitions are:

eftuserexit.form=eftuserexit # this makes it look in status for EFT User Exit de-viceeftuserexit.frame=0.13875,0.9716666666666667,0.13375,0.03 #.540,.187,.065,.028eftuserexit.backgroundcolor=0xCCCCCCeftuserexit.hilightbackgroundcolor=0x000000eftuserexit.hilighttext.color=0x00000eftuserexit.text.color=0x000000eftuserexit.text.font=Defaulteftuserexit.text.height=0.6eftuserexit.text.style=boldeftuserexit.text.horizontal=right

8.2 POS Profile ConfigurationIn Terminal Operations, under EFT User Exit options, Conditional Data Form should be set to a data formcontaining tww conditional prompts that have the data types EFT_USER_EXIT_AUTH_RESULT andEFT_USER_EXIT_ADMIN_RESULT. The minimum length should be 1, maximum length should be set to 64, andthe source device should be set to EFT User Exit.

If an authorization request needs to be sent to the EFT User Exit, the Authorizer property should be set to EFTUser Exit. This can be set in TenderPayment, TenderRefund, SellNonMerch, ReturnNonMerch,NonFinancialEFT, SellMerch and ReturnMerch function types.

If an administration function needs to be sent to the EFT User Exit, an EFT User Exit administration function typeneeds to be defined.

SAP®



of 90

8.3 EFT Device ConfigurationUsually, EFT device related configurations, such as the IP address and port number, are saved to a local file inthe POS client. Another option is to save the EFT device configuration in the Site parameters table that canthen be viewed/modified in the POS Manager. EFT device configuration parameters can be added eitherthrough POS Manager or through the SiteParametersMaintenance import file.

The following example shows you how to add two parameters, the IPAddress and COMPortNumber. Once im-ported, they can then be maintained in the POS Manager in Store Information present within Store Setup.

<?xml version="1.0" encoding="UTF-8"?>

<SiteParameterMaintenance Version="3.0" xmlns="http://www.triversity.com/TE/integration/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.triversity.com/TE/integration/ SiteParameterMaintenance.xsd">

<Header>

<OrganizationID>Triversity</OrganizationID>

<ApplyToStores>

<RetailStoreID>*</RetailStoreID>

</ApplyToStores>

<ForwardToHostedSites>false</ForwardToHostedSites>

<MessageId>578a1bd1ed6fcf2df20001</MessageId>

<Timestamp>2001-12-17T09:30:47-05:00</Timestamp>

<Originator>SiteParameterMaintenanceAdapter</Originator>

<AckType>Always</AckType>

<AckDestinationType>Queue</AckDestinationType>

<AckDestinationName>queue/SiteParameterMaintenanceAck</AckDestinationName>

</Header>

<Body>

<SiteParameterGroup>

<SiteParameter action="AddUpdate">

<ParameterID>IPAddress</ParameterID>

<ParameterValue>142.67.8.90</ParameterValue>

</SiteParameter>

<SiteParameter action="AddUpdate">

<ParameterID>COMPortNumber</ParameterID>

<ParameterValue>2</ParameterValue>

</SiteParameter>

</SiteParameterGroup>

</Body>

</SiteParameterMaintenance>

SAP®



of 90

Once the EFT device configurations are added, they are available in the header info map that is sent to the EFTUser Exit.

8.4 Sample Implementation - Virtual EFT Device PropertiesThe Virtual EFT is a sample code that acts as a real device. This is a template for a third-party to demonstrateways to implement functions.

The Virtual EFT is amount driven. Details of the amounts can be found in Section 13.

Sale - Card@EFT

Amount fromAmountto Card Comments Receipt

0 50.00 Visa Approved _SIG Signature

50.01 60.00 Visa Manually ApprovedSignature - man. Ap-proval No.

60.01 70.00 Visa Approved - Sig Verification70.01 75.00 Visa Approved - Sig Verification - timeout Signature

Etc.Refund - Card@EFT

Amount fromAmountto Card Comments Receipt

0 50.00 Visa Approved _SIG Signature

50.01 60.00 Visa Manually ApprovedSignature - man. Ap-proval No.

60.01 70.00 Visa Approved - Sig Verification70.01 75.00 Visa Approved - Sig Verification - timeout Signature

75.01 80.00 Visa

Referral (Call For Auth) - Existing POSBusiness logic Call for Authorizationprocessing

Dependent uponprocessing

80.01 90.00 Visa Declined - Printer req No receipt90.01 100.00 Visa Declined - No Printer req No receipt

100.01 150.00 Mastercard Approved Signature150.01 200.00 Mastercard Declined No receipt200.01 250.00 Amex Approved Signature250.01 300.00 Amex Declined No receipt300.01 max Visa Approved Signature

Fig. 11: Virtual EFT Device

As stated earlier, the VirtualEFT is a sample implementation of an EFT User Exit. Its behavior can be configuredby using the VirtualEFTdevice.properties (present in custom/client/config folder). This is a standardproperties file made of <Key>=<Value> pairs, however the VirtualEFT implementation recognizes three types ofproperty entries: Request, Response, and CardInfo.

A request corresponds to an invocation of the virtual EFT device, as a result of a cashier operation at the POSclient. When the Virtual EFT device receives a request, it also receives the card type used, as specified by thecashier in the POS client menu, and the transaction total amount. A response corresponds to the Virtual EFTdevice behavior being triggered by a given request. The Virtual EFT Device properties allow you to configuredifferent responses depending on the card type used and the transaction total amount of a request.

SAP®



of 90

8.4.1 Request PropertiesRequest properties define how a given request is processed by the virtual EFT device. Here is a sample of re-quest properties for a given request:

Request.UNKNOWNAUTH.RequestType=Authorization-PurchaseRequest.UNKNOWNAUTH.CardType=UnknownRequest.UNKNOWNAUTH.Amt1=0.00Request.UNKNOWNAUTH.Amt2=1000.00Request.UNKNOWNAUTH.CardInfoToUse=VISARequest.UNKNOWNAUTH.ResponseToUse=APPROVEDRequest.UNKNOWNAUTH.IsPrinterRequired=true

The Request component indicates that this is a request property.

The next component, UNKNOWNAUTH in the example, is an arbitrary ID whose purpose is to uniquely identifythe request by giving it a name. Consequently, all request properties sharing the same ID refer to the same re-quest.

The third component is a predefined attribute from that list: RequestType, CardType, Amt1, Amt2, CardInfo-ToUse, ResponseToUse, and IsPrinterRequired.

8.4.1.1 Request Type AttributeRequestType identifies the type of request. Each request type falls into one of three main categories: authoriza-tion, administrative, and card information.

The following shows the available request types (in bold) for each request category:

Authorization

o None: Indicates that no authorization is required.

o Reload: Indicates that a credit instrument (typically a gift card) is having its credit balance in-creased.

o Activate: Indicates that a credit instrument (such as a gift card) is being put into use.

o Issue: Indicates that a credit instrument (such as a gift card) is being issued. This is similar toActivate but is used mostly for non-denominated gift cards.

o Cashout: Indicates that a credit instrument (typically a gift card) is having its credit balance re-duced to zero in return for cash.

o Payment: Indicates a payment being made against the outstanding balance for a credit instru-ment.

o Authorization-Purchase: Indicates a request to authorize a purchase against the accountrepresented by a credit instrument. This action reduces the credit balance available in the ac-count (and, in the case of credit card, increases the amount owing).

o Authorization-Refund: Indicates a request to authorize a refund against the accountrepresented by a credit instrument. This action increases the credit balance available in the ac-count (and, in the case of credit card, decreases the amount owing).

SAP®



of 90

o Balance_Inquiry: Indicates a request to determine the current balance of the account asso-ciated with a credit instrument. The balance may be the amount of credit available and/or theamount currently owing, depending on the type of credit instrument.

o ItemAttributes: Indicates that authorization type is determined by Item Attributes. A well knownattribute 'ItemAuthAction' is used to specify the actual authorization type.

o To identify a void request for any of the above authorization requests, just prefix the name of theauthorization request with "Void-", for example: Void-Authorization-Purchase.

(Source: com/triversity/transactionware/eftmanager/util/IAuthorizationTypeConstants.java)

Administrative:

o LOGONo LOGOFF

o SETTLEMENTo TOTAL_SNAPSHOT

o RELEASE_CARD

o GET_DATETIMEo SET_DATETIME

o POWERON

o FAILOVERo GET_SOFTWARE_INFO

o ENABLE_MSRo DISABLE_MSR

o GET_TERMINAL_ID

o DIAGNOSISo INITIALIZATION

o REPRINT_LAST_RECEIPT

o KEY_RENEWAL(Source: com/saptrv/te/userexit/virtualeft.java)

In addition to the predefined administrative request types above, it is also possible to define newones with the Configurator through the User-Defined Functions menu option. Some are deliveredoff the shelf, for example, EFT_USER_EXIT_LOGON.

Card information

o GetCardInfo

SAP®



of 90

8.4.1.2 Card Type AttributeThe CardType attribute indicates that the request properties apply to cards of that type. Possible values are (inbold):

CreditCard: Credit card

DebitCard: Debit card

PrivateLabelCard: Private label card

StoredValueCard: Stored value card (Gift Card)

Cheque: Cheque

None: May be used in messages such as SignOn

SmartCard: Smart card

ThirdPartyCard: Third-party cards (such as Phone cards)

Unknown (this is also the default value if card type is not specified in the properties)(Source: com/triversity/transactionware/transnetauthorizer/model/AccountType.java)

8.4.1.3 Amount Attributes (Amt1 and Amt2)The Amt1 and Amt2 attributes define a range of amounts. That range indicates that the request properties applyto requests for which the total amount falls into the specified range. Each amount attribute must be defined withtwo digits after the decimal point.

For example, you can specify an amount range from 0.00 to 1000.00 in the default currency.

8.4.1.4 CardInfoToUse AttributeThe CardInfoToUse attribute is used to identify which card information properties provide the information forthe card relating to a request. In the following example, the request UNKNOWNAUTH has its CardInfoToUseattribute set to VISA. Since the string VISA matches the ID component of the CardInfo.VISA properties be-low, those properties in turn provide the card information for the UNKNOWNAUTH request.

Request.UNKNOWNAUTH.CardType=UnknownRequest.UNKNOWNAUTH.CardInfoToUse=VISA

...

CardInfo.VISA.CARD_NUMBER=4001000000000001CardInfo.VISA.EXPIRY_DATE=1210CardInfo.VISA.TENDER_ID=Visa

SAP®



of 90

8.4.1.5 ResponseToUse AttributeThe ResponseToUse attribute is used to identify which response properties provide the response configurationfor the request. In the following example, the request UNKNOWNAUTH has its ResponseToUse attribute set toAPPROVED. Since the string APPROVED matches the ID component of the Response.APPROVED propertiesbelow, those properties in turn provide the response configuration for the UNKNOWNAUTH request.

Request.READCARD.ResponseToUse=READCARD

...

Response.READCARD.Callback0.Display.Location=SystemFrameResponse.READCARD.Callback0.Display.Msg=PLEASE ENTER CARDResponse.READCARD.Callback0.Display.Delay=3000Response.READCARD.Callback1.Display.Location=SystemFrameResponse.READCARD.Callback1.Display.Msg=PLEASE ENTER PINResponse.READCARD.Callback1.Display.Delay=3000

8.4.1.6 IsPrinterRequired AttributeThe IsPrinterRequired attribute is used to specify whether the request requires a printer. Possible valuesare true or false.

For example:

Request.UNKNOWNAUTH.IsPrinterRequired=true

SAP®



of 90

8.4.2 Response PropertiesResponse properties define how the response is processed for all requests with a ResponseToUse attribute setto a value identical to the response ID as described in section 8.4.1.5 ResponseToUse Attribute above.

Response.KNOWNCARD_APPROVED.Callback0.Display.Location=DetailFrameResponse.KNOWNCARD_APPROVED.Callback0.Display.Msg=CONNECTINGResponse.KNOWNCARD_APPROVED.Callback0.Display.Delay=1000Response.KNOWNCARD_APPROVED.Callback1.Display.Location=DetailFrameResponse.KNOWNCARD_APPROVED.Callback1.Display.Msg=PROCESSINGResponse.KNOWNCARD_APPROVED.Callback1.Display.Delay=1000Response.KNOWNCARD_APPROVED.Callback2.Print.FormName=eftUserExitFullReceiptResponse.KNOWNCARD_APPROVED.Callback2.Print.ReceiptProperty=fullReceiptResponse.KNOWNCARD_APPROVED.Callback2.Print.ReceiptTxt=MY TEST RECEIPT@@@SAMPLE LINEResponse.KNOWNCARD_APPROVED.Callback2.Print.Delay=1000Response.KNOWNCARD_APPROVED.Callback3.OperatorInput.PromptText=IS SIGNATURE OKResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.InfoText=IS SIGNATURE OKResponse.KNOWNCARD_APPROVED.Callback3OperatorInput.DetailText=IS SIGNATURE OKResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Choice0.MenuLabel=YESResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Choice0.ResultCode=APPROVEDResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Choice0.DisplayMsg=Response.KNOWNCARD_APPROVED.Callback3.OperatorInput.Choice1.MenuLabel=NOResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Choice1.ResultCode=DECLINEDResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Choice1.DisplayMsg=SIGNATURE DOESNOT MATCHResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Default=NOResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.Format=Response.KNOWNCARD_APPROVED.Callback3.OperatorInput.MinLength=Response.KNOWNCARD_APPROVED.Callback3.OperatorInput.MaxLength=Response.KNOWNCARD_APPROVED.Callback3.OperatorInput.AllowCancel=TRe-sponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.ResultKey=VIRTUALEFT_SIGNATURE_RESULTResponse.KNOWNCARD_APPROVED.Callback3.OperatorInput.TimeOut=60000Response.KNOWNCARD_APPROVED.Callback4.Display.Location=SystemFrameResponse.KNOWNCARD_APPROVED.Callback4.Display.Msg=PLEASE REMOVE CARDResponse.KNOWNCARD_APPROVED.Callback4.Display.Delay=3000Response.KNOWNCARD_APPROVED.ResultCode=APPROVEDResponse.KNOWNCARD_APPROVED.DisplayMsg=EFT APPROVEDResponse.KNOWNCARD_APPROVED.Data.AUTHORIZATION_NUMBER=123456

SAP®



of 90

8.4.2.1 Callback PropertiesThe example above shows that it is possible to define a sequence of callbacks. Each callback is identified by asequence of numbers from 0 to an unlimited number. The sequence number guarantees the order of executionof the callbacks. There must only be a single callback (Display, Print or OperatorInput) for a given callback se-quence number.

Display PropertiesEach callback can have the following display properties:

Location (DetailFrame, SystemFrame or CustomerLineDisplay)

Msg (an arbitrary message string)

Delay (in milliseconds).

ClearMessages (true)

The ClearMessages property is used to specify whether the request requires clearing of all messages of typeA from the User Exit. Possible value is true. Default value is false.

For example:

Response.KC_DEBITCARD_APPROVED.Callback5.Display.ClearMessages=true

Print PropertiesEach callback can have the following print properties:

FormName (must match the name of a document defined in the Configurator)

ReceiptProperty (must match the name of a variable used in a document definition in the Configura-tor)

ReceiptTxt (this is the free format text being the value of the variable specified in ReceiptProper-ty)

Delay (in milliseconds)

See section 6.2.3 for more details.

Operator Input PropertiesEach callback can have operator input properties. The user input is either a choice list or a text entry and this isdefined by respectively defining either ChoiceN properties or a single Format property. The operator input pa-rameters can be:

PromptText (text prompted to the operator)

InfoText (text displayed in the information window)

DetailText (text displayed in the detail window)

ChoiceN (where N is a sequence number from 0 to N and each ChoiceN defines a choice list item)

Default (See section 6.2.2)

Format (See section 6.2.2)

MinLength (See section 6.2.2)

MaxLength (See section 6.2.2)

SAP®



of 90

AllowCancel (false)

The AllowCancel property is used to specify whether the request is allowed to cancel. If not allowed, the systemmessage CANCEL NOT ALLOWED will display and stay until the User Exit clears the message (See Clear-Messages). Possible value is false. Default value is true.

For example:

Response.KC_DEBITCARD_APPROVED.Callback1.IsCancelAllowed=false

ResultKey (this is the key of the key-value pair returned that contains the result of the operator input asthe value)

TimeOut (User Exit timeout value in milliseconds for operator input)

The following shows how to specify a choice list operator input:Response.KNOWNCARD_APPROVED.Callback2.OperatorInput.PromptText=IS SIGNATURE OKResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.InfoText=IS SIGNATURE OKResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.DetailText=IS SIGNATURE OKResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Choice0.MenuLabel=YESResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Choice0.ResultCode=APPROVEDResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Choice0.DisplayMsg=Response.KNOWNCARD_APPROVED.Callback2.OperatorInput.Choice1.MenuLabel=NOResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Choice1.ResultCode=DECLINEDResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Choice1.DisplayMsg=SIGNATURE DOES NOTMATCHResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Default=NOResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.Format=Response.KNOWNCARD_APPROVED.Callback2.OperatorInput.MinLength=Response.KNOWNCARD_APPROVED.Callback2.OperatorInput.MaxLength=Response.KNOWNCARD_APPROVED.Callback2.OperatorInput.AllowCancel=TResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.ResultKey=VIRTUALEFT_SIGNATURE_RESULTResponse.KNOWNCARD_APPROVED.Callback2.OperatorInput.TimeOut=60000

The following shows how to specify a text entry operator input:

Response.APPROVED.Callback7.OperatorInput.PromptText=ENTER AUTH NUMResponse.APPROVED.Callback7.OperatorInput.InfoText=ENTER AUTH NUMResponse.APPROVED.Callback7.OperatorInput.DetailText=ENTER AUTH NUMResponse.APPROVED.Callback7.OperatorInput.Format=DigitsResponse.APPROVED.Callback7.OperatorInput.MinLength=1Response.APPROVED.Callback7.OperatorInput.MaxLength=6Response.APPROVED.Callback7.OperatorInput.AllowCancel=FResponse.APPROVED.Callback7.OperatorInput.ResultKey=VIRTUALEFT_AUTH_NUMResponse.APPROVED.Callback7.OperatorInput.TimeOut=30000

SAP®



of 90

8.4.2.2 Result Code PropertiesThe result code property specifies the result code returned by the Virtual EFT upon completion of the request.

Response.KNOWNCARD_APPROVED.ResultCode=APPROVED

The following are valid result codes:

APPROVED Indicates that the EFT User Exit successfully processed or authorized the request.

APPROVED_WITH_VERIFICATION Indicates that the EFT User Exit successfully authorized the re-quest but final approval is pending identity verification

DECLINED Indicates that the EFT User Exit failed to process or declined the request.

REFERRED Indicates that the EFT User Exit has successfully processed the request but requested tocall for authorization.

TIMED_OUT Indicates that the EFT User Exit has timed out while processing the request.

CANCELED Indicates that the EFT User Exit has canceled the request.(Source: com.triversity.transactionware.eftuserexit/EFTUserExitResult.java)

8.4.2.3 Display Message PropertiesThe display message result code property specifies the message returned by the Virtual EFT to be displayedupon completion of the request.

Response.KNOWNCARD_APPROVED.DisplayMsg=EFT APPROVED

8.4.2.4 Data PropertiesThe response data property specifies key-value pairs returned by the Virtual EFT upon completion of the re-quest.

Response.KNOWNCARD_APPROVED.Data.AUTHORIZATION_NUMBER=123456

Valid key-value pairs are described in section 9.

SAP®



of 90

8.4.3 Card Information PropertiesCard information properties provide information about the card referred to in a CardInfoToUse request proper-ties.

See section 8.4.1.4 CardInfoToUse Attribute.

TRACK_1

TRACK_2

TRACK_3

TENDER_ID

TRACK_1 and TRACK_2To specify card number and expiry date for any card except EC Card, you must specify either a TRACK_1 or aTRACK_2 property.

Track 1:

CardInfo.VISA.TRACK_1=B4001000000000001^^101200000000

where card number = 4001000000000001 and expiry date is 1012

Track 2:CardInfo.VISA.TRACK_2=4001000000000001=101200000000

where card number = 4001000000000001 and expiry date is 1012

Track 1 Format

Field Example

Format Code B

PAN 4000000000000001

Field Separator ^

Name (<Last Name>/<First Name>) Bloe/Joe

Field Separator ^

Expiry Date (ED) 1612

Additional Data 90100000

Discretionary Data abcdefghij ... xyz

SAP®



of 90

Track 2 Format

Field Example

PAN 4000000000000001

Field Separator =


Additional Data 90100000

Discretionary Data abcdefghij ... xyz

TRACK_3To specify card data (Bank Identification Number, Customer Account Number, Country Code, Expiry Date, CardSequence Number) for an EC Card, use a TRACK_3 property.

CardInfo.ECCARD_BLACKLIST.TRACK_3=015912345678=01234567893=2809540040000006060013016351020000009123201951851==1=8215291000005460

where Bank Identification Number = 12345678, Customer Account Number = 0123456789, CountryCode = 280, Expiry Date = 0912 and Card Sequence Number = 3

Track 3 Format:

Field Example

Format Code (FC) 01

PAN - Major Industry Identifier (optional) 59

PAN - Bank Identification Number (BIN) 12345678

PAN - Field Separator =

PAN - Customer Account Number (CAN) 0123456789

PAN - Check Digit 3

Field Separator =

Country Code (exists only if MII=59) 280

Irrelevant fields 95400400000060600130163510200000


Card Sequence Number 3

Irrelevant fields 201951851==1=8215291000005460

SAP®



of 90

TENDER_ID

Use the tender ID property (TENDER_ID) to specify the type of tender. Valid tender IDs are configured in theConfigurator.

CardInfo.VISA.TENDER_ID=Visa

CardInfo.MASTERCARD.TENDER_ID=Mastercard

CardInfo.GIFTCARD.TENDER_ID=Giftcard

CardInfo.VISA.CARD_NUMBER=4001000000000001CardInfo.VISA.EXPIRY_DATE=1210CardInfo.VISA.TENDER_ID=Visa

CardInfo.MASTERCARD.CARD_NUMBER=5454545454545454CardInfo.MASTERCARD.EXPIRY_DATE=1220CardInfo.MASTERCARD.TENDER_ID=Mastercard

CardInfo.GIFTCARD.CARD_NUMBER=6006000000000001CardInfo.GIFTCARD.EXPIRY_DATE=1250CardInfo.GIFTCARD.TENDER_ID=Giftcard

Valid tender IDs (TENDER_ID) are configured in the Configurator.

SAP®



of 90

8.5 LoggingThe EFT User Exit implementation can use either the standard Java logging API or the SAP Triversity proprie-tary logging API.

With the Java logging API (out of the box), it is impossible to configure separate file handlers for different loggingcategories and it’s also impossible to configure a logging level for each logger object independent of the filehandler logging level. The SAP Triversity proprietary logging API can be used if the application requires separatelog files for different logging categories, otherwise the standard Java logging API can be used.

The standard Java logging API is configured for use with the posclient/logging.properties file and the SAP Tri-versity proprietary logging API is configured using the posclient/loggingExt.properties file.

The Virtual EFT implementation uses the SAP Triversity proprietary logging API. The proprietary logging API isdefined in src/com/triversity/tef/util/logging/Log.java.

8.5.1 Using the SAP Proprietary Logging API1. In the class where you want to produce log information (for example, MyClass), declare and initialize a log

instance:private static final Log LOG = Log.getLogInstance(

MyClass.class.getName() );

2. Use the log instance as needed to generate logging information, for example:

int myVariable;...LOG.debug("myVariable: " + myVariable);

8.5.2 SAP Proprietary Logging API

/** * This method creates a consistent log line entry for entering a method * * @param sourceMethod - a method name */

public void enter(String sourceMethod);

/** * This method creates a consistent log line entry for entering a method * * @param sourceMethod - a combination of the class and method names * @param parameters - extra parameters that are also added to the entry */

public void enter(String sourceMethod, Object[] parameters);

/** * This method creates a consistent log line entry for exiting a method * * @param sourceMethod - the method name */

public void exit(String sourceMethod);

SAP®



of 90

/** * This method creates a consistent log line entry for exiting a method * * @param sourceMethod - the method name * @param parameters - extra parameters that are also added to the entry */

public void exit(String sourceMethod, Object[] parameters);

/** * A method to determine if a specified logging level would result in an * entry * * @param aLevel - a Level value */

public boolean isLogging(Level aLevel);

/** * A method to determine if a specified logging level is enabled * */

public boolean isDebugEnabled();public boolean isInfoEnabled();

/** * These methods create a consistent log line entry at given log level

* * @param o - object to log * @param t - exception to log */

public void debug(Object o);public void debug(Object o,Throwable t);public void info(Object o);public void info(Object o,Throwable t);public void warn(Object o);public void warn(Object o,Throwable t);public void error(Object o);public void error(Object o,Throwable t);public void fatal(Object o);public void fatal(Object o, Throwable t);

/** * Miscelaneous */

public void error(HttpSession session, String message);public void error(HttpSession session, String message, Throwable e);public void warn(HttpSession session, String message);public void info(HttpSession session, String message);public void debug(HttpSession session, String message);

/** * This method should only be called just before the application * shutdowns to ensure buffered log messages are written to output * streams.

SAP®



of 90

*/

public static void shutdown();

logging.properties configuration file:

### ----------Configurations using standard java logging API format

# Specify the Handlers for logging.

# com.triversity.tef.util.logging.ConsoleSystemOutHandler is a custom handler

# to output to System Out stream. We need the custom handler because

# java.util.logging.ConsoleHandler only sends output to System error stream.

handlers=java.util.logging.FileHandler,com.triversity.tef.util.logging.ConsoleSystemOutHandler

com.triversity.level =WARNING

#### Nominally enabled proactive INFO-level logging...

com.triversity.transactionware.framework.presentation.serviceadapter.level =WARNING

# File Handler specific properties.

java.util.logging.FileHandler.pattern =logs/te_client.log

java.util.logging.FileHandler.limit = 1000000

java.util.logging.FileHandler.count = 25

java.util.logging.FileHandler.formatter =com.triversity.tef.util.logging.formatters.TriversityFormat

# Custom Console System Out Handler

com.triversity.tef.util.logging.ConsoleSystemOutHandler.level = WARNING

com.triversity.tef.util.logging.ConsoleSystemOutHandler.formatter =com.triversity.tef.util.logging.formatters.TriversityFormat

loggingExt.properties configuration file:

SAP®



of 90

# This configuration file contains SAP Triversity proprietary logging confi-guration parameters

# In JDK logging API, out of the box, it's impossible to configure separateFileHandlers

# for different logging category and to configure logging level for each log-ger object independent of logging level for

# file handler

# this configuration file is only required if the application requires

# seperate log files for different logging categories, otherwise use thestandard JDK configuration format

# specified in the logging.properties file

# Description of FileHandler configuration parameters

# FileHandler.<fileHandlerName>.level : logging level e.g. ALL, FINE, INFO,WARNING, SEVERE

# FileHanlder.<fileHandlerName>.pattern: log file name

# FileHandler.<fileHandlerName>.limit : size of log file in bytes

# FileHandler.<fileHandlerName>.count : number of rolling log files

# FileHandler.<fileHandlerName>.formatter: formatter class for output logmessage

# Description of configuration parameters for logger objects

# multiple logger objects can send messages to the same file handler (e.g.same log file)

# each logger object can have its own logging level set independent of log-ging level set for the file handler

# logger.<loggerName>.fileHandler : specify the name of file handler

# logger.<loggerName>.level : logging level e.g. FINE, INFO, WARNING, SEVERE

# logger.<loggerName>.useParentHandlers: true or false to indicate if logmessage should be sent to parent logger objects

# Mapping JDK logging levels to log4j

# JDK level Log4j level

# ALL ALL

# FINE DEBUG

# INFO INFO

# WARNING WARN

# SEVERE ERROR

SAP®



of 90

### main log file for POS Client

FileHandler.FH1.level=ALL

FileHandler.FH1.pattern=logs/te_client.log

FileHandler.FH1.limit=1000000

FileHandler.FH1.count=25

FileHand-ler.FH1.formatter=com.triversity.tef.util.logging.formatters.TriversityFormat

#### Log file for EFT User Exit


FileHandler.FH2.pattern=logs/eftUserExit.log




# configuration parameters for logger object

# the logger object name is com.triversity

Logger.com.triversity.fileHandler=FH1

Logger.com.triversity.level= FINE

Logger.com.triversity.useParentHandlers = false

#### Logger object for EFT User Exit

Logger.com.triversity.transactionware.client.eftuserexit.fileHandler=FH2

Logger.com.triversity.transactionware.client.eftuserexit.level= FINE

Logger.com.triversity.transactionware.client.eftuserexit.useParentHandlers =false

Log-ger.com.triversity.transactionware.framework.deviceservices.eftuserexit.fileHandler=FH2

Log-ger.com.triversity.transactionware.framework.deviceservices.eftuserexit.level= FINE

Log-ger.com.triversity.transactionware.framework.deviceservices.eftuserexit.useParentHandlers = false

SAP®



of 90

Logger.com.saptrv.te.userexit.virtualeft.fileHandler=FH2

Logger.com.saptrv.te.userexit.virtualeft.level= FINE

Logger.com.saptrv.te.userexit.virtualeft.useParentHandlers = false

#Logger.com.saptrv.te.userexit.virtualeft.eftdevicesimulator.fileHandler=FH2

#Logger.com.saptrv.te.userexit.virtualeft.eftdevicesimulator.level= DEBUG

#Log-ger.com.saptrv.te.userexit.virtualeft.eftdevicesimulator.useParentHandlers =false

#Log-ger.com.saptrv.te.userexit.virtualeft.EFTDeviceMessageHandler.fileHandler=FH2

#Logger.com.saptrv.te.userexit.virtualeftEFTDeviceMessageHandler.level= DEBUG

#Log-ger.com.saptrv.te.userexit.virtualeft.EFTDeviceMessageHandler.useParentHandlers = false

JDK configuration format

# specified in the logging.properties file

# Description of FileHandler configuration parameters

# FileHandler.<fileHandlerName>.level : logging level e.g. ALL, FINE, INFO,WARNING, SEVERE

# FileHanlder.<fileHandlerName>.pattern: log file name

# FileHandler.<fileHandlerName>.limit : size of log file in bytes

# FileHandler.<fileHandlerName>.count : number of rolling log files

# FileHandler.<fileHandlerName>.formatter: formatter class for output logmessage

# Description of configuration parameters for logger objects

# multiple logger objects can send messages to the same file handler (e.g.same log file)

# each logger object can have its own logging level set independent of log-ging level set for the file handler

# logger.<loggerName>.fileHandler : specify the name of file handler

# logger.<loggerName>.level : logging level e.g. FINE, INFO, WARNING, SEVERE

# logger.<loggerName>.useParentHandlers: true or false to indicate if logmessage should be sent to parent logger objects

SAP®



of 90

# Mapping JDK logging levels to log4j

# JDK level Log4j level

# ALL ALL

# FINE DEBUG

# INFO INFO

# WARNING WARN

# SEVERE ERROR

### main log file for POS Client


FileHandler.FH1.pattern=logs/te_client.log




#### Log file for EFT User Exit


FileHandler.FH2.pattern=logs/eftUserExit.log




# configuration parameters for logger object

# the logger object name is com.triversity

Logger.com.triversity.fileHandler=FH1

Logger.com.triversity.level= FINE

Logger.com.triversity.useParentHandlers = false

#### Logger object for EFT User Exit

Logger.com.triversity.transactionware.client.eftuserexit.fileHandler=FH2

Logger.com.triversity.transactionware.client.eftuserexit.level= FINE

Logger.com.triversity.transactionware.client.eftuserexit.useParentHandlers =false

SAP®



of 90

Log-ger.com.triversity.transactionware.framework.deviceservices.eftuserexit.fileHandler=FH2

Log-ger.com.triversity.transactionware.framework.deviceservices.eftuserexit.level= FINE

Log-ger.com.triversity.transactionware.framework.deviceservices.eftuserexit.useParentHandlers = false

Logger.com.saptrv.te.userexit.virtualeft.fileHandler=FH2

Logger.com.saptrv.te.userexit.virtualeft.level= FINE

Logger.com.saptrv.te.userexit.virtualeft.useParentHandlers = false

#Logger.com.saptrv.te.userexit.virtualeft.eftdevicesimulator.fileHandler=FH2

#Logger.com.saptrv.te.userexit.virtualeft.eftdevicesimulator.level= DEBUG

#Log-ger.com.saptrv.te.userexit.virtualeft.eftdevicesimulator.useParentHandlers =false

#Log-ger.com.saptrv.te.userexit.virtualeft.EFTDeviceMessageHandler.fileHandler=FH2

#Logger.com.saptrv.te.userexit.virtualeftEFTDeviceMessageHandler.level= DEBUG

#Log-ger.com.saptrv.te.userexit.virtualeft.EFTDeviceMessageHandler.useParentHandlers = false

SAP®



of 90

9 Standard EFT User Exit Data KeysAuthorization Request Keys

Key

IDataTypes Constant

Description

Common Keys Keys that are present in all authorization request

EFT_USER_EXIT_AUTHORIZATION_TYPE

DT_EFT_USER_EXIT_AUTHORIZATION_TYPE

[String] Type of authorization request to be performed by the EFTUser Exit

(None, Reload, Activate, Issue, Cashout, Payment, Authorization-Purchase,,Authorization-Refund,Balance_Inquiry)

Refer to IAuthorizationTypeConstants class for the list of valid autho-rization types

EFT_USER_EXIT_CARD_TYPE

DT_EFT_USER_EXIT_CARD_TYPE

[String] Card Type associated with an EFT request (None, Credit-Card, DebitCard, PrivateLabelCard, StoredValueCard)

EFT_USER_EXIT_CARD_TYPE_ID

DT_EFT_USER_EXIT_CARD_TYPE_ID

[String] Card Type ID associated with a card type (i.e. ATT forStoredValueCard type)

REQUEST_MODIFIER

DT_REQUEST_MODIFIER

[String] The request modifer (value set to VOID to indicate a void of‘transaction_code'.

Set to VOID if present.

TENDER_ID

DT_TENDER_ID

[String] The unique tender identifier.

Defined in Configurator

PARAMETER

DT_PARAMETER

Tender ID can also be specified in this data type and must also bechecked along with DT_TENDER_ID

EFT_USER_EXIT_REQUESTED_AMOUNT

DT_EFT_USER_EXIT_REQUESTED_AMOUNT

[Money] Requested amount to be authorized (tender amount, activa-tion amount, reload amount, and so on.)

EFT_USER_EXIT_CURRENCY_CODE

DT_EFT_USER_EXIT_CURRENCY_CODE

[String] Currency code of the requested amount.

UDF_ID

DT_UDF_ID

[String] Identifier for the configuration settings applied or to be ap-plied to a User Defined Function (a configurable "retail" function).

Card Keys Keys that are present if card info is present.

CARD_NUMBER

DT_ACCOUNT_NUMBER

[MaskedString] The primary account number (PAN). This is the ac-count number associated with some kind of credit instrument, suchas a credit card or gift card.

EXPIRY_DATE

DT_EXP_DATE

[MaskedString] The expiry date.

TRACK_1

DT_TRACK_1

[byte[]] The magnetic stripe track 1.

TRACK_2

DT_TRACK_2


TRACK_3

DT_TRACK_3


SAP®



of 90

TRACK_4

DT_TRACK_4


Cheque Keys Keys that are present in a cheque authorization

TRANSIT_NUMBER

DT_TRANSIT_NUM

[String] The transit number. Forms part of a complete bank accountnumber.

CHEQUE_NUMBER

DT_CHEQUE_NUM

[String] The check number.

BANK_ACCOUNT_NUMBER

DT_BANK_ACCOUNT_NUMBER

[MaskedString] Used to capture the bank account number. It is popu-lated during the cheque authorization process for instance. It is theaccount number that the cheque will apply to.

BANK_NUMBER

DT_BANK_NUMBER

[String] Used to capture the bank number. It is populated during thecheque(check) authorization process (MICR) for instance. It is thebank number that the check will apply to.

CHECK_TYPE

DT_CHECK_TYPE

[Integer] The check type. This is typically parsed from the MICR de-vice. The valid values are defined in the {@link IDslMicrConst MICRservice constants} file. The check type constants have names of theform <code>DSL_MICR_CT_xxx</code>.

MICR_NUM

DT_MICR_NUM

[MaskString] The raw MICR number.

Manual Authorization related keys

MANUAL_AUTH

DT_MANUAL_AUTH

[Boolean] This data type is used to identify a request as needing ma-nual authorization.

This should not be made available as a data type for prompts in theConfigurator

EFT_USER_EXIT_ALLOW_MANUAL_AUTH

DT_EFT_USER_EXIT_ALLOW_MANUAL_AUTH

[Boolean] Flag to indicate whether or not request is configured to al-low manual authorization.

EFT_USER_EXIT_AUTO_AUTH_AMOUNT

DT_EFT_USER_EXIT_AUTO_AUTH_AMOUNT

[Money] When manual authorization is enabled, this is the configuredauto auth floor limit. Any requested amount below this amount can beauto approved.

EFT_USER_EXIT_OFFLINE_AUTH_AMOUNT

DT_EFT_USER_EXIT_OFFLINE_AUTH_AMOUNT

[Money] When manual authorization is enabled, this is the configuredoffline auth floor limit. Any requested amount below this floor limit canbe auto approved, above this amount manual authorization should betriggered.

EFT_USER_EXIT_REFERRAL_AUTH_AMOUNT

DT_EFT_USER_EXIT_REFERRAL_AUTH_AMOUNT

[Money] When manual authorization is enabled, this is the configuredreferral auth floor limit. When an online authorization response re-sults in a referral (call for auth), if the requested amount is below thisfloor limit then the request can be auto approved, above this amountmanual authorization should be triggered.

EFT_USER_EXIT_MANUAL_AUTH_SOURCE

DT_EFT_USER_EXIT_MANUAL_AUTH_SOURCE

[String] When manual authorization is performed, this is the source ofthe authorization number, see AuthorizationSourceCode for possiblevalues (excluding none and online).

Void Keys Keys included in requests when voiding a prior request

ORIGINAL_EXTERNAL_RESPONSE_CODE

DT_ORIGINAL_EXTERNAL_RESPONSE_CODE

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains theDT_EXTERNAL_RESPONSE_CODE which was provided in the originalauthorization response from the exit.

ORIGINAL_EXTERNAL_REFERENCE_NUMBER

DT_ORIGINAL_EXTERNAL_REFERENCE_NUMBER

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains theDT_EXTERNAL_REFERENCE_NUMBER which was provided in the

SAP®



of 90

original authorization response from the exit.

ORIGINAL_HOST_DATE_TIME

DT_ORIGINAL_HOST_DATE_TIME

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains the DT_HOST_DATE_TIME whichwas provided in the original authorization response from the exit.

ORIGINAL_HOST_SEQUENCE_NUMBER

DT_ORIGINAL_HOST_SEQUENCE_NUMBER

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains theDT_HOST_SEQUENCE_NUMBER which was provided in the origi-nal authorization response from the exit.

ORIGINAL_BALANCE_AMOUNT

DT_ORIGINAL_BALANCE_AMOUNT

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains the DT_BALANCE_AMOUNTwhich was provided in the original authorization response from theexit.

ORIGINAL_APPROVED_AMOUNT

DT_ORIGINAL_APPROVED_AMOUNT

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains the DT_APPROVED_AMOUNTwhich was provided in the original authorization response from theexit.

ORIGINAL_AUTHORIZATION_NUMBER

DT_ORIGINAL_AUTH_NUM

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains the DT_AUTH_NUM which wasprovided in the original authorization response from the exit.

ORIGINAL_EFT_USER_EXIT_SEQUENCE_NUMBER

DT_ORIGINAL_EFT_USER_EXIT_SEQUENCE_NUMBER

[String] When sending a request back to a EFT User Exit for voidprocessing, this property contains theDT_EFT_USER_EXIT_SEQUENCE_NUMBER which was providedin the original authorization request sent to the exit (only if algorithmset in UDF Config).

Others

EFT_USER_EXIT_REQUEST_TIMEOUT

DT_EFT_USER_EXIT_REQUEST_TIMEOUT

[Integer] Request timeout as set in a UDF Config, sent back to theclient when a requestis to be authorized by an EFT User Exit.

EFT_USER_EXIT_SEQUENCE_NUMBER

DT_EFT_USER_EXIT_SEQUENCE_NUMBER

[String] Optional sequence number (if algorithm set in UDF Configu-ration) for requests configured to be authorized by an EFT User Exit.

_datasource_

DT_DATASOURCE

[String] Identifies actual data source used by the User Exit.

For example, EFTUserExit, Keyboard, Scanner, MSR.

Refer to ConfigPOSConstants class.

EFT_USER_EXIT_IDENTITY_VERIFIED

DT_EFT_USER_EXIT_IDENTITY_VERIFIED

[Boolean] When an authorization request resulted in an Approvedwith Identity verification authorization result(DT_EFT_USER_EXIT_AUTH_RESULT =APPROVED_WITH_VERIFICATION), this is the result of the verifica-tion process (true if identity was verified and the authorization shouldbe accepted, false otherwise).

SAP®



of 90

Authorization Response Keys

Key

IDataTypes Constant

Description

Mandatory Keys Keys that must be present in the authorization response

EFT_USER_EXIT_AUTH_RESULT

DT_EFT_USER_EXIT_AUTH_RESULT

Result of authorization processing.

See EFTUserExitResult for valid result codes

Conditional Keys Common keys that may be present depending on the type of authori-zation

AUTHORIZATION_NUMBER

DT_AUTH_NUM

[String] The authorization number. This is the number that authorizesuse of a tender.

EXTERNAL_RESPONSE_CODE

DT_EXTERNAL_RESPONSE_CODE

[String] Response code provided by an external EFT service provider(bank)

EXTERNAL_REFERENCE_NUMBER

DT_EXTERNAL_REFERENCE_NUMBER

[String] Reference number provided by an EFT provider (bank)

HOST_DATE_TIME

DT_HOST_DATE_TIME

[String] Date time the authorization was performed at the EFT pro-vider (bank)

HOST_SEQUENCE_NUMBER

DT_HOST_SEQUENCE_NUMBER

[String] Sequence number provided by an EFT provider (bank)

BALANCE_AMOUNT

DT_BALANCE_AMOUNT

[String] Available balance amount remaining on a card. The format ofthe amount string has to be in the default locale.

APPROVED_AMOUNT

DT_APPROVED_AMOUNT

[String] Amount approved by an EFT provider (bank). The format ofthe amount string has to be in the default locale. Approved amountcould be different from the requested amount in which case the ap-proved amount has to be set.

RECEIPT_MESSAGE

DT_RECEIPT_MESSAGE

[String] Receipt text sent by an EFT provider (bank).

Card Keys Keys that hold card data

CARD_NUMBER

DT_ACCOUNT_NUMBER

[MaskedString] The primary account number (PAN). This is the ac-count number associated with some kind of credit instrument, suchas a credit card or gift card.

EXPIRY_DATE

DT_EXP_DATE

[MaskedString] The expiry date.

TRACK_1

DT_TRACK_1


TRACK_2

DT_TRACK_2


TRACK_3

DT_TRACK_3


TRACK_4 [byte[]] The magnetic stripe track 4.

SAP®



of 90

DT_TRACK_4

LANGUAGE_ID

DT_LANGUAGE_ID

[String] The language specified on a debit/credit card in ISO format

EFT_USER_EXIT_CARD_SOURCE

DT_EFT_USER_EXIT_CARD_SOURCE

[String] Input mode specified by EFT User Exit.

Possible values are Swiped, Keyed, MICR, Scanned (case sensitive)

Merchant/Bank ID Keys Keys that are related to merchant or bank data

MERCHANT_ID

DT_MERCHANT_ID

[String] Merchant ID assigned to store by an EFT provider (bank)

AUTHORIZING_TERMINAL_ID

DT_AUTHORIZING_TERMINAL_ID

[String] Terminal ID assigned to store by an EFT provider (bank)

AUTHORIZING_BANK_ID

DT_AUTHORIZING_BANK_ID

[String] Bank ID used to identify the issuing bank

Administration Request Keys

Key

IDataTypes Constant

Description

Common Keys Keys that are present in an administration request

EFT_USER_EXIT_ADMIN_FUNCTION_TYPE

DT_EFT_USER_EXIT_ADMIN_FUNCTION_TYPE

[String] EFT User Exit administration function type. For example,LOGON, LOGOFF, POWERON, etc

Store Close / Poweron Keys Keys that are present in a store close / power on administration re-quest

STORE_CLOSE_INFO

DT_EFT_USER_EXIT_ADMIN_STORE_CLOSE_INFO

IPropertyMap[] List of properties containing store close informationspecifically the store close business date

EFT_USER_EXIT_ADMIN_TRIGGER_SOURCE

DT_EFT_USER_EXIT_ADMIN_TRIGGER_SOURCE

[String] Specifies the source that triggered the EFT User Exit adminUDF. This is set if automatically triggered.

Valid values are

POSMANAGER.STORE_CLOSE - Indicates EFT User Exit adminUDF was triggered as a result of store close from POS Manager

POS.STORE_CLOSE - Indicates EFT User Exit admin UDF wastriggered as a result of store close from POS

POS.POWERON - Indicates EFT User Exit admin UDF was triggeredas a result of Poweron from POS

TRIGGER_WAITING_AUTH

DT_EFT_USER_EXIT_ADMIN_TRIGGER_WAITING_AUTH

[String] Flag to indicate if the waiting authorization UDF should betriggered or not.

This is set by the EFT User Exit in the power on EFT User Exit adminfunction response to indicate that the waiting auth should be trig-gered after the poweron EFT user exit admin UDF.

HAS_WAITING_AUTH

DT_EFT_USER_EXIT_ADMIN_HAS_WAITING_AUTH

[Boolean] Flag to indicate if there is a waiting auth UDF or not. Thisflag is present in the power on EFT User Exit admin function and isan indication that there is an authorization waiting for a response

SAP®



of 90

Other Keys

EFT_USER_EXIT_REQUEST_TIMEOUT

DT_EFT_USER_EXIT_REQUEST_TIMEOUT

[Integer] Request timeout as set in a UDF Config, sent back to theclient when a requestis to be authorized by an EFT User Exit.

EFT_USER_EXIT_SEQUENCE_NUMBER

DT_EFT_USER_EXIT_SEQUENCE_NUMBER

[String] Optional sequence number (if algorithm set in UDF Configu-ration) for requests configured to be authorized by an EFT User Exit.

_datasource_

DT_DATASOURCE

[String] Identifies actual data source used by the User Exit.

For example, EFTUserExit, Keyboard, Scanner, MSR.

Refer to ConfigPOSConstants class.

Administration Response Keys

KeyIDataTypes Constant

Description

Mandatory Keys Keys that must be present in an administration response

EFT_USER_EXIT_ADMIN_RESULT

DT_EFT_USER_EXIT_ADMIN_RESULT

Result of admin processing

See EFTUserExitResult for valid result codes

10 Limitations10.1.1 Pre-Authorization and Allocated FeaturesNone in this SW Version. To be implemented at a later stage.

10.1.2 Request PINThis command is used to request a PIN for Loyalty and other Non Banking cards.

None in this SW Version. To be implemented at a later stage.

10.1.3 PreAuthorization and Completion of Item AuthorizationNone in this SW Version. To be implemented at a later stage.

SAP®



of 90

11 PCI ConsiderationsSince the POS client sends data (including sensitive data, such as credit card numbers) as string objects to theEFT User Exit, it is up to the EFT User Exit implementation to ensure that it satisfies all PCI requirements. Spe-cial care should be taken when logging data.

Any response data sent to the POS client is logged in the log file and TLOG. If sensitive response data needs tobe sent, the Data Type needs to be configured as MaskedString data type in the Configurator. This data is en-crypted in the TLOG and masked in the log files. Since response data is encrypted, if the data needs to be sentto external systems, the external system will also need to have access to the encryption key in order to decryptthe sensitive response data.

12 Development Environment SetupCheck your Java Version – currently it is Java 1.5.

The development environment can be setup having a reference to the following JAR files.

1. EFTUserExit.jar

This is the main JAR file that contains all the EFT User Exit related classes and the only JAR file that isrequired for EFT User Exit development. All others are optional.

2. te_clientsrvr.jar

This JAR file contains all POS related files. If you are using any SAP Transactionware Enterprise con-stants classes, they would be available in this JAR file.

3. tef.jar

This JAR file contains all core TEF framework TEF related classes.

4. tef_logging.jar

This JAR file would be used if using SAP Transactionware Enterprise logging.

5. VirtualEFT.jar

This JAR file contains Virtual EFT classes.

The Virtual EFT source code can be used as a reference when developing an EFT User Exit. EFT User Exit Ja-vaDocs can also be used to obtain help on EFT User Exit related classes.

SAP®



of 90

13 Virtual EFT AmountsFig. 12: The Virtual EFT Amounts and Expected Results

Sale - Get CardAmount from Amount to Card Comments

0 95.00 Visa Account # 4001000000000001

95.01 100.00 VisaExpired card, with account4002000000000000, Expiry of 0101

100.01 200.00 Mastercard Account # 5424180279791740200.01 300.00 Amex Account # 374245455400001300.01 400.00 Debit Account # 4551123456787790400.01 450.00 Manually entered with User Exit Callback450.01 500.00 Manually entered at POS

600.01 625.00 EC Cash Blacklist, Account # 5910000000000000001625.01 650.00 ELV Whitelist, Account # 5920000000000000001650.01 700.00 EC Floorlimit, Account # 5930000000000000001

700.01 800.00Not configured, unsuppported/canceled re-quest

800.01 900.00 EC Account # 5910000000000000001900.01 9999999.99 Visa Account # 4001000000000001

0 500 Giftcard When performing Gift Card requests

SAP®



of 90

Sale - Card@POSAmountfrom

Amountto Card Comments Receipt

0 50.00 VisaApproved with Signature Verifica-tion prompting

Merchant with Signature line &Customer

50.01 100.00 Visa Declined Customer100.01 150.00 Mastercard Approved Merchant with Signature line150.01 200.00 Mastercard Declined Customer

200.01 240.00 Amex ApprovedMerchant with Signature line &Customer

240.01 250.00 AmexApproved - Manual with SignatureVerificaiton prompting


250.01 300.00 Amex Declined Customer300.01 350.00 Debit Approved Customer350.01 360.00 Debit Declined Customer360.01 370.00 Debit Declined - Insufficient Funds Customer370.01 380.00 Debit Declined - Max Pin Entries Customer380.01 390.00 Debit Declined - Host no Response Customer

400.01 500.00 Credit card Manual card entry ApprovedMerchant with Signature line &Customer

500.01 600.00Request not supported, canceledby User Exit No receipt

600.01 625.00 EC Approved EC (in blacklist) Customer

625.01 650.00 EC Approved ELV (in whitelist)Merchant with Signature line &Customer

650.01 675.00 EC Approved ELV (below floor limit)Merchant with Signature line &Customer

675.01 700.00 EC Approved EC (above floor limit) Customer700.01 850.01 EC Declined Customer

850.01 860.00 EC Declined - printer requiredNo receipt if no printer is avail-able, Customer otherwise

860.01 870.00 EC Declined - Max Pin Entries Customer870.01 880.00 EC Declined - Insufficient Funds Customer880.01 895.00 EC Declined Customer895.01 900.00 EC Declined - card expired Customer

900.01 Max VisaApproved with Signature Verifica-tion prompting Merchant & Customer

SAP®



of 90

Purchase Correction (Void of a Sale)Amountfrom


0 25.00 Visa ApprovedMerchant with Signature line &Customer



225.01 250.00 Amex Declined Customer300.01 325.00 Debit Approved Customer325.01 350.00 Debit Declined Customer600.01 625.00 EC Approved EC Cash Customer

625.01 675.00 EC Approved ELVMerchant with Signature line &Customer

675.01 700.00 EC Approved EC Cash Customer

RefundAmountfrom



50.01 100.00 Visa Declined Customer

100.01 150.00 Mastercard ApprovedMerchant with Signature line &Customer

150.01 200.00 Mastercard Declined Customer


240.01 250.00 AmexApproved - Manual with SignatureVerificaiton prompting


250.01 300.00 Amex Declined Customer300.01 350.00 Debit Approved Customer350.01 360.00 Debit Declined Customer360.01 370.00 Debit Declined - Max Pin Entries Customer370.00 400.00 Debit Declined Customer


600.01 700 EC Approved - EC Cash Customer700.01 Max Visa Approved No Signature

SAP®



of 90

Refund Correction (Void of a Refund)Amountfrom





225.01 250.00 Amex Declined Customer300.01 325.00 Debit Approved Customer325.01 350.00 Debit Declined Customer600.01 625.00 EC Approved ECCash Customer

625.01 675.00 EC Approved ELVMerchant with Signature line &Customer

675.01 700.00 EC Approved EC Cash Customer

Sale - Card@EFTAmountfrom


0 50.00 VisaApproved with Signature Verificationprompting

Merchant with Signatureline & Customer

50.01 60.00 VisaApproved - Manual with Signature Verifi-caiton prompting


60.01 70.00 VisaApproved - Signature Verification by POSclient

Merchant with Signatureline

70.01 75.00 VisaTimeout - POS Business Logic performsManual Authorization processing


75.01 80.00 Visa



80.01 90.00 Visa Declined - Printer reqCustomer (if printer isavailable)


100.01 150.00 Mastercard ApprovedMerchant with Signatureline & Customer


200.01 250.00 Amex ApprovedMerchant with Signatureline & Customer

250.01 300.00 Amex Declined Customer300.01 350.00 Debit Approved Customer

350.01 360.00 Debit Declined - Printer reqCustomer (if printer isavailable)

360.01 370.00 Debit Declined - Insufficient Funds Customer370.01 380.00 Debit Declined - Max Pin Entries Customer380.01 400.00 Debit Declined - generic Customer

500.01 600.00Request not supported, canceled by UserExit No receipt

SAP®



of 90

600.01 900.00 Debit Approved Customer

900.01 Max VisaApproved with Signature Verificationprompting


RefundAmountfrom






60.01 70.00 VisaApproved - Signature Verification by POSclient

Merchant with Signatureline

70.01 75.00 VisaTimeout - POS Business Logic performsManual Authorization processing


75.01 80.00 Visa



80.01 90.00 Visa Declined - Printer reqCustomer (if printer isavailable)


100.01 150.00 Mastercard ApprovedMerchant with Signatureline & Customer


200.01 250.00 Amex ApprovedMerchant with Signatureline & Customer



360.01 370.00 Debit Declined - Max Pin Entries Customer370.00 400.00 Debit Declined - generic Customer

400.01 600.00Request not supported, canceled by UserExit No receipt

600.01 max Visa ApprovedMerchant with Signatureline & Customer

SAP®



of 90

Sale - Credit / DebitAmountfrom





100.01 150.00 Mastercard ApprovedMerchant with Signature line &Customer



240.01 250.00 AmexApproved - Manual with Signature Veri-fication prompting



350.01 360.00 Debit Declined - Printer req Customer (if printer is available)360.01 370.00 Debit Declined - Max Pin Entries Customer370.01 380.00 Debit Declined - Insufficient Funds Customer390.01 400.00 Debit Canceled at PinPad None


500.01 600.00Request not supported, canceled byUser Exit No receipt

600.01 700.00 EC Approved Customer

625.01 675.00 ECELV - Approved with Signature Verifi-cation prompting


700.01 Max Debit Declined Customer

700.01 Max VisaApproved with Signature Verificationprompting


RefundAmountfrom


0 50.00 Visa ApprovedMerchant with Signature line& Customer


Merchant with Signature line& Customer

60.01 70.00 VisaApproved - Signature Verification byPOS client

Merchant with Signature line& Customer

70.01 75.00 VisaTimeout - POS Business Logic performsManual Authorization processing Dependent upon processing

75.01 80.00 Visa


Dependent upon processing

80.01 90.00 Visa Declined - Printer req Customer if printer available90.01 100.00 Visa Declined Customer

100.01 150.00 Mastercard ApprovedMerchant with Signature line& Customer


SAP®



of 90

200.01 250.00 Amex ApprovedMerchant with Signature line& Customer


350.01 360.00 Debit Declined - Printer req Customer if printer available360.01 370.00 Debit Declined - Max Pin Entries Customer370.00 400.00 Debit Declined - generic Customer400.01 Max Approved Customer

625.01 675.00 EC ELV ApprovedMerchant with Signature line& Customer

700.01 max Visa ApprovedMerchant with Signature line& Customer

Payin / Payout (Banking)Amountfrom


0.01 350.00 Debit Approved Customer


360.01 370.00 Debit Declined - Max Pin Entries Customer370.01 380.00 Debit Declined - Insufficient Funds Customer390.01 400.00 Debit Canceled at PinPad None400.01 Max Request not supported, canceled by User Exit None

SAP Enterprise POS EFT User Exit Technical Reference

Documents

Transcript of SAP Enterprise POS EFT User Exit Technical Reference