payment manager manual – v2.1 - wordpress.com manager is a payment management solution which has...

Payment Manager Manual

Revision History Ver. Author Date Comments

2.1 JS Oct 2014 - Amended screenshot images to improve PDF conversion - New field added to Waiter message response

2.0 JS & ND Jun 2014

- Added Introduction of POS Routing, Legacy Mode and process flows from draft interface integration guide

- Updated terminal flow diagram - Rearranged the document - Added details on Waiter, Getvat and Closebill requests - Updated Terminal Loop - Changed order of sections - Terminal configuration amendments - Revised Waiter Record section - Correct successful CANCELBILL response added

1.1 JS April 2014 - Amendments made after first review

1.0 JS Jan 2014 - First edition of the manual

Payment Manager Manual – V2.1– 15th October 2014 2

Introduction The purpose of this document is to provide merchants and integrators with a full understanding of how to install, configure and integrate to VeriFone’s PAYware Ocius Payment Manager Service.

Payment Manager is a payment management solution which has been developed to provide bill lodging functionality, along with electronic funds transfer (EFT) payment processing, for use in the hospitality and retail industry.

Integrators must refer to the PAYware Ocius Manual or the VX Evolution Implementation Guide when integrating to this service. If a copy of either manual is required, please contact your VeriFone sales account manager.


Table of Contents Revision History .............................................................................................................................. 2

Introduction ..................................................................................................................................... 3

Solution Overview ........................................................................................................................... 7

Messages ....................................................................................................................................... 7

Terminals .................................................................................................................................... 7

Bill Manager Legacy Mode .............................................................................................................. 8

Payment Manager Vs Bill Manager ................................................................................................. 8

Socket Connection ...................................................................................................................... 8

Text Connection .......................................................................................................................... 8

Messages & Structures ............................................................................................................... 8

POS-Terminal Pairing.................................................................................................................. 9

Process Flow ................................................................................................................................ 10

POS System ................................................................................................................................. 11

Socket Connection ........................................................................................................................ 11

Text Connection ............................................................................................................................ 11

POS Routing ................................................................................................................................. 12

System Requirements ................................................................................................................... 14

Minimum requirements.................................................................................................................. 14

Optimum requirements.................................................................................................................. 14

Terminal Configuration .................................................................................................................. 15

Installation..................................................................................................................................... 16

Payment Manager UI .................................................................................................................... 19

POS .............................................................................................................................................. 20

Editing the POS ......................................................................................................................... 22

POS Connection ........................................................................................................................ 23

Payments ...................................................................................................................................... 24

Settings ......................................................................................................................................... 25

Logs .............................................................................................................................................. 27

VeriFone Support Application .................................................................................................... 27

Terminals ...................................................................................................................................... 29

Version Number ............................................................................................................................ 30


POS to Payment Manager Messages ........................................................................................... 31

B Record (Bill Record) .................................................................................................................. 31

B Record Examples ................................................................................................................... 32

B Record (Socket) Flow ............................................................................................................. 33

B Record (Text) Flow................................................................................................................. 34

T Record (Transaction Record) ..................................................................................................... 35

T Record Examples ................................................................................................................... 36

T Record (Socket) Flow ............................................................................................................. 37

P Record (Print Bill Record) .......................................................................................................... 38

P Record Examples ................................................................................................................... 38

S Record (Show Message Record) ............................................................................................... 39

S Record Examples ................................................................................................................... 39

P/S Record Flow ....................................................................................................................... 39

BILLINFO Record ......................................................................................................................... 40

BILLINFO Examples .................................................................................................................. 40

BILLINFO Flow .......................................................................................................................... 40

CANCELBILL Record ................................................................................................................... 41

CANCELBILL Examples ............................................................................................................ 41

CANCELBILL (Legacy Mode) Flow ........................................................................................... 41

CANCELBILL Flow .................................................................................................................... 42

O Record (Logout Record) ............................................................................................................ 43

O Record Examples .................................................................................................................. 43

L2 Record (Logon Record) ............................................................................................................ 44

L2 Record Examples ................................................................................................................. 45

UPDAPP ....................................................................................................................................... 46

UPDAPP Examples ................................................................................................................... 46

REQINFO Record ......................................................................................................................... 46

REQINFO Examples ................................................................................................................. 46

REQINFO/UPDAPP/L2/O Record Flow ..................................................................................... 47

SHUTDOWN ................................................................................................................................. 47

Payment Manager to POS Messages ........................................................................................... 48

CLOSEBILL Record ...................................................................................................................... 48

GETVAT Record ........................................................................................................................... 49

WAITER Record ........................................................................................................................... 50


POS Responses ........................................................................................................................... 51

Invalid Length/Message Response ............................................................................................... 52

Terminate Loop ............................................................................................................................. 53

APPENDIX.................................................................................................................................... 54

Terminal Screens .......................................................................................................................... 54

Process Flow ................................................................................................................................ 56

Terminal Flow ............................................................................................................................... 57

VeriFone Error Codes ................................................................................................................... 58

Contact Details ............................................................................................................................. 67


Solution Overview Payment Manager has been developed as a solution to effectively manage payment lodging between terminals and Point-of-Sale (POS) systems in the hospitality and retail industries. In an environment such as a restaurant, where multiple terminals are shared by a POS, Payment Manager enables the POS to lodge payments and allows terminals to request the closure of a sale without having to return to the POS. After payments have been lodged and placed into the system for processing, they can be picked up and paid at tables by waiting staff with their terminals. Payment Manager supports part payment on lodged bills as well as direct EFT payments. Payment Manager enables users to send bill information from the POS for printing on the terminal printer, to cancel lodged bills, and to close and save bills. The solution consists of the following three components:

• Payment Manager Service • Payment Manager UI (User Interface) application • Terminals supported – Vx 670 and VX 680 terminal range

The Payment Manager Service is used to process the bills lodged by the POS systems, while the Payment Manager UI application enables configuration of the POS systems and administration of the bills lodged.

Messages When integrating to the solution, the following message records must be used for the relevant request (please refer to the ‘POS to Manager Messages’ section):

• B Record – used to lodge a bill • T Record – used to both lodge and then pay a bill • P Record – used to send a message to be printed on the bill by the terminal • S Record – used to display a message on a terminal

Terminals The Vx 670 and VX 680 terminals can be connected to Payment Manager through sockets. Payment Manager can accept the following requests from the terminal:

• GETBILL – the request sent to retrieve the bill from Payment Manager. • PRINTBILL – the request sent to print an itemised bill. • GETPRINTBILL – the request sent to get and print the bill collectively, rather than sending

the requests separately. • BILLLIST – the request used to retrieve a list of all available bills from Payment Manager.


When the following requests are sent from the terminal, Payment Manager will communicate with the POS to complete the request. Depending on the type of request, the following actions will be processed by Payment Manager and displayed on the terminal:

• CLOSEBILL – the request sent by the terminal to close a table. On receiving this, the POS will generate a bill.

• GETVAT - the request used to retrieve a VAT receipt to be printed. • RESULT – the result of the transaction. • WAITER – the waiter validation request.

For more details on any of the message records above, please refer to the ‘Payment Manager to POS Messages’ section within this guide.

Bill Manager Legacy Mode The Payment Manager UI application provides existing Bill Manager customers with the option to process messages similar to Bill Manager, which allows the POS to keep the socket connection alive until it sends a result back.

The legacy mode can be enabled or disabled within the UI settings section of Payment Manager.

Please refer to the Payment Manager UI section within this manual for more details.

Payment Manager Vs Bill Manager Both solutions support socket and text integration but while Bill Manager uses a persistent socket model, Payment Manager uses a ‘make-and-break’ socket model. See below for more details:

Socket Connection Bill Manager’s socket model keeps the socket open at all times between a request and a response. If the connection is broken then the bill information will be lost and the bill will have to be re-lodged. This can cause issues if a bill has been part-paid and the connection is lost.

Payment Manager uses a ‘make-and-break’ socket model where the solution is not required to keep the socket open at all times. Instead, the model allows the bill to be regularly updated and retained, so the bill can be lodged and picked up again even if the connection is lost.

Text Connection Payment Manager has temporary outputs and final outputs with the extensions .temp and .out, whereas all outputs in Bill Manager have the same extension.

Messages & Structures Both solutions support the POS integration messages B, P, S, CANCELBILL and BILLINFO. However, Payment Manager also supports O, L2, REQINFO and SHUTDOWN messages. It uses the new Result message to send the outcome back to the POS.


POS-Terminal Pairing

Both Bill Manager and Payment Manager support single POS to multiple terminals routing via text integration.

The Payment Manager solution also includes new added features including:

• CLOSEBILL functionality - which allows a request to be sent to close a table/sale so the payment can be generated.

• GETVAT functionality - which allows users to request a VAT receipt be printed • WAITER ID functionality - which requires a waiter to enter their ID for validation


Process Flow The below diagram illustrates a high-level transaction flow using Payment Manager:

1. The POS lodges a bill with Payment Manager using the PAYware Ocius Bill Record via a socket connection or text integration. The Payment Manager immediately responds with a success or failure. In the case of socket integration, the socket can be closed at this point.

2. Terminal sends a Get Bill request to Payment Manager, specifying which bill to be returned.

3. Payment Manager extracts the bill a. The bill is returned to the terminal b. The bill is processed by the terminal using the VeriFone Gateway service and the

result is returned to Payment Manager 4. Payment Manager then re-establishes the communication with the POS on the port

25000 to send the result.

The POS will close the socket connection after the result is returned.

If using a Get/Print Bill request from the terminal, the payment receipt for the bill will be printed along with any information supplied when the bill was lodged by the POS. This could include an itemised list of what was purchased.

Terminal

Point Of Sale (POS)

3a

4

2

1

3b

VeriFone Server

Acquirer

Internet


POS System The POS system is responsible for accepting the requests from Payment Manager and lodging bills. There are two methods available to POS systems which allow them to integrate to Payment Manager. The sections below will detail the different methods and record formats available.

Socket Connection It is possible to connect to Payment Manager on port 29000 by default, referred to as the ‘Entrypoint’ port in the UI Settings panel, but this port number is configurable.

Integrators will be required to set up a socket listener on the POS in order to listen for the messages. This will be set to 25000 by default. For guidance, the default port numbers below are available but these are configurable:

Port Number Name Description 25000 RESULT The result of the transaction 29030 WAITER The request for waiter validation 29020 GETVAT The request to retrieve a VAT receipt 29010 CLOSEBILL The request sent to close a table and generate a bill

All integration commands can be sent through Payment Manager using POS routing to forward the messages onto the terminals.

Text Connection Text connection allows a single POS to communicate with multiple terminals, whereas socket connection allows one POS to communicate with one terminal by default. However, a POS can communicate with multiple terminals through socket connection by specifying a terminal IP address explicitly in the integration messages.

When using text connection, users are able to move text files (containing wildcard details1) into a shared file directory on the system running Payment Manager. The file directory will be monitored by Payment Manager for the text files and when they are received, the file data will be processed and a response will be sent as a message.

By default, the text files received by the directory will have the extension ‘.in’, the intermediate or temporary response will have the extension ‘.TEMP’, which is not available in Bill Manager, and the output response will have the extension ‘.OUT’.

1 See the following POS Routing section for more information on wildcards

Please note: Although Payment Manager supports multiple ports; it is possible to configure one port for the above messages being sent to the POS.


The file path, file name prefix and extensions (except for ‘.TEMP’) will be configurable through the Payment Manager User Interface (UI). If text files are being used to communicate, ‘TextMode’ should be enabled and the ‘TextPath’ correctly set. By default, the text file path will be the C:\ drive.

POS Routing POS routing enables Payment Manager to route integration messages from the POS to the relevant terminals. Text connection and the use of wildcards are used when a POS is required to connect to multiple terminals in a hospitality or retail environment.

It is possible to configure the POS routing in the POS section of the Payment Manager UI. The below table outlines the available POS routing fields:

Field Description IP Address The IP address assigned to the POS. The Payment Manager server uses

this to identify the POS and route those transactions to the correct terminal E.g. ‘192.168.0.1’

Description The reference or name that can be assigned to a POS E.g. ‘Till 1’

PED IP Address The IP address of the terminal to send the payment to E.g. ‘192.168.1.1’

Port number The port number on which the POS listens for result messages Wildcard (Only available if text connection is selected) The initial characters of the text

file which will be used to indicate which terminal the POS will communicate with

When adding a new POS in Payment Manager, if ‘text’ is selected as the POS type, then a wildcard will need to be entered. The wildcard can be used to indicate which terminal that Payment Manager will send the files to.

There are no formatting limitations to the wildcard, which can contain alpha and numeric characters, but the file name will be limited to a maximum of 256 characters.

After these details have been added, they will be stored in the configuration settings of Payment Manager and will enable the solution to determine which POS is associated with which terminal.

Please note: Both socket and text connection will use the same integration messages and structures.

Please note: In Bill Manager, it was necessary to configure the text file with an asterisk (*) to indicate it was a wildcard, e.g. B0001*, ABC01*, 123* etc. However, with Payment Manager, the asterisk is not required. For example, the wildcard can be B0001, ABC01, 123 etc.


The below diagram illustrates the use of wildcards via text connection:

1. If the user needs to lodge a bill at Wildcard B terminal, then the POS will send the B record in a file named B0001.in text file into the configured shared directory location along with Payment Manager.

2. Payment Manager, which monitors the directory for new text files, processes the file data and sends the resulting B0001.out message to the POS, after processing the message with the terminal assigned to wildcard B.

Wildcard A

A0001.in Wildcard B

B0001.in

Wildcard C

C0001.in


System Requirements In order for the POS to process transactions and communicate with Payment Manager, it requires outbound connections to the entry point (port numbers 29000, 29001 and 29050) and inbound connections on the TCP/IP ports below:

• 29010 - CLOSEBILL • 29020 - VAT • 29030 - WAITER VALIDATION • 25000 - RESULT

All of the port numbers are set by default and all, except for the UI port number, can be configured in the Payment Manager Settings section.

When installing Payment Manager, VeriFone recommends the following minimum requirements are met:

Minimum requirements • Microsoft Windows XP Service Pack 2 or higher • .NET Framework 4.0 • Intel Pentium IV 800MHz or above • 512MB available RAM • 250MB hard disk space • DirectX 9 capable graphics adapter

Optimum requirements • Microsoft Windows 7 • Intel Core 2 Duo or above

Please note: Payment Manager is developed using the latest .Net development technologies. As Microsoft no longer supports Windows 98, XP or NT, VeriFone does not recommend their use.


Terminal Configuration In order to communicate with the Payment Manager Server, the terminals in use will need to be configured accordingly. For the VX 680, please follow the steps below to perform this:

1. Switch the terminal off and on again, and press the ‘SETUP’ on the touchscreen. (For the Vx 670, turn off and on again before pressing F4 when presented with the ‘Press Enter to Start Communication’ screen).

2. Enter the Setup PIN ‘2580’ and press ‘Enter’ (green key) to continue.

3. Press ‘1’ to enter the ‘Network Settings’ section.

4. Press ‘2’ for ‘Payment Manager’ or ‘Bill Manager’.

5. Press ’1’ and Enter the IP Address of the machine on which Payment Manager is located.

6. Press ‘Enter’ to confirm the setting and continue.

7. Press ‘2’ and confirm that the port setting matches the port number of the Payment Manager server. By default, this will be configured to ‘29000’ and it is not recommended that this is changed unless necessary.

8. Open WebCom (VeriFone’s web-based estate management tool) and go to the Terminal

Config section in the TMS component.

9. Find the variable displayed as ‘This variable is used to enable or disable the Payment Manager on the terminal. When enabled, this will replace Bill Manager.’ Select ‘Enabled’ to complete the configuration.

10. Once the server settings have been entered correctly, use ‘Cancel’ (red button) to return to the ‘Press Enter to Start Communication’ screen; at which point the operator should login as normal.

Please note: For more information about using WebCom please refer to the WebCom manual or contact your VeriFone Account Manager.

Please note: To insert a ‘.’ (full-stop) on the VX 680, press ‘*’ star key. On the Vx 670, use the ‘Clear’ (yellow key) to delete characters and press ‘1’ and then the ‘ALPHA’ key twice to insert a ‘.’ (full-stop).


Installation To install Payment Manager, download the setup file provided and follow the setup wizard instructions below:

1. Begin by initiating the ‘setup.exe’ file within the Payment Manager directory. Once the setup wizard has started, click ‘Next’ to continue:

2. The Payment Manager Setup wizard will display the default folder location to save the application. Select ‘Browse’ to choose a suitable folder location to save the installed service.

Please note: The images are only for illustrative purposes.


By selecting ‘Disk Cost’, the user is able to view the available drives, the disk size, the available space and amount of space required by Payment Manager. Select ‘OK’ to close the window.

When the required folder has been chosen, select ‘Next’ to continue.

3. A ‘Confirm Installation’ window will appear. Select ‘Next’ again to confirm and start the installation:


To amend previous settings, select ‘Back’ or ‘Cancel’ to exit the wizard and cancel the installation.

4. The wizard will begin installation:

5. When the installation is complete, click ‘Close’ to exit the wizard:

6. After closing the installation wizard, the Payment Manager Service will start automatically.

To initiate the Payment Manager User Interface (UI), either navigate to the folder the application was saved in and double click ‘PaymentManagerUI.exe’ or double click on the Payment Manager shortcut icon (displayed below) which will appear on the desktop after the installation:

Please note: Please ensure the Payment Manager Service application is running prior to initiating the Payment Manager UI.


Payment Manager UI The Payment Manager UI enables users the ability to configure or monitor the following five components of the application:

• POS • Payments • Settings • Logs • Terminals

• •

Please note: If the Payment Manager Service is manually restarted then the Payment Manager UI must also be restarted to preserve all of the auto-refresh features.


POS As part of the initial setup, users will be required to create new POS systems which will be registered to the Payment Manager. For example, in a restaurant environment there might be two or more waiter POS systems, a kitchen POS and a manager POS.

When Payment Manager is loaded to setup a new POS system, the user must select the drop-down option next to the POS component.

1. Click on the blue vertical toolbar to the side of the POS component icon and then select ‘Add new POS’, as shown in the picture below:

2. The ‘Add POS’ settings will appear. At this stage, it is possible to select the POS connection type, either Socket or Text:

Please note: Only POS systems registered to the Payment Manager will be able to lodge bills. All other POS systems not connected/registered will be rejected.


a) Socket – if selected, the user will be required to enter the following details:

• IP Address (The IP address of the POS) • Description (A name or description to designate which POS it is) • Terminal IP Address (The IP address of the terminal) • Port number (The port number on the POS to send transaction result messages to)

b) Text – if selected, the user will be required to enter the following details:

• Wildcard (An initial character to designate which terminal the POS will communicate with) • Description (A name or description to designate which POS it is) • Terminal IP Address (The IP address of the terminal)

3. Select and fill in the details for each field to progress with the POS setup process and select

‘Add’.

4. The new POS will appear on the Payment Manager screen along with a message reading ‘POS added successfully’, as illustrated below:

5. If necessary, repeat the process to add multiple POS systems that will be registered to the Payment Manager.


Editing the POS

To edit a POS configuration, select the icon located next to the name of the system you want to edit and a new panel will open. See image below for more details:

The POS panel will display all the POS systems linked to the Payment Manager. Select a POS located on the left of the panel (e.g. Manager POS) to display the POS settings (as illustrated above). To delete a POS connection, click on the ‘red cross’.

By clicking ‘Edit’ the user is able to alter the POS Name, IP Address, Port Number and Terminal IP. To keep any changes, select ‘Save’ and an ‘Update successful!’ message will appear.

To discard any changes select ‘Cancel’.


POS Connection

Once setup, the POS systems registered to the Payment Manager will appear on the main screen, as shown in the image below:

The connection status of each POS system is shown by the colour of the circular indicator to the right of each POS.

The POS connection status is indicated as follows:

Indicator colour Appearance Description

Grey

Grey indicates that the POS is disconnected

Orange

Orange indicates that the POS is idle but connected to Payment Manager

Green

Green (flashing) indicates that the POS is communicating with Payment Manager.

Please note: The indicator will only flash green three times while the POS communicates with Payment Manger or when a bill is being lodged. Afterwards it will revert back to orange if the POS is still connected or grey if it disconnects.


Payments The Payments component displays all the lodged bills available for payment. By clicking on each individual bill, Payment Manager will provide the following bill information:

• Reference – the table number or name • Bill Amount – the total bill amount for the table • Status – whether the bill is waiting, part-paid, processed (paid), cancelled, locked or

unlocked. • Lodged By – the IP address of the POS that lodged the bill • Processed By – the IP address of the terminal that processed the payment. •

Once a GETBILL request is sent from the terminal, the bill will be locked. In situations when a terminal goes offline during a GETBILL request, this will also lock the bill. To unlock the bill, click on the ‘Unlock’ button or press ‘Cancel’ on the terminal keypad.

If a bill is part-paid, then Payment Manager will display two figures. The top figure is the total bill amount and the lower figure is the outstanding amount to be paid.

Please note: Payment Manager has the ability to process more than 400 bills simultaneously.


Settings The Settings component enables the user to configure POS settings (e.g. IP addresses), Entry point settings (e.g. port numbers and the legacy mode) and modify the log path to which the logs are saved to:

For more details on each setting, please refer to the table below:

Setting Name Type Description Close Bill IP IP Address The IP Address where all CLOSEBILL requests will be routed Close Bill Port Integer The port number on which all CLOSEBILL requests will be routed to for

socket connection Close Bill Path String The file path on the machine running the service where all CLOSEBILL

requests will be routed Close Bill Extn String The extension to use for file based CLOSEBILL requests Prefix String The prefix to use for file based CLOSEBILL requests Waiter Val IP IP Address The IP Address where all WAITER validation requests will be routed Waiter Val Port Integer The port number on which all the WAITER validation requests will be

routed Waiter Val Path String The file path on the machine running the service where all WAITER

validation requests will be routed Waiter Val Extn String The extension to use for file based WAITER validation requests Prefix String The prefix to use for file based WAITER validation requests Vat Port Integer The port number on which all GETVAT requests will be routed Vat Extn String The file path on the machine running the service where all GETVAT

requests will be routed Port number Integer The port number on which the payment manager service runs

Please note: The text boxes in the Settings panel are not case sensitive, allowing the file paths and extensions to can be entered in upper or lower case characters.


Enable Legacy Mode Tick to allow Payment Manager to behave like the legacy solution (Bill Manager)

Input file path String The file path on which the payment manager service listens to POS and TERMINAL requests

Input file prefix String The prefix to use for input files from POS Input Extn String The extension to use for input files from POS Output Extn String The extension to use for output files from POS Log Path String The file path to where the Payment Manager service logs will be

written to The Entrypoint port number (29000) can also be changed, see System Requirements for details of the default port number settings.

The user can also communicate with Payment Manager using the Input file path by entering the file and Input file prefix in the relevant drive.

After updating the settings, click ‘Save’ and the message ‘Applying new settings… Please Wait!’ will appear. The service will restart automatically with the new changes included.

To discard any changes select ‘Cancel’.

Please note: If users enter an invalid file path then it will not be validated by Payment Manager at the point of entering.


Logs The Logs component will enable users to view the history of all bill lodges and terminal transactions by logging all messages coming in and going out; either from a POS to a terminal or from a terminal to a POS.

To view incoming and outgoing transactions and bills, click ‘Start’ and the messages will appear in the box below.

To stop the logs appearing click ‘Stop’ and to clear the transaction logs click ‘Clear’. Data will be saved to a file which is viewable on the Support Application. For more details, see the VeriFone Support Application section.

The destination of the logs can be altered in the ‘Log Path’ section of the Settings component.

VeriFone Support Application The VeriFone support application enables users the ability to view logs generated by Payment Manager. It is not necessary for merchants to use the VeriFone support application; users may use their own logging application.

In order to view Payment Manager logs, the Support Application needs to be installed.

To open the application, double click the Support Application icon on your desktop:


Alternatively, launch the application located in your local directory, for example: ‘C:\ProgramFiles\Verifone\Support Application\ Support Application.exe’ or .salf file.

A password prompt box will then appear as shown below:

There is no default password required when logging in for the first time, the password box should be left blank before clicking ‘Ok’ to login. Use the ‘Open’ drop down menu and locate the file to be viewed.

When amending the log files, it is necessary to edit the field value and select the row below it before exiting the application. This registers the change that has been made and the user will be prompted to save changes before closing. If the prompt to save changes is displayed on the screen, it should be assumed that any changes made were not saved and will need to be reapplied to the settings file.

Please note: The Support Application password should be changed at the earliest opportunity by navigating to “File > Settings” when the application is first initiated. The user will need to click the ‘UpdatePassword’ box before entering and confirming a new password.


Terminals This component will show all of the terminals which are currently communicating with the Payment Manager.

Each terminal will be displayed on the screen when this component is opened, displaying the following information:

• The terminal IP address (e.g. 10.85.9.66) • The table reference (e.g. A1) • The waiter ID (e.g. 369) • The current action or status of the terminal (e.g. Get Bill)

Each terminal will appear once, displaying the given action or status of the terminal at that time.

Please note: The data shown on the terminals component is not configurable.


Version Number It is possible to find out the version of the installed Payment Manger by clicking on the Payment Manager logo in the top right corner of the UI.

After selecting the logo, a new panel will open which will display an ‘About’ section in which the Payment Manager software version will be displayed e.g. “Payment Manager v1.X.X.X”.

The ‘Contact’ section will provide the VeriFone UK address and telephone number. For contact information on specific departments, see the Contact Details section at the back of the document.


POS to Payment Manager Messages The main records to be sent from the POS to Payment Manager include B, P, S and T records. The tables below provide details of what these are used for and examples of record formats.

B Record (Bill Record) Bill Lodging is achieved with the use of a B record. When sending a B record, it lodges a bill and allows a transaction to be placed into Payment Manager for processing and then picked up by any terminal connected to the system. The format of which is detailed as follows:

Field Name Type Description 1 Record Type String

Mandatory ‘B’ – indicates a Bill record

2 Account Number Decimal Optional

Defines merchant parameter, set to use

3 Transaction Type Integer Mandatory

‘01’ – Purchase ‘02’ – Refund

4 Modifier Integer Mandatory

‘0000’ – No special handling ‘0004’ – Online ‘0008’ – CNP ‘0200’ – Ecommerce

5 Track1 Reserved, leave empty 6 PAN/Track2 Reserved, leave empty 7 Cardholder Verification Value (CVV) Reserved, leave empty 8 Expiry MMYY Reserved, leave empty 9 Issue Number Reserved, leave empty

10 Start MMYY Reserved, leave empty 11 Transaction Value Decimal

Mandatory Total value of the transaction including tax applies to Purchase, Refund, Cheque Guarantee, Cash Advance and Purchase with Cashback. In the case of Purchase with Cashback transactions this field should only contain the values of the goods or services provided. Provision of the decimal point is recommended although optional. For example: 1.23 = £1.23 123 = £123.00, 000001.2389 = £1.23 Values should always be positive. Values will be truncated to the correct number of decimal places required for the transaction currency. For example: 1.23 = 1¥ (one Japanese Yen) (0 decimal places)). Refer to notes on monetary values.

12 Cash Back Value Reserved, leave empty Disabled for Bill Lodging. The terminal will prompt for each payment.

13 Bank Account Number Reserved, leave empty


14 Sort Code Reserved, leave empty 15 Cheque Number Reserved, leave empty 16 Cheque Type Reserved, leave empty 17 Cardholder Name Reserved, leave empty 18 Cardholder Billing Address Reserved, leave empty 19 EFT Sequence Number Reserved, leave empty 20 Authorisation Source Reserved, leave empty 21 Authorisation Code Reserved, leave empty 22 Transaction Date & Time Reserved, leave empty 23 Merchant Reference Number / Invoice

Number String Optional

Reference numbers can be supplied up to a maximum length of 50 characters. However, when sent to the acquirer they are truncated to 25 characters

24 Terminal IP Address Decimal Optional

IP address of the terminal where the bill is to be sent for printing. If left blank, the print data will be sent to a terminal based upon the POS routing setup

25 Print Message String The text that is to be printed as a bill. Each line can be up to 21 characters long, and must be separated by a carriage return

26 User ID String Conditional

User ID which lodged the Bill. In conjunction with the UsePEDUserID option within Payment Manager, allows Bills to only be accessible by the User ID logged in

27 RequestTokenFlag Integer Optional

Indicates whether to raise token registration. 0 – Not Set 1 – Do Not Register 2 – Register 3 – Register Only

28 PromptVoucherFlag Integer Optional

Indicates whether to prompt for a voucher or not. The usage of this flag will be configurable. Can be ‘Y’ or ‘N’.

B Record Examples Request examples: 1. For socket-based POS: B,,01,0000,,,,,,,10.00000,0.00000,,,,,,,,,,,A1,, 2. For text-based POS: B,,01,0000,,,,,,,10.00000,0.00000,,,,,,,,,,,A1,,

Response Examples: (valid result) 0,1,10.00,0.00,0.00,492912*****23,1214,,,20140507122447,9123456,20420001,Visa Debit,0.00,2903,789DE,,SIGNATURE VERIFIED,1234 (2nd message from the same socket) -26,1,,,,,,,,,,,,,,,,Invalid Channel (any error) -98,1,,,,,,,,,,,,,,,,ERROR PROCESSING BILL (unknown sender) -98,1,,,,,,,,,,,,,,,,UNKNOWN_CLIENT


(duplicate reference) -80,1,,,,,,,,,,,,,,,,BILL REFERENCE ALREADY EXISTS (shutting down) 99,1,,,,,,,,,,,,,,,,BILL CANCELLED – PAYMENT MANAGER SHUTTING DOWN

B Record (Socket) Flow

The diagram below shows the steps involved in a B record being sent via socket connection:

1. POS sends integration message on socket 29000 to Payment Manager. 2. Payment Manager sends a response back to the POS - this can be complete or

intermediate which can be identified by the terminate loop field. Please refer to the POS Responses section within the Integration Message section of this document for more details.

3. The POS should close the socket at this point. 4. Payment Manager sends the transaction response on port 25000 to the POS. This can be

full payment or part-paid payment response, which can be identified by the terminate loop field.

PORT 25000


B Record (Text) Flow

The diagram below shows the steps involved in a B record being sent via text connection:

1. POS sends integration message to Payment Manager. 2. Payment Manager sends a response back to the POS - this can be complete or

intermediate which can be identified by the terminate loop field. Please refer to POS Responses within the Integration Message section of the document.

3. Payment Manager sends the transaction response to the POS. This can be a full payment or a part-paid payment response. This can be identified by the terminate loop field.

Please note: Intermediate and .TEMP responses will occur in Payment Manager but not in Bill Manager legacy mode.


T Record (Transaction Record) The T record can be used to both lodge and pay the bill. For example, if the POS sends a B record with a T record, then the bill will be lodged and the transaction will immediately be sent to the associated terminal IP address.

It is followed by the resultant output response generated after the transaction record has been processed. The appropriate version of the response message will be automatically selected by the terminal depending upon the information included with the transaction request.

The transaction request message must conform to the below message format:

Field Name Type Description

1 Message Type String Mandatory

‘T’ – indicates a transaction record

2 Account Number This field is no longer used. Field 24, Account ID, is used to define the merchant parameter set to use

3 Transaction Type Integer Mandatory

‘01’ – Purchase ‘02’ – Refund ‘07’ – Account Check

4 Modifier Integer Mandatory

The modifier meanings have been updated to account for the different types of CNP transactions: ‘0000’ – Cardholder Present ‘0002’ – Offline (Capture) ‘0004’ – Online ‘0008’ – CNP – Mail Order ‘0010’ – Authorisation Only ‘0020’ – Continuous Authority ‘0200’ – Electronic Commerce ‘1000’ – CNP – Telephone Order ‘2000’ – CNP – Account On File

5 POS Routing / Bill ID Reserved, leave empty 6 PAN / Track 2 Reserved, leave empty 7 CSC Reserved, leave empty

8 Expiry Date Reserved, leave empty 9 Issue No Reserved, leave empty 10 Start Date Reserved, leave empty 11 Txn Value Decimal

Mandatory Total value of the transaction including tax applies to: Purchase, Refund, Cheque Guarantee, Cash Advance and Purchase with Cash Back (PWCB). In the case of PWCB transactions, this field should only contain the values of the goods or services provided. Provision of the decimal point is recommended although optional. For example: 1.23 = £1.23 123=£123.00, 000001.2389 = £1.23. Values should always be positive, and will be truncated to the correct number of decimal places required for the currency. For example: 1.23 = 1¥ (one Japanese Yen) (0 decimal places).

12 Cash Back Value Decimal Conditional

Total Cash Back Value for Purchase with Cash Back transactions (PWCB). Values will be truncated (without rounding) to the number of decimal places required for the given currency. The value should always be


positive. If left blank, the terminal will prompt for cashback. If populated with a value, or zero value, the terminal will not prompt.

13 Bank Acc No Reserved, leave empty 14 Sort Code Reserved, leave empty 15 Cheque No Reserved, leave empty 16 Cheque Type Reserved, leave empty 17 Cardholder Name Reserved, leave empty 18 Cardholder Billing

Address Reserved, leave empty

19 EFTSN Reserved, leave empty 20 Auth Source Reserved, leave empty 21 Auth Code Reserved, leave empty 22 Txn Date Time Reserved, leave empty 23 Reference String

Optional Reference numbers can be supplied up to a maximum length of 50 characters. When sent to the acquirer these are truncated to 25 characters.

24 Account ID Decimal Optional

Defines merchant parameter set to be used.

25 Gratuity Decimal Conditional

Total gratuity value to be added to the transaction. Provision of the decimal point is recommended although optional. For example: 1.23 = £1.23 123=£123.00, 000001.2389 = £1.23 Values should always be positive, and will be truncated to the correct number of decimal places required for the currency. For example: 1.23 = 1¥ (one Japanese Yen) (0 decimal places)

26 NDI Value Decimal Conditional

Non Discounted Items value, showing the value of items which are not eligible for Freedom. This field is conditional, as it will only be populated if there are values meeting this criterion.

27 Register for Account On File

Integer Valid values are: Not Set = 0 Do Not Register = 1 Register = 2 Register Only = 3

28 Token ID Decimal ID assigned to the stored Account On File details

T Record Examples

Request Example: T,,01,0000,,,,,,,01.00,,,,,,,,,,,TEST,,,0,,,

Response Example:

(valid result) 0,1,10.00,0.00,0.00,492912*****23,1214,,,20140507122447,9123456,20420001,Visa Debit,0.00,2903,789DE,,SIGNATURE VERIFIED,1234 (2nd message from same socket) -26,1,,,,,,,,,,,,,,,,Invalid Channel (any error) -98,1,,,,,,,,,,,,,,,,ERROR PROCESSING BILL (unknown sender) -98,1,,,,,,,,,,,,,,,,UNKNOWN_CLIENT


T Record (Socket) Flow

The following diagram illustrates the flow of a typical T record transaction via socket connection:

POS sends a T record on port 29000 to Payment Manager (PM)

Intermediate response is sent back to the POS on port 25000 or on same socket (legacy mode) PM sends a bill to

the terminal

Terminal sends result back to PM

PM sends result to the POS on port 25000 or same socket (legacy mode)


P Record (Print Bill Record) A bill can be sent, via Payment Manager, directly to a specific terminal for printing without the need to lodge a bill record first. This is achieved using the P record format:

Field Name Type Description 1 Record Type

String Mandatory

‘P’ – indicates a Print Bill record

2 Terminal IP Decimal Optional

IP address of the terminal where the bill is to be sent for printing. If left blank, the print data will be sent to a terminal based upon the POS routing setup.

3 Print Message String Mandatory

The text that is to be printed as a bill. Each line can be up to 21 characters long, and must be separated by a carriage return. To allow either double width or double height font printing for a particular line; add a control character of “&fw;” (for double width) or “&fh;” (for double height) at the start of the line. Alternatively, to allow double height and width font printing then add “&fb;” at the start of the line.

Please note: The font will revert back to the original font size once that line is printed

In order to demonstrate a P Record format in use, the below example has been included for reference:

P,192.0.1.2,This is your bill Your total is &fb;£10.00

P Record Examples (success) 0,1,,,,,,,,,,,,,,,,P MESSAGE RECEIVED SUCCESSFULLY (failed) -98,1,,,,,,,,,,,,,,,,PRINT FAILED (invalid message) -98,1,,,,,,,,,,,,,,,,INVALID MESSAGE


S Record (Show Message Record) The S record can be used to show something on a specific terminal.


Mandatory ‘S’ – indicates a Show Message Record

2 Terminal IP Address String Mandatory

The IP address of the terminal to send the message to.

3 Print Message String Mandatory

The message to be shown

S Record Examples Request Example: S,10.85.9.66,DISPLAY TEXT Response Examples: (success) 0,1,,,,,,,,,,,,,,,,S MESSAGE RECEIVED SUCCESFULLY (failed) -98,1,,,,,,,,,,,,,,,,STATUS MESSAGE FAILED (timed out) -142,1,,,,,,,,,,,,,,,,S RECORD TIMED OUT

P/S Record Flow The flow diagram below shows how the P and S records are sent between the POS, Payment Manager and the terminal.

P/S record sent on PORT 29000 or .in file

Response on same socket or .out file

P/S (based on POS routing)


BILLINFO Record The BILLINFO record is used to get the information about the status of the bill. For example, part-paid or waiting to be paid.


String Mandatory

‘BILLINFO’ – indicates a request for bill information

2 Reference String Mandatory

The reference of the payment

BILLINFO Examples Request example: BILLINFO,A5

Response example:

(success) BILLINFO,1,True,10.85.9.66 (failed) -98,1,,,,,,,,,,,,,,,,BILLINFO failed

BILLINFO Flow The below flow shows the BILLINFO messages sent between a POS and Payment Manager using socket connection:

BILLINFO on PORT 29000 or .in file

BILLINFO response on same socket or .out file


CANCELBILL Record This record is used to cancel a bill. The process cannot be reversed once initiated.


String Mandatory

‘CANCELBILL’ – indicates a request to cancel a bill



CANCELBILL Examples

Request example: CANCELBILL,A5

Response example:

(Success) -99,1,0.00,0.00,0.00,,,,,,,,,,,,,PAYMENT CANCELLED SUCCESSFULLY,,,,A1 (Cannot cancel) -98,1,,,,,,,,,,,,,,,,BILL CANCEL FAILED (Being processed) -77,1,,,,,,,,,,,,,,,,Cancel Failed – In Payment on 10.85.9.66

CANCELBILL (Legacy Mode) Flow The following diagram illustrates a CANCELBILL request sent from the POS to Payment Manager (in legacy mode) via a socket or text connection:

POS sends B record on port 29000 or .in file

CANCELBILL request sent to PM – on same socket or .out file

PM sends a bill to the terminal

Terminal sends a GETBILL request to PM

If cancel is not possible as it is processing the bill, PM sends failure response to POS on same socket or .out file

If cancel is possible, PM sends success response to POS on same socket or .out file


CANCELBILL Flow The following diagram illustrates a CANCELBILL request sent from the POS to Payment Manager via a socket or text connection:

CANCELBILL request sent to PM on port 29000 or .in file

POS sends B record on port 29000 or .in file

PM sends success/failure response to POS on same socket or .out file

Intermediate response on port 25000 or .out file or same socket (legacy mode)


O Record (Logout Record) The O record allows the user to log off from the current process and perform additional functions as specified in the table below:

Field Name Type Description 1 O (Upper case) String

Mandatory ‘O’ – Indicates Logout Record

2 Function Integer Mandatory

‘0’ – Logout ‘1’ – Print Q Report and logout ‘2’ – Exit and logout* ‘3’ – Exit and logout with Q report* ‘4’ – Submit offline transactions, logout and shut down*

* - only for use with PAYware Ocius for PC

A final response is sent once the action has been processed, informing the operator of the outcome. Similarly to the login record, a ‘0’ record is received back to confirm a successful logout.

In situations when a processing error has occurred, a ‘-31’ will be returned or if attempting to logout when there is no user logged in, a ‘-85’ error message is received. See table within the Appendix for a full list of error codes.

O Record Examples Request example: O,0

Response examples:

(success) O,0 (failed) 98,1,,,,,,,,,,,,,,,,LOGOFF FAILED


L2 Record (Logon Record) An L2 record is used to login and stipulate which menu structures are enabled for the operator. A description of this record type can be seen in the table below:

Field Name Type Description 1 L2 (Upper Case) String

Mandatory ‘L2’ – Indicates an L2 format Login Record

2 UserID String Mandatory

User ID

3 PIN String Mandatory

User PIN

4 Menu Options String Conditional

See Menu list in table below

‘1’ – New Transaction [Not possible to restrict sub menus. This is controlled by Account Permissions] ‘2’ – Menu ‘1’ – Transaction Management ‘1’ – Reports ‘1’ – Terminal ‘1’ – Z Report ‘2’ – X Report ‘3’ – Txn Report ‘4’ – Q Report ‘5’ – Offline Transactions ‘6’ – Stored Offline Transactions ‘2’ – Account ‘1’ – Account Summary ‘2’ – Account Details ‘3’ – End of Day ‘3’ – Bank Report ‘4’ – Last Printed Report ‘2’ – Submit Offline Transactions ‘2’ – Reprint ‘3’ – System ‘1’ – Print Stored AID’s ‘2’ – System Info ‘3’ – Voucher Type ‘4’ – Change Setup PIN ‘5’ – Download ‘4’ – Ordering ‘1’ – Get Order List ‘2’ – Place Order ‘5’ – User Management ‘1’ – Add New User ‘2’ – Change User ID ‘3’ – Change User PIN ‘6’ – Terminal Management [options vary depending upon which terminal/software in use] ‘1’ – Power ‘2’ – Reboot Pinpad ‘3’ – Signal Strength ‘3’ – Bill Options ‘1’ – Close Bill on POS ‘2’ – Get Bill ‘3’ – Get/Print Bill ‘4’ – Print Bill ‘4’ – Logoff ‘5’ – Other


‘1’ – Nectar ‘2’ – E-Topup ‘3’ – Givex ‘4’ – MiVoucher

L2 Record Examples The menu allows the options available to be listed by placing all the required options in the fourth field of the record. For example, to include all the menus and their sub-menus (for a user with a Login ID and PIN of 1234):

L2,1234,1234,*

For more specific configurations, it is possible to only enable the operator access to the logout option. This would be achievable using the following record:

L2,1234,1234,4

By including a 4, none of the other options are accessible. Leaving the fourth field blank would specify that no options would be available at all, rendering the application completely controlled by records from the POS.

To control the sub-menus as well as a set of “{ }” must be included after the option is selected, and within the brackets list which sub-options are usable. An example would be where Select Bill is required, but only Print Bill to be available within the sub menu (option 4 of the four sub-options):

L2,1234,1234,3 {4} 4

As with the previous example, include {*} after the option for all sub-options to be available. By not including anything will only allow the top menu to be accessed. The only exception to this rule is the New Transaction option, which is controlled using the permissions setup on the account.

Response examples:

(success) L2,1234,1234 (failed) -98,1,,,,,,,,,,,,,,,,LOGON FAILED


UPDAPP The UPDAPP message can be used to request a check for updates from the terminals:


Mandatory ‘UPDAPP’ – indicates a request to check for updates

2 Terminal IP Address String Mandatory

The IP address of the terminal to send the update message to

UPDAPP Examples Request example: UPDAPP,10.85.6.45

Response example:

(success) UPDAPP, 10.85.6.45 (failed) -98,1,,,,,,,,,,,,,,,,FAILED

REQINFO Record The REQINFO record will request the information about a specific terminal:


REQINFO

String Mandatory

‘REQINFO’ – indicates a request for information about a specific terminal



REQINFO Examples

Request example: REQINFO,1

Response example:

(success) REQINFO,1 (failed) -98,1,,,,,,,,,,,,,,,,FAILED


REQINFO/UPDAPP/L2/O Record Flow

The flow diagram below shows how REQINFO, UPDAPP, L2 and O records are sent between the POS, Payment Manager and the terminal:

SHUTDOWN This will shut down the Payment Manager application:


SHUTDOWN

String Mandatory

‘SHUTDOWN’ – indicates a request to shut down Payment Manager

REQINFO, UPDAPP, L2 or O record sent on PORT 29000 or .in file

Response on same socket or .out file

REQINFO/UPDAPP/L2/O

Response


Payment Manager to POS Messages This section contains all the request formats that Payment Manger sends to the POS systems.

CLOSEBILL Record The CLOSEBILL request is sent from the terminal to the POS via Payment Manager to close a sale. At this point Payment Manager would close the connection.

When the POS receives the request, it generates a bill and sends a B record containing the terminal IP address and sends the bill to Payment Manager to send onto the applicable terminal. Alternatively, in case of text connection, a T record saved into the appropriate wildcard prefixed filenames can be used. Payment Manager would then send them to terminals based on the POS-PED routing.

Message Request:

Field Name Type Description 1 Record type

String Mandatory

‘CLOSEBILL’ – indicates a request to close a bill

2 PTID

String Mandatory

The terminal number

3 Reference

String Mandatory

The reference of the table

4 Waiter ID

String Mandatory

The ID of the waiter

5 Terminal IP

String Mandatory

The IP address of the terminal sending the response back

Close Bill record example: CLOSEBILL, 28459576,A48,1234,10.85.9.70 Sample socket response : B,,01,0000,,,,,,,10.00000,0.00000,,,,,,,,,,,A1,10.85.12.170, Sample text response saved to A0001.in : B,,01,0000,,,,,,,10.00000,0.00000,,,,,,,,,,,A1,, (Assuming ‘A’ maps to 10.85.12.170 in the POS-PED routing)


GETVAT Record The GETVAT record is used to generate a VAT receipt by sending a request from the terminal to the listening port on the POS via Payment Manager.

When the POS receives the request, the socket connection will be closed and a VAT receipt will be generated. The POS will send a P record to Payment Manager, specifying the terminal IP address of where the VAT receipt needs to be sent to. Once the terminal receives the VAT receipt, it is ready for printing on the terminal. For text connection, by default the file extension will be .vat, however this is configurable. Request Message:

Field Name Type Description 1 Record type

String Mandatory

‘GETVAT’ – indicates a request for a VAT receipt

2 PTID

String Mandatory

The terminal number

3 Waiter ID String Mandatory


4 Terminal IP String Mandatory

The IP address of the terminal sending the response

5

Bill ID Integer Conditional

The ID of the bill – mandatory if reference not present

6 Reference

Integer Mandatory

The bill reference

Example: GETVAT,28459576,1234,10.85.9.70,A48


WAITER Record The Waiter record is used to validate the terminal user processing the transaction. When a waiter record is sent from Payment Manager to the POS listening for waiter validation requests, the POS will respond back with a response of ‘VALID’ or ‘INVALID’. For socket communication, the POS needs to respond on the same channel. By default, Payment Manager will wait for 5 seconds for the response. After that time it will send a response back to the terminal confirming if the waiter was valid. This prevents waiter validations being blocked when there is an issue with the POS.

The Waiter validation prompt on the terminal (displayed as Employee ID) is optional and is performed when processing the following requests: Close bill, Get bill and Get/Print bill.

For text connection the file extension for waiter validation is ‘.wv’ by default, however this is configurable in the Payment Manager Settings panel. The POS will select ‘.wv’ files from the ‘Waiter Val Path’ directory, which is also configurable, and drop responses with an ‘.in’ extension at the same location. The name of these files will be in line with the POS routing table, e.g. If the wildcard for a terminal is ‘C’ then the waiter response to that terminal should be ‘Cx.in’ (with ‘x’ being any number). However, the IP address of the terminal used in the response message (the ‘Terminal IP’ field) from the POS will take precedence over the POS-PED routing.

Request Message:

Field Name Type Description 1 ‘WAITER’

String Mandatory

‘WAITER’ – indicates a waiter validation request

2 Waiter ID

String Mandatory


3 PTID

String Mandatory

The terminal ID

4 Terminal IP String Optional

The IP of the terminal being used by the waiter

Example: WAITER,1234,28459576,10.85.9.70 Response Message:

Field Name Type Description 1 ‘WAITER’

String Mandatory

‘WAITER’ – indicates a waiter validation request

2 Waiter ID

String Mandatory


3 Result String Mandatory

Possible values: VALID INVALID

4 Terminal IP String Optional

The IP of the terminal being used by the waiter

Example:

(Valid response) WAITER, 1234, VALID, 10.85.9.70 (Invalid response) WAITER, 1234, INVALID, 10.85.9.70


POS Responses All of the POS responses are in the following format:

Field Name Type Description 1 Result Integer Transaction result:

‘0’ – Completed ‘7’ – Declined ‘-nn’ – Negative values are used to define error conditions.

2 Terminate Loop Integer ‘0’ – Partial result ‘1’ – Final result For more details on this field, please refer to the Terminal Loop section within this guide.

3 Transaction Value Decimal Values will be truncated to the correct number of decimal places required for the transaction currency. For example: 1.23 = 1 (one Japanese Yen) (0 decimal places)

4 Cashback Value Decimal Values will be truncated to the correct number of decimal places required for the transaction currency. For example: 1.23 = 1 (one Japanese Yen) (0 decimal places)

5 Gratuity Value Decimal Values will be truncated to the correct number of decimal places required for the transaction currency. For example: 1.23 = 1 (one Japanese Yen) (0 decimal places)

6 PAN Decimal A copy of the PAN field from the .in file (if card details are keyed) or the PAN derived from Track2/ICC

7 Expiry Date MMYY Decimal Card Expiry Month and Year 8 Issue Number Decimal Card Issue Number. Empty when

issue number provided by card issuer 9 Start MMYY Decimal Card start month and year 10 Transaction Date / Time Decimal CCYYMMDDHHMMSS 11 Merchant Number Decimal The Merchant Number for the given

card scheme and account 12 Terminal ID Decimal Terminal ID used for this transaction 13 Scheme Name String Card scheme name 14 Floor Limit Decimal Floor limit for the given card scheme /

account 15 EFT Sequence Number Decimal Four digits in the range 0001 –

9999 16 Authorisation Code String Blank if the transaction is declined or

below the floor limit 17 Referral Telephone Number Leave empty 18 Authorisation Message / Error String As returned by communications

Please note: Depending on the POS message request, not all of the fields stated will be returned.


Message process. Normally direct from acquirer.

19 User ID String Mandatory

User ID which lodged the Bill

20 WaiterID* String Mandatory

The ID of the waiter who processed the bill.

21 TokenID* Decimal Mandatory

The token ID if the POS had requested account on file.

22 Reference* String Mandatory

The reference of the payment.

*These fields will only be returned for Payment Manager but not if operating in Legacy Mode.

Invalid Length/Message Response 98,1,,,,,,,,,,,,,,,,UNKNOWN MESSAGE


Terminate Loop The Terminate Loop field is used to indicate whether a POS response is partial or complete. This is used in instances when the payment for a bill is being paid in parts or in full payment.

If a part payment is being made, then Payment Manager will send a response of 0 (partial result) to the POS. All the time the part payments are being made, a terminal loop response of 0 is being sent to the POS. When the final payment is made then a final result of 1 (final result) will be returned to the POS.

If there is only one full payment, then Payment Manager will send a terminal loop response of 1.

POS sends T record on port 29000

Intermediate response – on port 25000 or .out file or same socket

PM sends a bill to the terminal

Terminal sends result back to PM

PM sends result to the POS on port 25000 or .out file or same socket (legacy mode)

Payment Manager (PM) lodges bill


APPENDIX

Terminal Screens The following images illustrate the various screens, menus and prompts displayed on the terminal when using Payment Manager.

Main menu screen (press ‘3’ on main menu for ‘Bill Options’).

Bill Options screen:

The Employee ID prompt is displayed after selecting any of the Bill Options; Close Bill, Get Bill, Get/Print Bill or Print Bill.

ocius

1. New Txn

2. Menu

3. Bill Options

4. Log Off

5. Other

Bill Options =========

1. Close Bill

2. Get Bill

3. Get/Print Bill

4. Print Bill

Please enter Employee ID by swiping card

Please note: The screens displayed below are only for illustrative purposes.


Reference ID or table ID prompt:

Retrieving bills screen after selecting the Get Bill option:

Available bills screen showing the reference/table IDs of all the bills lodged:

ENTER REFERENCE ID

PLEASE PRESS ENTER TO CONTINUE

Get Bill contacting Payment Manager to

retrieve bills

Available Bills ==========

1. A1

2. A2


Process Flow The process flow diagram below illustrates the steps involved when Payment Manager and Bill Manager (in legacy mode) process a B record transaction:

Bill Manager (Legacy Mode)Payment Manager

POS sends B record to Bill Manager on

PORT 29000.

If validation error occurs, Bill Manager sends error on same

socket.

If valid, bill will be lodged and socket

remains connected. Bill Manager sends a part or full payment result.

1.

2.

3.

4.

5. Step 4 repeats until bill is cleared and Bill Manager sends final result to the POS.

POS sends B record to Payment Manager

on PORT 29000.

If validation error occurs, Payment

Manager sends error on same socket.

Payment Manager sends a part or full payment result on

new socket via port 25000.

Final transaction result sent by

Payment Manger to the POS.

If valid, ‘Bill lodged successfully’ message sent on same socket.

POS should then close the socket.

POS should keep the socket open


Terminal Flow The below diagram illustrates a high level process flow of how the Get Bill, Get/Print Bill and Print Bill options are used on the terminal:

Customer requests bill

Employee selects “Bill Options”

Prompt for Employee ID

Terminal idle

Display bill and wait for selection

Print bill

Fetch selected bill

Prompt to enter amount to pay if

part payment (default: full

remaining value)

Prompt for gratuity decision

Prompt for account on file decision

Prompt to insert or swipe card or select

card payment

Perform EFT transaction

Payment complete?

Display “Updating bill – please wait”

message

Prompt for VAT receipt decision

No

Yes

Terminal will display “Contacting

Payment Manager to receive bills”

Select Bill

Print VAT receipt

Prompt for reference/table ID

Get Bill or Get/Print Bill option selected?

Yes

No


VeriFone Error Codes The following table illustrates a generic list of PAYware Ocius error codes, with descriptions and recommended actions required.

Error Code

General Description Additional Technical Description (if required)

Recommended Action

-1 Unspecified error Contact VeriFone Merchant Helpdesk

-2 Invalid transaction type

An example of this could be a Refund being passed when the site are not set up to do so. A trace of what was passed will be in the system log.

Use alternative method for transaction type

-3 Invalid card / invalid Track2

General card error. Track2 must either be ;PAN=YYMMsss……?x or just the PAN.

Re-enter card number or re-swipe card

-4 Card scheme not recognised

The card Issuer Identification Number (IIN) has not been located in the IIN table. The IIN is typically the first 4 to 6 digits of the card number.

Prompt for alternate method of payment

-5 Card scheme not accepted

The card has been identified, but the card scheme is not accepted at the given site.

Reject Transaction

-6 Invalid card number (lcd)

The LUHN check digit is incorrect (the card has been mis-keyed or mis-swiped).


-7 Invalid card number length

The length of the PAN is incorrect for the given card scheme.


-8 Invalid card number (pcd)

The pen-ultimate check digit is invalid.


-9 Expired card Prompt for alternate method of payment

-10 Card not yet valid Prompt for alternate method of payment

-11 Invalid card service code

The Track2 service code is invalid.


-12 File or XML missing or wrong format

A required file or XML is missing or has wrong format.

Contact VeriFone Merchant Helpdesk

-13 File permanently locked

A file required by the EFT library was still locked after EFT FIO TRIES attempts.


-14 Out of memory The library has failed to allocate sufficient heap.


-15 Account number does not exist

The requested account number does not exist.

Check the account number configuration of the system, ensuring it matches that configured within WinTI

-16 Value exceeds ceiling limit

Purchase value exceeds card scheme ceiling limit

Prompt for alternative method of payment.

Please note: Depending on the method of integration and communication means utilised, not all the error codes listed will be applicable to Payment Manager.


Arrange to increase ceiling limits

-17 Cashback exceeds ceiling limit

Cashback value exceeds card scheme ceiling limit

Revise transaction cash-back value

-18 Transaction currency is invalid

The transaction currency code is invalid or incorrect for the given site.

-19 Lay aways are not allowed

Attempt to lay away invalid / lay aways are not allowed

-20 Lay away already stored

Attempt to lay away a transaction where there is already a transaction laid away on that card


-21 EFT system not configured

The EFT system has not been configured

-22 Internal error, buffer too small

A buffer is too small

-23 Unknown comms device type

Invalid / unknown communications device type

Check communications configuration

-24 Configuration file is invalid

Configuration file is invalid / bad format

Check system configuration

-25 No valid accounts There are no valid accounts specified in the TillInfo.cfg

Check system configuration

-26 Invalid channel Invalid channel Check> · 2 transactions aren’t being passed down the same channel. · 2 tills aren’t using the same channel number. · WinTI EFTChans within the registry has enough available channels set (Socket mode only).

-27 System error –module not loaded

System error (Track2 check module has not been loaded)

-28 General transaction error

Re-enter transaction

-29 Transaction store unavailable

Transaction store unavailable Check Live Store. Check hard disk space.

-30 Unspecified error Unspecified error Check system log for indication of error.

-31 Unspecified error:2 Transaction cancelled Channel available for next transaction

-32 Library not open EFT library is unavailable -33 Possible text for error:

<fieldname> (<fieldno>) should be X to Y characters in length. <fieldname> out of range, should be X to Y. <fieldname> out of tolerance, is X, should be X +/- Z. Line discount not available for Cendant cards. Line count (X) doesn’t match header -> CPC lines (Y).

The error message is made up of a combination of text (1 to 6) with the applicable field name inserted, as applicable. For example: Net value out of tolerance, is 123.45, should be 123.00 +/- 1


Separate post and packing only on Amex cards. Where <fieldname> = part number, part description, commodity code, unit of measure, quantity, net value, VAT amount, gross value, PAN, PO number, customer number, customer name, customer VAT no, destination zip, destination country code, order date, original invoice number, cost centre, invoice net amount, invoice VAT amount, post and packing VAT, invoice gross or transaction total. Invalid CPC data

-34 Modifier field invalid/missing

As the modifier is passed within the T record the host software is likely to be the cause of this

-35 Invalid card / invalid Track 1

Track 1 is invalid Re-swipe card

-36 Invalid card / invalid Track 3

Track 3 is invalid Re-swipe card

-37 Invalid / missing expiry date

The expiry date is either invalid or missing. If key entered, the format should be MMYY

Re-enter expiry date or re-swipe card

-38 Invalid / missing issue number

The issue number is either invalid (value or length) or missing

Re-enter issue number or re-swipe card

-39 Invalid / missing start date

The start date is either invalid or missing. If key entered, the format should be MMYY.

Re-enter start date or re-swipe card

-40 Purchase/refund value bad or missing

The transaction value is either invalid or missing


-41 Cash-back value bad or missing

The cash-back value is either invalid or missing


-42 Auth code value bad or missing

The authorisation code is either invalid or missing

-43 Cheque account number value bad or missing

The cheque account number is either invalid or missing

Re-enter cheque account number

-44 Invalid cheque sort code

The cheque sort code is either invalid or missing

Re-enter sort code

-45 Invalid / missing cheque number

Re-enter cheque number

-46 Invalid / missing cheque type

Re-enter cheque type

-47 Invalid EFT serial number

The EFT serial number is either invalid or missing in the .Cnf file

Recreate *.cnf

-48 Unexpected CPC data Purchasing card invoice data has been presented for a non-

Re-enter transaction without invoice data or prompt for a


Purchasing Card (where invoice data is not valid/required)

valid Purchasing Card

-49 Transaction already confirmed or rejected

Attempt to confirm or reject a transaction, which has already been confirmed or rejected

-50 Copy protection failure

Could be a permission problem on the PC

-51 Post confirm reversal not allowed for PWCB or Cash Advance (reserved for future use)

Attempt to perform a post confirm reversal on a PWCB or Cash Advance has been dis-allowed (as post confirm reversals are not supported when cash is involved)

Reverse transaction manually (as cash is involved)

-52 Transaction data supplied in post conf rev not consistent with store (reserved for future use)

The details supplied in the post confirm reversal message is not consistent with the data stored for the transaction to be reversed

-53 Transaction already void

Attempt to perform a post transaction reversal has failed because the transaction has already been voided/reversed

-54 Card on hot list The card number is on the locally stored host list (received from the acquirer and/or entered by the customer). The card must be rejected


-55 Attempt to confirm a declined transaction

The format of the confirmation message is invalid (confirming a declining transaction). The confirmation message should contain a command value of 2 (reverse/reject) and not a value of 1 (confirm).

-56 EFT_ERR_BAD_CV2 CV2 is invalid Check CV2 and re-enter -57 EFT_ERR_BAD_AVS AVS is invalid Check AVS and re-enter -58 Invalid Merchant

Details Merchant Details passed in Web Services Gateway are Invalid.

Check both the GUID and Passcode information that being passed to the Web Services Gateway

-59 Invalid Mobile Number Format

The Mobile Number format passed is incorrect

Please check and re-enter the mobile number supplied.

-60 Invalid/missing bank account number

The bank account number within the supplied T-Record is incorrect.

Check the bank number being passed and re-enter as necessary.

-62 Token does not exist or invalid token for this merchant system

The Token ID supplied is incorrect or invalid for the merchant system

Check the Token ID is correct and for use with the current merchant system

-64 Unexpected / Invalid Authorisation Response

Unexpected / Invalid Authorisation Response from M-Voucher Host

Please contact VeriFone Merchant Helpdesk

-65 Invalid voucher target type

The Target Voucher Type is invalid (M-Voucher)


-66 Invalid Refund Pin The refund pin entered is invalid

Please enter the correct refund pin if continues to fail, please contact VeriFone Merchant Helpdesk

-67 Report Not Supported The Report ID supplied is either invalid or does not correspond to a report that is

Check the Report ID that is being passed


supported -68 Report Failed Integrated report failed Contact VeriFone Merchant

Helpdesk -69 Gratuity value

exceeded Check Gratuity Value Check Gratuity Value

-70 Invalid Capture Not Supported

Check Ocius settings Capture Method Not Set correctly

-71 Cashback not allowed by card

Card does not allow cashback Use a different card or proceed without cashback

-72 Cash advance not allowed by card

Card does not allow cash advance

Use a different card

-73 Max refund value exceeded

Refund transaction value is greater than the maximum refund value set on the account

Reduce transaction value

-74 Bill Already Complete The bill being cancelled is already completed and therefore cannot be cancelled.

N\A

-75 No ETU accounts Attempt to process ETU transaction without ETU accounts being present on terminal


-76 Card is online only Attempt to process an online only card whilst offline

Check network or use another card

-77 Cancel Failed - In Payment on xxx.xxx.xxx.xxx

Attempt to cancel a lodged Bill failed, usually locked on a specific terminal

Leave for configured amount of time before retrying cancel routine.

-78 Login failed User ID or PIN is incorrect Check login details and try again

-79 Confirmation Status Unknown

An invalid confirmation response has been received or the confirmation message to be sent was not saved

-80 Bill Reference Already Exists

Attempt to lodge a Bill into I-Link that already exists

Clear the original Bill, or re-send this one using an alternative reference.

-81 Print Report Failed The request report failed to generate or print

Check printer settings, network connection and try again.

-82 Network Error Error in Network Check network. -83 Invalid Record Invalid Record The record received is invalid. -84 PED User already

logged in A Login command has been received, but a user is already logged in

Log the terminal off first, or simply pass a transaction.

-85 PED User not logged in

The terminal needs to be logged in

Send a login command to the terminal, or manually login using the on-screen prompts, then re-send the transaction.

-86 Submission of offline transactions failed

The submission of the offline stored transactions have failed.

The transactions will still be stored on the terminal. Re-try, and if still having problems contact VeriFone Merchant Helpdesk.

-87 Problem in network There has been a problem in the network.

-88 Voice Referral Timeout

The voice referral transaction has taken too long.

Re-try or cancel.

-89 Invalid Account ID Invalid Account ID -90 Service Not Allowed Service code not supported Use another card, or cancel

the transaction -91 Card Not Accepted Card type not accepted Use another card, or cancel

the transaction


-92 Unknown Card Unknown card type Use another card, or cancel the transaction

-93 Not In IIN Range Unknown card type Use another card, or cancel the transaction

-94 Application Blocked The terminal cannot accept this card type

Use another card, or cancel the transaction

-95 Card Blocked The card has been blocked Use another card, or cancel the transaction.

-96 Card Error There is a problem with the card

Re-try or use another card.

-97 Authorisation Error The authorisation process has been interrupted or is not responding.

Check ILink & WinTI are running – or when using gateway, contact VeriFone Merchant Helpdesk.

-98 Unknown Client Unknown Transaction Source Unknown Message

When using transaction processing, if no POS Routing has been configured for the IP Address or File Name where the transaction originates from, ILink does not know where to send the transaction. It therefore rejects it with this message.

Configure POS routing for that POS

-99 Transaction/Bill Cancelled

When a transaction has been cancelled by the user, the system or an ICC card, this error message will be sent.

-100 Pin Bypass Failed ICC Card does not allow Pin Bypass.

Use another card

-101 Invalid Terminal Country Code'

The Terminal Country Code passed is invalid

Please check the ISO Country Codes table and make sure the code being passed is correct.

-102 User has no permissions on specified account

Check account permissions in WebCom.


-103 Invalid Currency Code'

The Currency Code passed is invalid.

Please check the ISO Currency Codes table and make sure the code being passed is correct.

-104 Invalid EMV Terminal Type'

The EMV Terminal Type passed is invalid

Please check the EMV Terminal Type that is being passed is valid.

-105 Unknown Message Type

The message type received by server side is not recognised


-106 General Enqueue Error

General VeriFone Enqueueing Error


-107 Transaction Confirmation Error

The transaction confirmation has errored.

Please retry the confirmation and if continues to fail please contact VeriFone Merchant Helpdesk

-108 Payer Auth Error The Payer Auth has encountered an error.

Please check the error message response and contact VeriFone Merchant Helpdesk

-109 Ukash Auth Error The Ukash transaction has encountered an error.

Please check the error message response and Contact VeriFone Merchant Helpdesk

-110 Encryption Failure An error has occurred in the data encryption.



111 Unable to build Auxillary Data Record

The auxillary data record failed to build correctly


-112 Transaction rejection error

The attempt to reject the transaction has errored

Please retry the rejection and if continues to fail please contact VeriFone Merchant Helpdesk

-113 Unknown Terminal The terminal\PTID is not recognised


-114 Invalid Download Type

The download type is invalid Please contact VeriFone Merchant Helpdesk

-115 Terminal Registration Failed

The attempt to register the terminal has failed

Please retry the registration if it continues to fail, contact VeriFone Merchant Helpdesk

-116 Terminal has been deactivated

The terminal has been marked as deactivated.


-117 Comms down Acquirer has been blocked in the database as acquirer is not processing any authorisations (comms down)


-118 M-Voucher Service Unavailable

This is when the terminal is in offline mode at the start of a transaction, and cannot connect to the hosted server to allow M-Voucher


-119 Barclays Bonus Service Unavailable

Error response when Comms failure between server application and XLS Host experienced.


-120 Token Server Error The Token Server has encountered an error


-121 Purchase transaction type not allowed on token

The token provided does not allow purchase transactions

Please supply another token that allows purchase transactions

-122 Refund transaction type not allowed on token

The token provided does not allow refund transactions

Please supply another token that allows refund transactions

-123 Cashback transaction type not allowed on token

The token provided does not allow cashback transactions

Please supply another token that allows cashback transactions

-124 Token expired The token provided has passed its expiry date

Please register a new token

-125 Invalid TokenID The token provided is invalid Please supply another token or contact VeriFone Support

-126 Token has no Txn Type Permissions

The Token Registration has no transaction permissions

Please resubmit the token request with transaction permissions enabled

-127 Invalid Token expiration date

The token expiration date provided is invalid

Please resubmit the token request with a valid token expiration date

-128 ProcessingDB Missing or Invalid

The processing database that is passed in the client header is either missing or invalid.

Please check that the message you are sending has the processing database set in the client header and that it is valid (as per the transaction\payer auth request)

-129 Invalid Original Barclays Gift Transaction ID

The Original Gift Transaction ID provided is invalid

Please check the Original Transaction ID and try again.

-130 Invalid Barclays Gift Configuration

Your Barclays Gift Configuration is invalid

Please check the configuration and download to


the terminal. If the problem continues please contact support.

-131 Barclays Gift Service Unavailable

The Barclays Gift Service is temporarily unavailable

Please contact VeriFone Support

-132 Merchant Reference Required

Your current configuration requires a Merchant Reference to be passed.

Please re-submit the transaction with the Merchant Reference populated.

-133 Account On File Not Allowed

Terminal is operating in offline mode Account does not allow Account On file CNP transactions EFT transaction capture method does not support registration of details for Account On File processing

Please check that the terminal is online Please check the configuration of the account Check the transaction details that you have passed.

-134 Card not allowed to be keyed

The card scheme doesn't allow processing of keyed card numbers

Use another card, or cancel the transaction

-135 Timeout Waiting for Card

A timeout has occurred whilst waiting for the card and Transactions has been cancelled

Reprocess Transaction.

-137 Present Cash Advance Transaction As Purchase

The card presented does not support cash advance and needs to be represented as a purchase txn.

Reprocess Transaction as a purchase

-138 Gratuity Value Incorrect

Check Gratuity Value Check Gratuity Value

-139 Transaction Timeout The application has timed out waiting for a Barclays Gift response

Please check whether the gift request has gone through and if necessary please try again.

-140 Schedule Payment registration failed

The scheduled payment registration has failed.

Please attempt to re-register the scheduled payment or contact VeriFone Support

-141 Ocius migration failed The Ocius migration failed on the database because the migration has not been setup / enabled

Contact VeriFone to arrange for migration

-142 S Record Timeout Terminal has timeout after 30 seconds from no response from user

Reprocess record if required

-143 Download Failed The software or configuration download on the Vx 810 solution has failed to complete its download successfully.

Please retry the download if it continues to fail please contact VeriFone Support

-150 Invalid PayPoint Configuration

The PayPoint configuration that you have setup is invalid.


-151 No PayPoint Accounts There are no PayPoint accounts available.


-152 PayPoint Service Unavailable

The PayPoint service is currently unavailable

Please retry the payment or contact VeriFone Merchant Helpdesk

-153 PayPoint Download Required

A PayPoint download is required

Please perform a configuration file update to your terminal

-154 PayPoint Account Extraction Failed

PayPoint account file extraction has failed

Please retry the download if it continues to fail please contact VeriFone Merchant Helpdesk


-155 PayPoint Transaction Type Not Allowed

The PayPoint transaction type provide is not allowed

Please check the Transaction Type supplied and correct

-156 Invalid PayPoint TopUp Type

The PayPoint TopUp type provided is invalid

Please check the TopUp Type supplied and correct

-157 Invalid PayPoint Service Provider

The PayPoint Service Provider provided is invalid

Please check the Service Provider supplied and correct

-158 Invalid PayPoint Scheme

The PayPoint Scheme provided is invalid

Please check the Scheme supplied and correct

-159 Invalid PayPoint Scheme Option

The PayPoint Scheme Option provided is invalid

Please check the Scheme Option supplied and correct

-160 Invalid PayPoint Amount

The PayPoint Amount provided is invalid

Please check the Amount supplied and correct

-161 No PinPad Available The PIN pad is currently unavailable

Please check the PIN pad is available for use, contact VeriFone Merchant Helpdesk if the problem persists.

-189 Invalid refund password

An invalid refund password has been supplied during the transaction, and was rejected by the database


-999 Token Server Error Start date or issue data supplied is incorrect or missing

Please check you are passing the appropriate required fields

-1000 Generic Error Generic Capture Error Please contact VeriFone Merchant Helpdesk

-1001 Merchant Supplied Bad Data

The information supplied in the post is incorrect

Please check the data that you are sending and retry.

-1002 Bad Source URL The source URL is unrecognised


-1003 Attempting to use a TokenID and a PAN at the same time

A TokenID and PAN were received for the same transaction

Please check the data that is being passed

-1004 Curl Error Communication Error Please contact VeriFone Merchant Helpdesk

-1005 Couldn't Extract Error Code from Response

The error code returned could not be extracted


-1006 Failed to Retrieve System Config

Payment Page has failed to retrieve your System Configuration


-1007 Unusual Data Supplied (Possible Attack)

The data that has been supplied is suspicious

Please check the data that you are sending and contact VeriFone Merchant Helpdesk

-1008 Failed to Retrieve Session Data

Payment Page has failed to retrieve your session data


-1009 Failed to Create New Session

Payment Page has failed to create a new session


-1010 Bad SessionID received from end user

The sessionID provided by the front end is incorrect.


-1011 Bad PIN received from end user

The PIN provided by the front end is incorrect.


-1012 Session Finished The session that you are trying to use has already finished.


-1013 Failed to extract PA Data

An error has occurred trying to decrypt\extract the Payer Auth data


-1014 Session Expired The session that you are trying to use has expired.



Contact Details

© 2014 VeriFone. All rights reserved. VeriFone, the VeriFone logo, VX are either trademarks or registered trademarks of VeriFone. No part of the contents of this document may be reproduced or transmitted in any form without the written permission of VeriFone.

All content information is subject to change without notice.

VeriFone Services UK & Ireland 100 Eureka Park

Ashford Kent

TN25 4AZ

PAYware Ocius Merchant Helpdesk [email protected]

08444 828 222

VeriFone Technical Services [email protected]

08444 828 273

Sales Enquiries [email protected]

08444 828 200

Customer Services 08444 828 223

Website: www.verifone.co.uk

mailto:[email protected]



http://www.verifone.co.uk/

payment manager manual – v2.1 - wordpress.com manager is a payment management solution which has...

Documents