CardGate.net Pty Ltd CardGate® Payment Gateway V5 ... · 5.6.1 Event ID 7 and ID 37 54 5.7.2 Event ID 24 54 5.7.3 Event ID 34 54 6. USER INTERFACE 55 6.1 State View 55 6.2 Console

CardGateV5-TM.004.doc Commercial-in-confidence Issue 4 - Page 1 of 72

CardGate.net Pty Ltd

CardGate® Payment Gateway V5

Technical Manual

CardGate program version 5.00

28 February 2013

Issue 4

CardGate.net Pty Ltd A.C.N. 086 679 950

1/200 Wellington Rd Clayton 3168

Australia

PO Box 4297 Mulgrave 3170

Australia

Tel (03) 9582 7000 Fax (03) 9582 7001

Support (03) 9582 7099

[email protected]

www.cardgate.net

Reference : DOC-CardGateV5-TM

Copyright© 1999-2005, 2011-13 UMD IP Pty Ltd ACN 08 7 361 644


1. INTRODUCTION 5

1.1 Overview 5

1.2 What is the CardGate Payment Gateway? 5

1.3 What does the Merchant need to supply? 5

1.4 Communications between CardGate and COMMLINK 5

1.5 Virtual Terminals 6

1.6 This Manual 6

1.7 Trademarks 6

1.8 Confidentiality and Copyright 6

1.9 Abbreviations 6

2. CONFIGURING CARDGATE 7

2.1 Win32 Registry 7 2.1.1 Strings 7 2.1.2 Registry Values 8

2.2 External Files 13 2.2.1 Terminal definition file 13 2.2.2 Sequence number files 16 2.2.3 Remembered state file 16 2.2.4 Warning bulletin file 17

2.3 Operating System Settings 17

3. INTERAPPLICATION COMMUNICATIONS 18

3.1 System Partitioning 18

3.2 Interfacing with CardGate 18 3.2.1 File method 18 3.2.2 Sockets method 19

3.3 Custom Interfaces 19

4. MERCHANT APPLICATION DATA INTERCHANGE 20

4.1 Record Structure 20

4.2 CardGate Responses 20

4.3 Requests Fields 22 4.3.1 Source ID 22 4.3.2 Sequence Number 22


4.3.3 Message Type 22 4.3.4 Merchant ID 22 4.3.5 Reference Text 23

4.4 Non-Financial Authorisation / Financial Transaction Request / Warning Bulletin Lookup 23 Additional Data 25 4.4.1 Authorisation /Financial Transaction Response 27 4.4.2 Authorisation / Financial Acknowledgment 29 4.4.3 Reversals 33

4.5 Financial Capture Transaction Request 34 Additional Data 36 4.5.1 Financial Capture Response 37 4.5.2 Financial Capture Response Acknowledgment 39

4.6 Reconciliation Advice 40 4.6.1 Reconciliation Response 41 4.6.2 Reconciliation Response Acknowledgment 42 4.6.3 Settlement Options 42

4.7 CardGate Immediate Commands 43

4.8 Training Mode / Host Emulation 48

5. TRACEABILITY, LOGGING AND ANOMALIES 49

5.1 CardGate Record Of Transaction Log 49

5.2 Monitor Log 49

5.2 Monitor Log via Socket Stream 51

5.4 Socket Request Log 51

5.5 Host Communications Log 52

5.6 Event Logging 53

5.7 Typical Anomalies 54 5.6.1 Event ID 7 and ID 37 54 5.7.2 Event ID 24 54 5.7.3 Event ID 34 54

6. USER INTERFACE 55

6.1 State View 55

6.2 Console View 55

7. SUPPORT 55

8. REVISION HISTORY 56

APPENDIX A. COMMLINK RESPONSE CODES 57


APPENDIX B. CARDGATE RESPONSE CODES 58

APPENDIX C. VERSION DIFFERENCES 60

C.1 Version 5 differences 60

APPENDIX D. SAMPLE REFERENCE VISUAL BASIC CLIENT 61

APPENDIX F. OPTUS/TNS CONFIGURATION 65

F.1 CardGate Registry Settings 65

APPENDIX G. TELSTRA ARGENT CONFIGURATION 66

G.1 CardGate Registry Settings 66

APPENDIX H. CBA IP@POS CONFIGURATION 67

H.1 CardGate Registry Settings 68

H.2 Set up Firewall rule for netAccess IP 67

H.3 netAccess Device Setup 69

H.3 netAccess Device Setup Error! Bookmark not defined.

APPENDIX I. CONFIGURING WINDOWS 71

I.1 Starting CardGate without logging on 71

APPENDIX J. UPGRADING FROM VERSION 4 TO 5 72

J.1 Set up directory 72

J.2 Update the Terminal Definition File 72

J.3 Transfer state file 72


1. Introduction

1.1 Overview CardGate® is a payment gateway that operates exclusively with the Commonwealth Bank of Australia's COMMLINK on-line credit card authorisation and transaction system which allows merchants to conduct credit card transactions in real-time.

CardGate® is a PC based system that interfaces to the Commonwealth Banks’ COMMLINK host.

CardGate® simply interfaces with a Merchant's computer or interactive voice response (IVR) system.

Custom interfaces to CardGate® can be built to suit a Merchant's exacting requirements.

CardGate® takes the certification load, ie the Merchant system does not need to be evaluated by the Commonwealth Bank prior to taking live transactions.

1.2 What is the CardGate Payment Gateway? The CardGate Payment Gateway is a turnkey PC based package that interfaces a merchant’s transaction system - be it a standalone PC, DOS/WINDOWS/UNIX etc based LAN, mini computer, mainframe or IVR systems with the Commonwealth Bank’s COMMLINK™ real-time credit and charge card authorisation system.

The package includes -

• CardGate software • CardGate.net's Supply of Turnkey System Agreement incorporating the

Merchant Agreement • Consultancy, customisation, installation • Maintenance which includes 24h x 7d support, software maintenance

updates and alerting service

1.3 What does the Merchant need to supply? CardGate interfaces with the Merchant Application which must be modified to produce the required files and/or communications links. The standard CardGate interfaces are described in this manual.

The Merchant is responsible for supplying the computer connected to their local area network with an appropriate MS-Windows operating system.

Before CardGate is supplied, the Merchant must sign CardGate.net's Supply of Turnkey System Agreement which incorporates the Merchant Agreement.

1.4 Communications between CardGate and COMMLINK CardGate communicates via Bank supplied communications links with the Commonwealth Bank's COMMLINK host system by sending it formatted messages and receiving responses. CardGate completely handles the communications and error processing requirements.

CardGate can use multiple communications channels, which includes Optus/TNS VPN solution or Telstra Argent®.


1.5 Virtual Terminals Each Merchant ID configured on the Bank's host must have a minimum of one terminal ID (CATID) assigned to it. A terminal can be regarded exactly like an EFTPOS terminal typically used in retail stores. Each terminal can process only one transaction at a time which will normally complete within a few seconds. It should be noted however that "stuck transactions" can occur which hold up a terminal for up to half an hour (after which it is deleted from CardGate’s state file).

The number of terminal ID's assigned to a given Merchant ID determines the number of credit card transactions that can be handled simultaneously for that Merchant ID.

CardGate introduces the concept of "virtual terminals" where multiple Merchant ID's and multiple terminals per Merchant ID can be handled on a single CardGate gateway. The number of virtual terminals installed determines CardGate pricing.

1.6 This Manual Recommendations will be highlighted in BLUE .

This manual should be read in conjunction with the Commonwealth Bank of Australia’s COMMLINK specifications, Version 2.33 or higher.

1.7 Trademarks Argent® is a registered trademark of Telstra.

CardGate® is a registered trademark of UMD IP Pty Ltd.

COMMLINK is a trademark of the Commonwealth Bank of Australia.

Microsoft® is a registered trademark of Microsoft Corporation, and Windows is trademark of Microsoft Corporation in the United States of America and other countries.

Other brand and product names are trademark or registered trademark of their respective holders.

1.8 Confidentiality and Copyright No part of this literary work may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, stored in any retrieval system of any nature without the written permission of the copyright holder, application for which shall be made to the copyright holder.

1.9 Abbreviations • ABP – Asynchronous Block Protocol • ATA – Argent Terminal Adapter • CBA - Commonwealth Bank of Australia • CCV – Card Check Value • CLNP – Connectionless Network Protocol • CSC – Card Security Code • CVV – Card Validation Value • DEnn - AS2805 Data Element number nn • ENG - Enterprise Network Gateway, ie CBA's branch network • MTA – Managed Terminal Adapter • PCI DSS – Payment Card Industry Data Security Standard • ROT - Record Of Transaction • TNS – Transaction Network Services • TPDU - Transport Protocol Data Unit


2. Configuring CardGate The CardGate software is configured to suit a particular Merchant Application by:

a) the Win32 Registry

b) Configuration files

c) Operating system settings

2.1 Win32 Registry CardGate uses registry sub-key "\\HKEY_LOCAL_MACHINE\SOFTWARE\UMD\CardGate PARM" to store its configuration values, where PARM is the optional command line parameter used to call the CardGate executable. This concept of profiles is new to CardGate V4 and proves very useful in a multi-connectivity and/or multi-session environments.

For example: you could have a Windows short cut labelled “CardGate via ENG”, with the short cut having the target set to:

“C:\program files\cardgatev4\cardgate.exe” ENG

This would use registry sub-key:

"\\HKEY_LOCAL_MACHINE\SOFTWARE\UMD\CardGate ENG"

2.1.1 Strings Registry string values may contain the following 'escape' characters:

\\ single back slash (\) \r carriage return ie 0Dh \n line feed ie 0Ah \t tab ie 09h \nnn octal value nnn \xhh hexadecimal value hh


2.1.2 Registry Values

Software unlocking Value name Type limits default

Serial Nr String max length 8 ""

This parameter is supplied by CardGate.net. It is used to serialise the package and "unlock" virtual terminals.

State file back up Value name Type limits default

State Backup File String max length 40 ""

If you want the state.dat file backed up in real time, provide the file name (and path if not in the current directory), eg “state.bak” or “d:\\cardgatebak\\state.bak”

It is recommended that a backup of this important state file be enabled.

Communications Value name Type Limits default

Dial0 String max length 40 ""

Telephone number used to access the Bank host.

Value name Type Limits default

Line Mode 0 DWORD 0

0 = Dial up modem access 1 = Leased line modem access 2 = Serial port direct with Data Carrier Detect (DCD) 3 = Serial port direct without Data Carrier Detect (DCD) 4 = Asynchronous Block Protocol (ABP) wrapping Connectionless Network Protocol (CLNP) - used by Telstra Argent® and CBA IP@POS 5 = Asynchronous Block Protocol (ABP) wrapping Tran sport Protocol Data Unit (TPDU) …..- used by Optus/TNS Solution via MTA serial port 6 = TCP/IP, length prepending Transport Protocol Data Unit (TPDU) …..- used by Optus/TNS Solution via MTA ethernet port (NOTE – Option 6 is NOT IMPLEMENTED)


Line Nr 0 DWORD 0 ..16 0

When Line Mode 0 = 0 (ie dial up) indicates which TAPI line number to use to dial. 0 is don't care, 1 is the first line, 2 the second line and so on.

Value name Type limits default

Comms Port String "COM2"

When Line Mode 0 = 1 to 5, it indicates which communications port to use for the connection.



Comms Mode String "9600,N,8,2"

When Line Mode 0 = 1 to 5 this string is used as the mode command to configure the communications port indicated in Comms Port.

Value n ame Type Limits Default

Refused String String max length 40 "Connection refused!"

Banner String String max length 40 "\x05"

Logon String String max length 40 “”

Logged On String 0 String max length 40 “CHANNEL 1\r\n”

Logged On String 1 String max length 40 “\x151\x81\xC55)\xFF”

These strings are used in the host logon process. Upon modem connection, CardGate waits for the receipt of the banner string. Once the banner string is received, the logon string is transmitted and then reception of either logged on string 0 OR logged on string 1 is awaited before proceeding with transmission of transaction requests.

Refer to the Configuration Settings Appendix relevant to the communications channel you are using (eg Optus/TNS) as the defaults above are not relevant to all these options.

Value name Type Limits Default

Banner Timeout DWORD 1 .. 500

Used by ReadFile(). Is the initial intercharacter gap, in milliseconds, to use when logging on to the host. Used to ensure reception of the banner string and any required delay between transmissions of the first message.


Read Interval Timeout DWORD 1 .. 30 000 10

Used by the Win32 ReadFile() routine to indicate what the intercharacter time is (in milliseconds) before returning with a buffer read


No Activity Timeout DWORD 0 ..60 000 0

Time to wait in seconds before disconnecting a call when there is no activity. 0 means don't hang up.


Post Message Delay DWORD 0 .. 30 000 0

Inter message delay in milliseconds. 0 means no delay.


NSAP SHA DWORD 0 .. 0


Telstra Argent® - Network Service Access Point Symbolic Host Address (supplied by the Bank)


NSAP Terminal Id DWORD 0 .. 0

Telstra Argent® - Network Service Access Point Terminal Identifier (supplied by Telstra, tied to the Terminal Adapter)


Listen Port DWORD 4000

TCP/IP sockets server listening port. Note that the Monitor port is this value + 1.


Host Address nn STRING

TCP/IP address (eg 192.168.10.80), or address:port (eg 192.168.10.80:xxxx) of the nnth iNAC (TCP/IP Network Access Controller) for the Transact Plus TCP/IP solution. If a port is not specified, then the default port xxxx is assumed.

NOTE – NOT IMPLEMENTED


File Mode Directories Value name Type Limits Default

Request Directory string max length 39 "DATA\"

This is where CardGate reads in the request files. NOTE – must end directory names with “\”.


Response Directory 0 string max length 39 "DATA\"

Response Directory 1 string max length 39 “”

Response Directory 2 string max length 39 “”

This is where CardGate writes the record of transaction files. Note that the same file is written out multiple time for redundancy. An empty string indicates not to write out a file. NOTE – must end directory names with “\”.

Warning Bulletin


Warning Bulletin Directory

string max length 40 ""

This is where CardGate reads in the Warning Bulletin file. NOTE – must end directory names with “\”.

Note that this directory should be dedicated to only holding the warning bulletin file as whenever any file is written to this directory, the Warning Bulletin file is reloaded.


Warning Bulletin File string max length 40 ""

This is the Warning Bulletin file. Blank string means no file present.


Warning Bulletin Format

DWORD 0.. 0

This is the format of the Warning Bulletin file. Only one format handled at the moment.

Logging Value name Type Limits default

Online Log DWORD 0 .. 1

0 means to not log sockets communications. 1 means to log sockets communications as time stamped data to the "ONLINE_YYYYMMDD.TXT" file. 2 means to log sockets communications as time stamped data to "COMMS_YYYYMMDD.TXT" file (V3.2)

This should normally be disabled (ie set to 0) in production as you will not be PCI DSS COMPLIANT with logging enabled .



Comms Log DWORD 0 .. 0

0 means to not log received and transmitted frames, 1 means log all bytes received as raw time stamped data to the "COMMS_YYYYMMDD.TXT" file.

This would normally be disabled (ie set to 0) in production as you will not be PCI DSS COMPLIANT with logging enabled .


Debug Log DWORD 0 .. 1

0 means to not log. 1 means to write the monitor output to file "MONITOR_YYYYMMDD.TXT".

This would normally be enabled (ie set to 1) in production. It is a very handy for tracking communications issues.


Error Level DWORD 0 .. 0

0 means standard level of error reporting.

1 means to log socket connections lost and ‘C’ and ‘V’ acknowledgement timeouts to the Event Log.

Note as these errors are more readily viewed in the Debug Log file if enabled, recommendation is to leave this setting at 0.


Event Log Server String ""

Windows NT event logging is put to the computer named here. If the string is empty, this indicates to use the local computer's event logging service.

Host emulation Value name Type Limits default

Test Mode DWORD 0 .. 0

0 means normal operation, 1 means simulate host response, 2 indicates to connect in usual way with host using modem, but simulate host response.


Success Rate DWORD 0 .. 0

When Test Mode is 1, 0 indicates to use cents part of transaction value as the Bank response code; for example a transaction request with value $1.23 in emulation mode will respond with emulated bank response of “23”. Values 1 to 10 is n * 10% success rate, so 10 means 100% success rate.


2.2 External Files

2.2.1 Terminal definition file CardGate allows multiple Merchants and multiple virtual terminals to be defined for each Merchant.

The terminal definition file "terminalv4.txt" is used to set up these virtual terminals with their CAIC (ie Merchant ID) and CATID (ie Terminal ID) numbers, as assigned by the Bank. [NOTE that CardGate Version 3 used file “terminal.txt” an d CardGate Version 4 and 5 use file “terminalv4.txt.]

Terminalv4.txt is a TAB control character delimited text file with the following [optional] fields:

CAIC CATID KEY FLAGS Comment [SaleLimit] [RefundLim it]

Comments may be included by starting the line with the “#” character.

FLAGS is made up of a sequence of ASCII HEXADECIMAL digits, ie '0' through ‘9', ‘A’ through ‘F’ characters. For boolean values, ‘1’ meaning ENABLE and all other values mean DISABLE.

Position Meaning

1 (most left hand) Refund enable, (boolean).

2 Void enable, (boolean).

3 For sockets transactions, write Record Of Transaction File 0 = Don’t write file 1 = Write file as CAIC.ROT 2 = Write file as CAIC.YYYYMM.ROT where YYYYMM = transaction date as returned in field 013 (V4.2) 3 = Write file as CAIC.YYYYMMDD.ROT where YYYYMMDD = transaction date as returned in field 013 (V4.2) 4 = Write file as CAIC.YYYYMM.ROT where YYYYMM = settlement date as returned in field 015 (V4.2) 5 = Write file as CAIC.YYYYMMDD.ROT where YYYYMMDD = settlement date as returned in field 013 (V4.2)

4 Warning Bulletin File look up, (boolean).

5 Return the Primary Account Number (PAN - ie card number) in field 911. (V4)

0 = don’t return field 911 1 = return the PAN as the FULL card number, eg "5353100000000000" Do not use this option in production as you will not be PCI DSS COMPLIANT with it enabled 2 = return the TRUNCATED PAN as the first six digits, dot, last three digits of the PAN, eg "535310.001" 3 = return the TRUNCATED PAN as the first four digits, dot, last four digits of the PAN, eg "5353.0001" 4 = return the TRUNCATED PAN as the first 2 digits, dot, last four digits of the PAN, eg "53.0001" 5 = return PAN as MD5 hash (refer to document CardGateV4-SM for further information) 6 = return PAN as first half of MD5 hash (refer to document CardGateV4-SM for further information) 7 = return PAN as second half of MD5 hash (refer to document CardGateV4-SM for further information) 8..A = reserved

6 Return the Card Type (first two digits of the card) in field 913,


(boolean). (V4)

7 Terminal is barred from use. Transaction attempts will return INF_INVALID, (boolean). (V4)

8 Log sockets client IP address and Port number and authenticated user in fields 914, 915 and 916, (boolean).

9 Authentication required for SALE above sale limit. (V4) Unauthorised transaction attempts will return ERR_AMOUNT_BAD, (boolean).

10 Authentication for REFUNDS (V4) 0 = Authentication not required 1 = Authentication required TO the refund limit 2 = Authentication required ABOVE the refund limit 3 = Authentication required for ANY refund Unauthorised transaction attempts will return ERR_AMOUNT_BAD

11 Authentication required to view terminal status (ie perform Status immediate command), (boolean). (V3.8)

12 Return field 917 (year), (boolean). (V4.2)

13 Return Expiry Date in field 912, (boolean). (V4.4)

14 CardGate4OCV – Client Type

15 Confirm Command Acknowledgement not required (v4.9)

16 Optionally set settlement time for this terminal for Amex (not implemented – set to ‘0’)

17 Optionally set settlement time for this terminal for Diners (not implemented – set to ‘0’)

18 Optionally set settlement time for this terminal for MasterCard/Visa (not implemented – set to ‘0’)

19 COMMLINK compatibility

0 = V2.2 AND LOWER 1 = V2.32 AND HIGHER (IE DE47 MANDATORY)

20 Point Of Service Condition Code, Data Element 25: (v5.0)

0 = ‘15’ – (USE FOR COMMLINK VERSION EARLIER THAN V2.32) 1 = ‘08’ – MAIL OR TELEPHONE ORDER (INCLUDING IVR, RECURRING AND NON-INTERNET BASED TRANSACTIONS) 2 = ‘48’ – ELECTRONIC COMMERCE/INTERNET

21 Additional Data – ECM tag – first (m )value (v5.0) 0 – Unknown 1 – Telephone order 2 – Mail order 3 – Internet Order

22 Additional Data – ECM tag – second (t) value (v5.0) 0 – Unknown 1 – Single transaction


2 – Recurring transaction


23 Additional Data – SLI tag – (v5.0) 0 – Not applicable 5 – Authenticated secure electronic commerce transaction 6 – Non Authenticated secure e-comm where card acceptor is certified to perform authentication 7 – Non Authenticated secure e-comm where card authentication cannot be performed. Other security mechanisms may be present. Ex: channel encryption 8 – Non-secure transaction in the clear over an open network

FOR EXAMPLE: # Name changed 311000062120500 82120507 76749 111021 My business 311000062120500 82120508 44366 001021 My business 311000062121300 82121300 37962 111100 Your business 311000062121300 82121301 05589 111100 Your business 311000062121300 82121302 05349 111100 Your business # No refunds wanted on the following 311000062121300 82121301 05589 1111000002 Joes 0 50 000

A sample terminal definition files is provided in the software distribution as “terminalv4-sample.txt”.

2.2.2 Sequence number files A sequence number file is maintained in the CardGate directory for each Merchant ID (CAIC) that is to have file mode input to record the highest sequence number received from the Merchant Application. The file name is simply the CAIC number with a ".TXT" extension eg:

311000062121300.TXT

The contents of the file is a six ASCII digit sequence number, for example:

016001

With Version 4, this file will be automatically created if it does not exist, which will be the case when added a new merchant facility.

2.2.3 Remembered state file CardGate maintains the current state of each virtual terminal in file “STATE.DAT”. It is used to ensure that any outstanding transactions are completed in the event of an outage. It is important that this file not be deleted as it holds the Systems Trace Audit Number for each virtual terminal .

With Version 4, every time CardGate is started, the current state.dat file is first written to a backup file named state.YYYYMMDD-HHMMSS.dat where “YYYYMMDD-HHMMSS” represents date and time, eg state.20050406-091431.dat. This is done BEFORE it is updated with any new or deleted virtual terminals.

With Version 4, a registry value has been added, “State Backup File” which allows for the state file to be mirrored to a second file. This proves useful for backup and recovery procedures and it is recommended that this facility be enabled.


2.2.4 Warning bulletin file The optional warning bulletin file holds card numbers and partial card numbers that will optionally be searched (if the Warning Bulletin Lookup flag is set in the terminal definition file) for pre-authorisation, financial and offline transactions.

This file is also searched with the "W" warning bulletin look up transaction. All these transactions will return INF_WARNING_LIST if a match is found in the file.

The file is ASCII text, one record per line. In the example below, 4015200000000001 and 4015200000000012 will be matched with the first record.

Here is an example of the file's layout:

401520 ALL CARDS 4028380008182020 4028380009093697 4072202010833835 4072202010846902 4072202010851969

Note that if the Warning Bulletin Directory is set in the registry, CardGate will monitor it for any directory changes. As soon as a new file is written to this directory, CardGate will reload the warning bulletin file to memory. For this reason, the warning bulletin directory should only contain one file, the warning bulletin file. This allows, for example, daily updates to the warning bulletin list without restarting CardGate.

2.3 Operating System Settings CardGate PC must be using the TCP/IP protocol stack if the sockets interface is to be used. The modem device driver and settings must be set up if dial up access is required.


3. Interapplication Communications

3.1 System Partitioning Merchant Applications can connect with the CardGate Payment Gateway in a variety of ways:

Merchant Application--LAN--CardGate—Comms--COMMLINK

Merchant Application--Custom Interface--CardGate--C omms--COMMLINK

3.2 Interfacing with CardGate There are two methods of inter-application communication provided by CardGate, file and sockets.

3.2.1 File method The Merchant Application may communicate with CardGate by writing standard tab delimited ASCII text Request files (name with file extension ".REQ") to the Request directory (as configured in the registry). The gateway reads these request files, performs the transactions and responds by writing a Record Of Transaction response file with the ".ROT" extension. These files hold all bank responses and CardGate rejected requests. Once the request file has been completely read, its' extension is renamed from ".REQ" to ".FIN".

For

Request Directory = REQUEST\

Response Directory 0 = RESPONSE\

REQEST\SAMPLE.REQ � Processed by CardGate � RESPONSE\SAMPLE.ROT

� renamed on completion � REQUEST\SAMPLE.REQ of read


3.2.2 Sockets method CardGate provides a standard "sockets" interface to allow inter-application communications with a Merchant system over a TCP/IP network. It acts as a sockets server, listening on a user configurable TCP/IP port (default is port 4000).

The sockets interface is typically used when a "real-time" response is required, for example to respond to a card holder waiting on the end of a telephone conversation for confirmation of a credit card payment request.

Some pseudo code follows:

// create the socket sh = socket(PF_INET, SOCK_STREAM,…); // Initialise host socket address to connect with sa.sin_addr = "128.23.23.1"; // IP address of CardG ate PC sa.sin_port = 4000; // port number used by CardGat e // seek a connection ok = connect(sh,sa) if ok == 0 do { SeqNr = SeqNr + 1; // Bump SeqNr

// get request for credit card transaction GetRequest(&request); send(sh, request); // send to host StartTimer; ok = recv(sh,response); // receive from host if (ok > 0) { // we have a response - act on it ActOnResponse(&RxSeqNr); StopTimer(RxSeqNr);

// acknowledge receipt of response to CardGate send(sh, 'C'+ RxSeqNr); } else if (timeout) { // timed out - ask CardGate to reverse

// original transaction send(sh, 'V' + SeqNr); // Let the requesting process know we had a problem

ErrorReport(SeqNr); }

} while(not finished); closesocket(sh);

To learn more about sockets programming, refer to "Windows Sockets Network Programming" by Bob Quinn and Dave Shute, published by Addison Wesley. Microsoft's web site also has extensive information on Winsock programming. A sample Visual Basic 5 client application is listed in Appendix D.

3.3 Custom Interfaces Custom Interfaces can be written to interface a Merchant Application with CardGate. They will typically be written to connect a Merchant Application which is not readily modifiable to communicate directly with CardGate.

Reference client applications, including source, are provided here:

http://www.cardgate.net/cardgate


4. Merchant Application Data Interchange The Merchant Application initiates all exchanges of messages with CardGate, passing a request to CardGate to perform a task. On completion of the task, CardGate passes back a response.

The response is written to a Record Of Transaction file and/or the socket interface (if this is where the request came from).

4.1 Record Structure Merchant Application requests and CardGate responses use simple tab delimited ASCII text records. The format of these records are:

a) fields made up of printable ASCII characters (ie 20h to 7Fh)

b) tab (<HT>) control characters (ie 09h) which act as field delimiters, and,

c) carriage return/line feed (ie 0Dh/0Ah) control character pairs that act as record delimiters.

This record format was chosen as it provides a universal format which is independent of machine, operating system and other program specifics.

4.2 CardGate Responses CardGate responses consist of :

a) ASCII representation of the raw response from the Bank host.

b) CardGate generated fields.

Each response field is prepended with a three ASCII digit "bit number" followed by the "=" symbol. For example, bit 11 is the systems trace audit number, an example being "011=123456".

Each field is returned in bit number ascending order, with bit "000" being the message type identifier. Refer to the Commonwealth Bank specifications for an explanation of bit numbers and the responses expected.

Bit numbers 900 and above are generated by CardGate, not the Bank network.

All fields may not necessarily be returned, eg bit 910 will only be returned when bit 039 is present.

Bit No Field Length Contents

900 Source ID ..20 From the request, eg "PC23"

901 Sequence number 6 From the request, eg "001345". Note, formatted to six digits, zero filled. So, in this example, the request could have had "1345".

902 Reference text ..40 From the request, eg "Invoice 123"

903 CardGate Error Code ..6 eg 20

904 CardGate Response Text ..80 eg "ERR CHECK DIGIT"

910 Bank suggested response

..80 Bank suggested message to display for the bank response given in bit 039 eg "Do not honour"

911 Primary Account Number ..19 Optional field (refer to flags in terminal definition file).

From the request. Is either the FULL PAN with blanks, etc removed. Eg "5353100000000000", OR,


the TRUNCATED PAN, eg first six digits, dot, last three digits of the PAN, eg "535310.001"(V3.8)

912 Expiry date 4 Optional field (refer to flags in terminal definition file).

From the request. YYMM format. (V3.2)

913 Card Type 2 Optional field (refer to flags in terminal definition file).

From the request. Is the first two digits of the PAN. (V3.8)

914 Client IP Address 11 Optional field (refer to flags in terminal definition file).

TCP/IP address in nnn.nnn.nnn format of the sockets client which made the request. (V3.8)

915 Client Port Address 5 Optional field (refer to flags in terminal definition file).

TCP/IP port number in nnnnn format of the sockets client which made the request. (V3.8)

916 Client user id ..16 Optional field (refer to flags in terminal definition file).

Authenticated user id.(V3.8)

917 Year 4 Optional field (refer to flags in terminal definition file).

Year returned by PC’s real-time clock.(V4.2)

920 Summary of Transactions “Merchant Side” totals sent out with Reconciliation request

930 Command response Response to immediate command (V3.2)


An example of a Record Of Transaction with no CardGate generated errors (prior to COMMLINK v2.32):

000=0210 003=003000 004=000000001250 011=006301 012 =092245 013=0113 015=1030 039=39 041=82121300 042=311000062121300 90 0=ME 901=001234 902=Invoice 123 910=NO CREDIT ACCOUNT

An example of a Record Of Transaction with no CardGate generated errors (COMMLINK v2.32 and higher) and extra fields 911, 912, 913 and 917:

000=0210 003=003000 004=000000002201 011=076687 012 =114212 013=0705 015=0621 038=999000 039=00 041=82121701 042=3110000 62121706 047=CCVM\ 900=0 901=000000 902=82755 910=Transaction Approved 911=456485xxxxxxx147 912=1301 913=45 917=2011

An example of a Record Of Transaction with a CardGate generated error:

900=001 901=001234 902=Invoice 123 903=20 904=Check Digit Invalid!

4.3 Requests Fields All requests to CardGate have five common fields : source id, sequence number, message type, merchant id and reference text.

4.3.1 Source ID When there are multiple Merchant Applications (ie clients) communicating with CardGate, the "source id" field is used to identify which client generated the request. This field is not used by CardGate for any other purpose other than providing traceability and therefore each client instance should be given a unique source id.

This field is always returned with the response unchanged.

4.3.2 Sequence Number A Merchant Application sends a request to CardGate with its own unique six digit sequence number to identify the request. CardGate responds to the request with the same sequence number and is used to determine which response it belongs to. A sequence number of "000000" means don't care and should only be used with file method of input for test purposes.

With file input, the unique sequence number is used to ensure that file transactions are not processed twice. The sequence number enables a request file to be partially processed, then input again into CardGate without fear that transactions will be doubly processed. This is achieved by holding the highest sequence number processed on file. If a higher sequence number is received, this number is stored to file, otherwise, if the number is less than that on file, it is rejected with the CardGate error code 21 - "Sequence number too low!". The file used to store these sequence numbers has the CAIC (merchant id) number as its name, eg "3110000612345.".

This field is returned with the response (beware that it may be reformatted).

4.3.3 Message Type The Message Type field is used to indicate the sort of request.

4.3.4 Merchant ID The Message ID (Card Acceptor Identification Code) is used by the host to determine which merchant the transaction is for.


4.3.5 Reference Text This field is simply returned with the response. It is use for private purposes by the Merchant Application, typically to provide a key to the originating transaction.

4.4 Non-Financial Authorisation / Financial Transaction Request / Warning Bulletin Lookup A non-financial authorisation request is where the card issuer's pre-approval of a transaction is sought. When this approval is given, an approval code is provided as proof of the approval. The pre-authorised transaction is not captured for settlement. This request is commonly referred to as a "Pre-Authorisation".

A financial transaction request is where the card issuer's approval of a sale transaction is sought. If approved, the transaction is used for settlement. This request is commonly referred to as "Financial or For Value" request.

With CardGate Version 3 and upwards, the "W" warning bulletin lookup message type has been added. This command instructs CardGate to verify the check digit of the card number, the expiry date and look up the optional Warning Bulletin file (refer to 2.2.3 Warning Bulletin file). With this command, a CardGate error response is always returned. If the card number passes all checks, INF_NO_WARNING will be returned; INF_WARNING_LIST if found in the warning bulletin file, INF_EXPIRY_DATE if the expiry date is not valid or INF_CHECK_DIGIT if the card number is in error.

As these requests require essentially the same data they are grouped together in this description.

Pos

Field Nam e Length Contents

0 Source ID ..20 Returned with response as bit number 900. This field is typically used as the Merchant Application originated source id that uniquely identifies which application or client generated this transaction, eg "PC23"

1 Sequence Number

6 Returned with response as bit number 901 (formatted as six digits, zero filled)

This is the Merchant Application originated transaction sequence number. When combined with the Source ID it uniquely identifies the transaction for a given online client. In the file method, it is used ensure that batches are not doubly processed for a given Merchant ID. This number remains unchanged throughout the duration of the transaction. The sequence number will be incremented by the Merchant Application for every new transaction. It starts from "000001" and increments upto "999999" and wraps around to "000001" again. "0" means don't care.

2 Message Type 1 "A" - Pre-Authorisation Request; "a" - Training Mode "F" - Financial Transaction Request; "f" - Training Mode "W" - CardGate Warning Bulletin lookup and Card Number / Expiry Date check


3 Card Acceptor Identification Code

15 Supplied by the bank. This code must be listed in the terminal configuration file.

4 Reference text ..40 Returned with response as bit number "902"

5 Transaction Type

1..

"S" – SALE "R" – REFUND (ONLY RELEVANT FOR MESSAGE TYPE "F") TO OVERRIDE THE DEFAULT POINT OF SERVICE CONDITION CODE (DE25) AS SET FOR THE FACILITY IN THE TERMINAL CONFIGURATION FILE, USE THE FOLLOWING FORMAT: “S: P” – SALE, SET DE25 ACCORDING TO P “R: P” – REFUND, SET DE25 ACCORDING TO P WHERE P IS: '0' - USE FOR CBA COMMLINK V2.2 AND LOWER (DE25=15) '1' OR ‘M’ - MAIL OR TELEPHONE ORDER (INCLUDING IVR, RECURRING AND NON-INTERNET BASED TRANSACTIONS) (DE25=08) '2' OR ‘E’ - ELECTRONIC COMMERCE/INTERNET (DE25=48) FOR EXAMPLE: “S:2” – E-COMMERCE/INTERNET SALE “S:M” – MAIL ORDER SALE

6 Primary Account Number

..19 eg "535001231123345". May contain blanks or "-" characters

7 Amount Transaction

..12 Whole cents eg "1234" for $12.34

8 Expiry Date 4 YYMM eg "9610"

9 Additional Data Optional. Refer to section “Additional Data”


Additional Data The optional “Additional Data” field in Non-Financial Authorisation and Financial Transaction requests is used to fill the AS2805 Data Element 47 , “Additional Data, National”. This Data Element is now mandatory in COMMLINK V2.32 and higher.

Data Element 47 consists of several sub-elements. Each sub data element consists of a three character tag, followed by data and terminated with the ‘\’ (backslash) character.

E-commerce transactions are required to include CCV and SLI tags.

Other transactions such as mail/telephone order are encouraged to also capture CCV data however this is optional and CCV and SLI tags can be omitted when CCV is not captured.

ECM tag must be provided for e-commerce, moto, recurring transactions for all card types (Visa, MasterCard, Amex, JCB, Diners), ie for all COMMLINK transactions.

When used, this field shall contain the following information, in the order set out below:

TAG TAG NAME ATTRIBUTE COMMENT CCV Card Check Value AN 8 Value ‘CCVxxxx\’ where xxxx is the CVV2/CVC2/CID value.

The length of the entered value is variable and is terminated by the ‘\’ character. Typically, the CCV is three digits except for Amex which is 4 digits, although there is no standard defined length.

CCI Card Check Indicator AN 5 Value ‘CCIn\’ is used as CCV presence indicator. Where ‘n’ can contain the following values: 0 – CCV value is not provided 1 – CCV value is present 2 – CCV value is on the card but is illegible 9 – Cardholder states that the card has no CCV printed

ECM Electronic commerce and Mail/Telephone order Indicator

AN 6 Value ‘ECMmt\’ is used as e-commerce/moto/recurring indicator. Where ‘m’ can contain the following values: 0 – Unknown 1 – Telephone order (eg call centre, IVR) 2 – Mail order 3 – Internet order And where ‘t’ can contain the following values: 0 – Unknown 1 – Single transaction 2 – Recurring transaction

SLI Security Level Indicator

AN 6 Value ‘SLInn\’ is used as CCV presence indicator. Where ‘nn’ can contain the following values: 00 – Not applicable 05 – Authenticated secure electronic commerce transaction (Not relevent for COMMLINK transactions) 06 – Non Authenticated secure e-comm where card acceptor is

certified to perform authentication (Not relevent for COMMLINK transactions) 07 – Non Authenticated secure e-comm where card

authentication cannot be performed. Other security mechanisms may be present. Ex: channel encryption (eg SSL, SSH)

08 – Non-secure transaction in the clear over an open network (eg call centre, IVR, mail order)


CardGate simplifies filling of Data Element 47:

1. No Additional Data field provided in the request: the “Additional Data” flags set in the CardGate terminal configuration file terminalv4.txt for the facility is used to configure the Data Element 47 sub-elements.

Mail Order/Telephone Order transactions (as indicated by “Additional Data – ECM tag – first (m )value” config flag) will have the ECM tag only. Internet Order (ie Electronic Commerce) transactions will have CCI, ECM and SLI tags.

This maintains compatibility for CardGatev4 clients who would naturally not be supplying the Additional Data field.

2. Additional Data field comprises numeric digits for the CCV (Card Check Value) (variously known as CVC, CVC2, CVV2 and CID): the “Additional Data” flags set in the CardGate terminal configuration file terminalv4.txt for the facility are used to configure Data Element 47 sub-fields.

Mail Order/Telephone Order transactions (as indicated by “Additional Data – ECM tag – first (m )value” config flag) will have CCV, CCI and ECM tags. Internet Order (ie Electronic Commerce) transactions will have CCV, CCI, ECM and SLI tags.

This method will be used by the majority of merchants who have dedicated a merchant facility to a specific delivery channel (eg the facility is used solely for e-commerce processing).

3. Additional Data comprises verbatim Data Element 47 sub-elements. For example “CCV1234\CCI1\ECM31\SLI07\”.

This method will be used by merchants who have different transaction delivery channels using a single merchant facility.

Merchants are encouraged to seek CardGate.net advice in implementing CSC and setting the Additional Data flags in the terminal configuration file and Data Element 47 sub-elements appropriately.


4.4.1 Authorisation /Financial Transaction Response The following is CardGate's response to an authorisation request/financial transaction request, when there is no CardGate generated error.

For sockets interface requests, CardGate optionally writes the response to a "Record Of Transaction" log file named after the requesting Merchant ID appended with the ".ROT" extension, eg "311000062121706.ROT". This option is enabled in the flags field in the terminal.txt configuration file.

Note that the fields with bit numbers 0 to 128 are what the bank returns and are not manipulated by CardGate (other than reformatting them into ASCII and appending the bit number). The Commonwealth Bank specification should be referred to.


000 Message Type 4 "0110" for Non-Financial Authorisation Request Response "0210" for Financial Transaction Request Response "0430" for Reversal Advice Response

003 Processing Code 6 as set in the request (hidden), ie "003000" for transaction authorisation or sale transaction. "203000" for refund "223000" for void of transaction

004 Amount Transaction 12 eg "000000001234" for $12.34 as in request

011 Systems Trace Audit No.

6 Uniquely identifies the transaction as in request (hidden)

012 Time, local transaction

6 hhmmss eg "120254"

013 Date, local transaction

4 mmdd eg "1129"

015 Date Settlement 4 mmdd eg "1130" Date on which settlement with the merchant is to occur.

037 Retrieval Reference No.

12 This number is generated by the host and shall be used to reference a transaction for further processing.

038 Authorisation ID response

6 When the Response Code is "00" (approved), this field contains the approval code for the transaction. When the Response Code is "02", this field contains the Bank referral number. This field will not be present for Message Type "0430" - Reversal Advice Response

039 Response Code 2 See Appendix A for details eg "05".

041 Card Acceptor System ID

8

042 Card Acceptor Id Code

15

044 Additional Response Data

..25 This optional field may contain the identity of the host system that generated the response as follows: "00" – unspecified "01" - Response from terminal host "02" - Response from stand-in processor.

047 Additional Data National

… When the request message contains CCV data, this data element shall be used to carry the CCV verification response provided from the issuer. The sub data element used consists of a 3 character


code, followed by the data and terminated by the ‘\’ character.

When used, this field shall contain the following information:

Value ‘CCVx\’ where x is the CCV verification result code and can contain the following values:

M – matched N – not matched P – not processed S – Suspicious/CCV should be on card U – CCV unverified (Mastercard use) / Issuer is not Visa certified for CCV (Visa use)

900 Source ID ..20 From the request

901 Sequence Number 6 From the request but formatted as six digits, zero filled.

902 Reference ..40 From the request

910 Response Text ..80 Generated by CardGate. Provides textual description to Bank response code. See Appendix A eg "DO NOT HONOUR"


..19 Optional field (refer to flags in terminal definition file).

From the request. Is either the FULL PAN with blanks, etc removed. Eg "5353100000000000", OR, is the TRUNCATED PAN, ie the first six digits, dot, last three digits of the PAN, eg "535310.001" (V3.2)

912 Expiry Date 4 Optional field (refer to flags in terminal definition file).













4.4.2 Authorisation / Financial Acknowledgment When using the sockets method for interfacing with CardGate, it is the Merchant system's responsibility to positively acknowledge reception of an Authorisation or Financial Response from CardGate.

This requirement for positive acknowledgment is imposed by CardGate. The methodology has been designed to ensure that the Merchant system has concluded the transaction, and has left the card holder understanding the outcome of the transaction. This is particularly important in fully automated Internet and Interactive Voice Response systems. For example, if a card holder prematurely hangs up a call before the Bank response is received, then the Merchant system should not accept payment as the service has not been delivered.

Upon receiving a Bank a "0110" or "0210" message type response to an Authorisation or Financial request, the Merchant system must acknowledge reception by sending a 'C' positive acknowledgment message as detailed below.

If this message is not received by CardGate within 30 seconds, or a 'V' negative acknowledgment message is sent instead of the 'C' message, the original request is automatically reversed (ie a 0420 message is sent). A reversal with response code of 00 means that the financial capture was cancelled with the Bank. Note that for successful authorisation/financial request the authorisation (ie reservation of funds) is NOT cancelled by a reversal.

Upon initiating a reversal, CardGate will send the socket a reversal pending message (see the next section) to the Merchant Application. When the reversal is concluded by the Bank, it will respond with a 0430 'Reversal Advice Response' message.

Field No Field Length Contents

0 Source ID ..20 As in the request.

1 Sequence Number 6 As in the request

2 Message Type 1 "C" - Confirm (ie Positive Acknowledgment)

"V" – Reverse Financial request (ie Negative Acknowledgment)



4 Card Acceptor Terminal ID

8 For Message Type ‘C’ only. This field is optional but it is should be used .

If the CATID field is supplied, then this is used instead of the Source ID and Sequence Number fields to identify which Virtual Terminal to clear.

5 Systems Trace Audit Number

6 Indicates that this is an “Enhanced Confirm” command (V4.06)

This is the STAN of the transaction that is being confirmed. Will ellicit a response from CardGate.


Here is an example of the message protocol:

Merchant App CardGate Host Comments Case 1 – normal ‘F’Request 1 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 Record Of Transaction Received by merchant ‘C’ -> Confirm command Trans#1 completed Case 2 – negative ack ‘F’Request 2 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 Record Of Transaction Cardholder hangs up or message not received ‘V’ -> Negative acknowledgement <-903=25 904=Reversal Pending CardGate Response 0420 -> Reversal Request <- 0430 Reversal Response <-000=0430 Record Of Transaction Trans#2 reversed Case 3 – no ack ‘F’Request 3 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 Record Of Transaction Cardholder hangs up or message not received 30 seconds No acknowledgement <-903=25 904=Reversal Pending CardGate Response 0420 -> Reversal Request <- 0430 Reversal Response <-000=0430 Record Of Transaction Trans#3 reversed

4.4.2.1 Enhanced Confirm

The “Enhanced Confirm ” command has been added with Version 4.06 of CardGate. It is designed for use when there is, for example, unreliable socket communications (eg via the Internet) between the Merchant Application and the CardGate payment gateway. When this command is used, CardGate will acknowledge receipt of the command by responding with a CardGate Response, ie an acknowledgement of the acknowledgement.

The normal Confirm command is changed to a Enhanced Confirm command by adding the STAN in field five.


Here is an example of the message protocol using the “Enhanced Confirm ” command:

Merchant App CardGate Host Comments Case 4 – normal ‘F’Request 4 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 011=000004 Record Of Transaction Received by merchant ‘C’…’000004’ -> Enhanced Confirm <-903=60 904=OK Trans#4 committed so CardGate Acknowledges Confirm received Trans#4 completed Case 5 – Confirm not received by CardGate ‘F’Request 5 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 011=000005 Record Of Transaction Received by merchant ‘C’…’000005’ -X Enhanced Confirm sent Not received by CardGate! 10 second timeout No response received by Merchant – resends after 10 second timeout. ‘C’…’000005’ -> Enhanced Confirm resent <-903=60 904=OK Trans#5 committed so CardGate Acknowledges Confirm Received Trans#5 completed Case 6 – CardGate Acknowledgement not received ‘F’Request 6 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 011=000006 Record Of Transaction Received by merchant ‘C’…’000006’ -> Enhanced Confirm sent X- 903=60 904=OK Trans#6 committed so CardGate Acknowledges Confirm Received, BUT it is not received by merchant 10 second timeout No response received by Merchant – resends after 10 second timeout. ‘C’…’000006’ -> Enhanced Confirm resent <-903=60 904=OK CardGate Acknowledges Confirm Received Trans#6 completed


Case 7 – Late Enhanced Confirms ‘F’Request 7 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 011=000007 Record Of Transaction ‘C’…’000007’ -X Enhanced Confirm sent but N ot received by CardGate! 10 second timeout No response received by Merchant – resends after 10 second timeout. ‘C’…’000007’ -X Enhanced Confirm resent but N ot received by CardGate! 10 second timeout ‘C’…’000007’ -X Enhanced Confirm resent but N ot received by CardGate! 10 second timeout ‘C’…’000007’ -X Enhanced Confirm resent but N ot received by CardGate! 10 second timeout As Enhanced Confirm not received by Cardgate 30 sec CardGate timeout <-903=25 904=Reversal Pending CardGate Response 0420 -> Reversal Request ‘C’…’000007’ -> Late Enhanced Confirm sent <-903=25 904=Reversal Pending CardGate Response <- 0430 Reversal Response <-000=0430 Record Of Transaction Trans#7 reversed ‘C’…’000007’ -> Late Enhanced Confirm sent <-903=7 904=SLOT CLASH CardGate Response ‘F’Request 8 -> 0200 -> Financial Request <- 0210 Financial Response <-000=0210 011=000008 Record Of Transaction Received by merchant ‘C’…’000007’ -> Late Enhanced Confirm sent (note STAN is for tran#7 not 8) <-903=51 904=STAN not found! CardGate Response 30 sec CardGate timeout <-903=25 904=Reversal Pending CardGate Response <- 0430 Reversal Response <-000=0430 Record Of Transaction Trans#8 reversed

In summary, CardGate responses to the Enhanced Conf irm command are:

Response Code (field 903)

Response Text (field 904)

Meaning

60 OK Transaction completed okay

25 Reversal Pending Transaction is about to be reve rsed

7 SLOT CLASH Transaction has been reversed

51 STAN not found! A new transaction has been initiated on this terminal


4.4.3 Reversals Whenever the host does not respond to a 0100 or 0200 request within a 30 second timeout period, or the confirm command has not been received from the merchant application, CardGate will automatically send a reversal request message to the host. With sockets connections, upon initiating a reversal, CardGate will also send a "reversal pending" (error code 25) error message to the Merchant Application socket so that it may continue on with other processing if desired.

Should a reversal advice response from the host not be received within the agreed timeout period, a repeat reversal request message shall be sent at regular intervals until a response is received. After five minutes of no response, the transaction is classed as "sticky" and reported to the record of transaction file or online sockets connection with a CardGate error “Sticky transaction, possibly stuck” (error code 23). After 30 minutes of no response, the sending of repeat reversal requests is aborted and the transaction is marked as "stuck" and reported to the Windows Event Logging service as well as the record of transaction file or sockets connection as a CardGate error “Stuck transaction being cleared from system! REPORT DETAILS TO BANK!” (error code 24). [Note that merchants typically do not report stuck transactions to the Bank!]

Note that for successful authorisation/financial request the authorisation (ie reservation of funds) is NOT cancelled by a reversal, just the financial capture.


4.5 Financial Capture Transaction Request A financial capture transaction request is where the card issuer's approval of a sale transaction is sought. If approved, the transaction is used for settlement.

This request is commonly referred to as an "Offline Transaction", or “Forced Post Auth”.

Pos

Field Name Length Contents

0 Source ID ..20 Returned with response as bit number 900. This field is typically used as the Merchant Application originated source id that uniquely identifies which application or client generated this transaction, eg "PC23"

1 Sequence Number

6 Returned with response as bit number 901, formatted as six digits, zero filled.

This is the Merchant Application originated transaction sequence number. When combined with the Source ID it uniquely identifies the transaction for a given online client. In the file method, it is used ensure that batches are not doubly processed for a given Merchant ID. This number remains unchanged throughout the duration of the transaction. The sequence number will be incremented by the Merchant Application for every new transaction. It starts from "000001" and increments upto "999999" and wraps around to "000001" again.

"0" means don't care.

2 Message Type 1 "O" - Financial Capture Transaction Request "o" - Training Mode - Financial Capture Transaction Request



4 Reference text ..40 Returned with response as bit number "902"

5 Transaction Type

1 "S" - Sale "R" – Refund To override the default Point Of Service Condition Code (DE25) as set for the facility in the terminal configuration file, use the following format: “S:p” – Sale, set DE25 according to p “R:p” – Refund, set DE25 according to p where p is: '0' - use for CBA COMMLINK v2.2 and lower (DE25=15) '1' or ‘M’ - Mail or telephone order (including IVR, recurring and non-internet based transactions) (DE25=08) '2' or ‘E’ - Electronic Commerce/Internet (DE25=48) For example: “S:2” – e-Commerce/Internet sale “S:M” – Mail order sale


..19 eg "535001231123345". May contain blanks or "-" characters

7 Amount ..12 Whole cents eg "1234" for $12.34


Transaction

8 Expiry Date 4 YYMM eg "9610"

9 Authorisation ID 6 Optional field. Should be used where possible. Alphanumeric approval code - assumed to be the same as that for a prior authorisation (bit 38).

10 Additional Amount

..12 This optional field may contain the tip amount. The tip amount is included in the amount transaction. Whole cents eg "100" for $1.00

11 Additional Data Optional. Refer to section “Additional Data”


Additional Data The optional “Additional Data” field in Financial Capture requests is used to fill the AS2805 Data Element 47 , “Additional Data, National” field. This field is now mandatory in COMMLINK V2.32 and higher.

Data Element 47 consists of several sub-elements. Each sub data element consists of a three character tag, followed by data and terminated with the ‘\’ (backslash) character.

E-commerce transactions are required to include SLI tags.

Other transactions such as mail/telephone order are encouraged to also capture CCV data however this is optional and CVV and SLI tags can be omitted when CCV is not captured.

ECM tag must be provided for e-commerce, moto, recurring transactions for all card types (Visa, MasterCard, Amex, JCB, Diners), ie for all COMMLINK transactions.

When used, this field shall contain the following information, in the order set out below:

TAG TAG NAME ATTRIBUTE COMMENT ECM Electronic commerce

and Mail/Telephone order Indicator

AN 6 Value ‘ECMmt\’ is used as e-commerce/moto/recurring indicator. Where ‘m’ can contain the following values: 0 – Unknown 1 – Telephone order (eg call centre, IVR) 2 – Mail order 3 – Internet order And where ‘t’ can contain the following values: 0 – Unknown 1 – Single transaction 2 – Recurring transaction

SLI Security Level Indicator

AN 6 Value ‘SLInn\’ is used as CCV presence indicator. Where ‘nn’ can contain the following values: 00 – Not applicable 05 – Authenticated secure electronic commerce transaction (Not relevent for COMMLINK transactions) 06 – Non Authenticated secure e-comm where card acceptor is

certified to perform authentication (Not relevent for COMMLINK transactions) 07 – Non Authenticated secure e-comm where card

authentication cannot be performed. Other security mechanisms may be present. Ex: channel encryption (eg SSL, SSH)

08 – Non-secure transaction in the clear over an open network (eg call centre, IVR, mail order)

CardGate simplifies filling of Data Element 47:

1. No Additional Data field provided in the request: the “Additional Data” fields set in the CardGate terminal configuration file terminalv4.txt for the facility is used to configure the ECM, CCI, and SLI Data Element 47 sub-fields. This maintains compatibility for CardGatev4 clients who would naturally not be supplying the Additional Data field and the majority of CardGatev5 merchants who have dedicated a merchant facility to a specific delivery channel (eg facility used solely for e-commerce or recurring processing).

2. Additional Data comprises verbatim Data Element 47 sub-elements. For example “CCV1234\CCI1\ECM31\SLI07\”. This method will be used by merchants who have different modes/delivery of traffic over a single merchant facility.

Merchants are encouraged to seek CardGate.net advice in implementing CSC and setting the Data Element 47 sub-elements appropriately.


4.5.1 Financial Capture Response The following is CardGate's response to a financial capture transaction request, when there is no CardGate generated error.


000 Message Type 4 "0230" for Financial Capture Response

003 Processing Code 6 As set in the request (hidden), ie "003000" for sale completion or offline sale transaction; "203000" for an off-line refund transaction.

004 Amount Transaction 12 eg "000000001234" for $12.34 as in request

011 Systems Trace Audit No.

6 Uniquely identifies the transaction as in request (hidden)

012 Time, local transaction 6 Hhmmss eg "120254"

013 Date, local transaction 4 Mmdd eg "1129"

015 Date Settlement 4 Mmdd eg "1130" Date on which settlement with the merchant is to occur.

037 Retrieval Reference No.

12 This field is optional (typically not returned). This number is generated by the host and shall be used to reference a transaction for further processing. It is assumed that the retrieval reference number for these transactions will be the same number used on any prior authorisation or transaction



8

042 Card Acceptor Id Code

15

044 Additional Response Data

..25 This optional field may contain the identity of the host system that generated the response as follows: "00" - unspecified "01" - Response from host "02" - Response from stand-in processor




910 Response Text ..80 Generated by CardGate. Provides textual description to Bank response code. See Appendix A eg "APPROVED"


..19 Optional field (refer to flags in terminal definition file). From the request. Is either the FULL PAN with blanks, etc removed. Eg "5353100000000000", OR, is the TRUNCATED PAN, ie the first six digits, dot, last three digits of the PAN, eg "535310.001" (V3.2)

912 Expiry Date 4 Optional field (refer to flags in terminal definition file).














4.5.2 Financial Capture Response Acknowledgment When using the sockets method for interfacing with CardGate, it is the Merchant system's responsibility to positively acknowledge reception of a Financial Capture Response from CardGate.

This requirement for positive acknowledgment is imposed by CardGate. Upon receiving a Bank a "0230" message type response to a Financial Capture request, the Merchant system must acknowledge reception by sending a 'C' positive acknowledgment message as detailed below.

For 0230 Financial Capture responses, if the 'C' positive acknowledgement message is not received by CardGate within 30 seconds, the original request is automatically repeated (ie sent as a 0221 Financial Capture Repeat).

Pos




2 Message Type 1 "C" - Confirm receipt (ie Positive Acknowledgment)




8 This field is optional but it is preferred that it is used.


Note that the 0220 messages protocol is fundamental ly different to the protocol used with 0100/0200 messages. Here repeat messages (0221 ) are sent UNTIL a 0230 response is received. There is no "reversal" capabi lity.

This means that if the Merchant Application does no t get a response for whatever reason, it should not re-send the offline transacti on as it may cause the cardholder to be multiply debited as there is a possibility that the Bank has responded to the stuck transaction. Please contact CardGate.net for furthe r advice.

Here is an example of the message protocol:

Merchant Application CardGate Comments

"O" Request 1 � 0220 Request sent to Bank

0230 Bank Response

Response 1 Received ok

Positive Acknowledgment � Transaction 1 completed ok

"O" Request 2 � 0220 Request sent to Bank

0230 Bank Response

Message not received by Merchant

No acknowledgment � 0221 Request Repeat sent to Bank

0230 Bank Response Transaction 2 completed


4.6 Reconciliation Advice A reconciliation advice is sent to the host to advise that the Merchant has changed business days.

Pos

Field name Length Contents

0 Source ID ..20

1 Sequence Number 6

2 Message Type 1 "R" - Reconciliation Advice


15

4 Reference text ..40

5 Card Acceptor Terminal Id

8 eg "82517000"

6 Settlement Date 4 mmdd. The date on which settlement with the merchant is to occur, eg "1130". This field is optional. If left out, CardGate will send the system date.

7 Summary Of Transactions

36 This field shall contain information from the Merchant's point of view: Debit count - 6 chars - the number of debits accumulated. Debit amount - 12 chars - the total amount of debit transactions in the system (ie accumulation of the amount transaction fields of all debit transactions) Credit count - 6 chars - the number of credits accumulated. Credit amount - 12 chars - the total amount of credit transactions in the system (ie accumulation of the amount transaction fields of all credit transactions)

If this field is left blank, then CardGate will use its own internally maintained Summary Of Transactions record.

New file name 0 ..40 Optional parameter. If this parameter is provided, it indicates to rename the record of transaction file (which, for online transactions is CAIC.ROT where CAIC is the CAIC number eg 311000062000000.ROT, or, for Batch transactions, the name of the request file) in Response Directory 0 to contents of this field AFTER receipt of the reconciliation response from the Bank. (V3.2)

9 New file name 1 ..40 Optional parameter. As field 8, but for Response Directory 1. (V3.2)

10 New file name 2 ..40 Optional parameter. As field 8, but for Response Directory 2. (V3.2)


4.6.1 Reconciliation Response The following is CardGate's response to an reconciliation advice request when there is no CardGate generated error.


000 Message Type 4 "0530" for Reconciliation Response

011 Systems Trace Audit No. 6 Uniquely identifies the transaction as in request (hidden)

012 Time, local transaction 6 hhmmss eg "120254"

013 Date, local transaction 4 mmdd eg "1129"

015 Date Settlement 4 mmdd eg "1130"



8

042 Card Acceptor Id Code 15

062 Summary Of Transactions number

063 Summary Of Transactions

36 This field shall contain information from the host's point of view:

Debit count - 6 chars - the number of debits accumulated. Debit amount - 12 chars - the total amount of debit transactions in the system (ie accumulation of the amount transaction fields of all debit transactions) Credit count - 6 chars - the number of credits accumulated. Credit amount - 12 chars - the total amount of credit transactions in the system (ie accumulation of the amount transaction fields of all credit transactions)




910 Response Text ..80 Generated by CardGate. Provides textual description to Bank response code. See Appendix A

920 Merchant View Summary of Transaction

This field shall contain information from the Merchant's point of view: Debit count - 6 chars - the number of debits accumulated. Debit amount - 12 chars - the total amount of debit transactions in the system (ie accumulation of the amount transaction fields of all debit transactions) Credit count - 6 chars - the number of credits accumulated. Credit amount - 12 chars - the total amount of credit transactions in the system (ie accumulation of the amount transaction fields of all credit transactions)


4.6.2 Reconciliation Response Acknowledgment When using the sockets method for interfacing with CardGate, it is the Merchant system's responsibility to positively acknowledge reception of a Reconciliation Response from CardGate.

This requirement for positive acknowledgment is imposed by CardGate. Upon receiving a Bank a "0530" message type response to a Reconciliation request, the Merchant system must acknowledge reception by sending a 'C' positive acknowledgment message as detailed below.

For 0530 Reconciliation responses, if the 'C' positive acknowledgement message is not received by CardGate within 30 seconds, the original request is automatically repeated (ie sent as a 0521 Reconciliation Repeat).

Pos




2 Message Type 1 "C" - Confirm receipt (ie Positive Acknowledgment)




8 This field is optional but it is preferred that it is used.


Note that the 0520 messages protocol is fundamental ly different to the protocol used with 0100/0200 messages. Here repeat messages (0521 ) are sent UNTIL a 0530 response is received. There is no "reversal" capabi lity.

4.6.3 Settlement Options There are a number of options for settlement with the Bank's host.

a) Forced by the Bank. This occurs at roughly 2145hrs each banking day. With this option the Bank does not send a specific message to the Merchant containing totals. To obtain the totals, the Merchant must issue a reconcile request after the reconciliation has occurred.

b) Fixed Time. This operates as above but occurs at time nominated by the Merchant (between 0100hrs and 2145hrs).

c) Your Option. Settlement request is initiated by the Merchant at a time of their choosing, which the Bank responds to with a totals message.

In every case the Merchant will know that settlement has occurred because the settlement date field (bit 015) of the NEXT transaction will have "clicked over" to the following business day.


4.7 CardGate Immediate Commands With Version 3, "immediate commands" have been introduced. These allow commands to be sent to CardGate in a similar fashion to the Bank transaction requests. Typically these would be sent from a Telnet session to the Listen Port, which is typically port 4000.

All immediate commands have the following format:

Pos

Field name Length Contents

0 Source ID ..20 Returned with response as bit number 900.

1 Sequence Number 6 Returned with response as bit number 901

2 Message Type 1 "0" - CardGate Immediate Command

3 Sub Command 1 See table below

4 Parameter 1 ..20 Optional - depends on sub-command




Sub Command

Description

C Close (ie shutdown) CardGate application. (V3.8)

Authentication level “system control” required to perform this command.

Parameter 1 is mandatory and is the exit code to be used by the program.

Returns response codes: INF_INVALID – Parameter 1 missing INF_FAIL – not authorised to perform this command INF_OK

F Set flags/variables. (V3.7). Parameter 1 indicates which volatile variable to set to Parameter 2. Parameter 1 meanings: 0 – don't set any variable - return values of each variable. 1 - set CommsLog to Parameter 2 2 - set DebugLog to Parameter 2 3 - set OnlineLog to Parameter 2

Command Response field 930 is returned with further fixed length, comma delimited and labelled status fields: CommsLog[1]=n,DebugLog[2]=n,OnlineLog[3]=n

Returns response codes: INF_FAIL – not authorised to perform this command INF_INVALID - Parameter 1 invalid INF_OK

G Global status of CardGate. (V3.2) Returns response code : INF_OK Command Response field 930 is returned with a comma delimited and labelled fields:

dd/mm/yy hh:mm:ss.mmm, Sockets=n, Active=n, ReversalPend=n, Stuck%=n, Approved=n, Declined-01=n, Declined-05=n, Declined-91=n, Uptime=n


Where:

dd/mm/yy hh:mm:ss.mmm – current time and date

Sockets is the number of socket connections

Active is the number of transacting virtual terminals

ReversalPend is the number of outstanding reversals

Stuck% is the percentage of transactions that are currently being reversed ie ReversalPend * 100/Active

Approved is the number of transactions approved since CardGate started

Declined-nn is the number of transactions declined with response code nn since CardGate started

Uptime is the number of seconds since CardGate was started.

H Hold All - forces all virtual terminals to return BUSY when a request is made. Returns response codes : INF_FAIL – not authorised to perform this command INF_OK INF_PENDING – at least one terminal was pending a response

H Hold Merchant Facility (Parameter 1 = CAIC) - forces all virtual terminals associated with merchant id CAIC to return BUSY when a request is made. (V4.2) Returns response codes : INF_FAIL – not authorised to perform this command INF_OK INF_PENDING – at least one terminal was pending a response INF_INVALID – Merchant id/CAIC not found


K Kill stuck terminal (Parameter 1=CATID)- ie stops repeating reversals and logs to EventLog. (V3.05) Returns response codes: INF_FAIL – not authorised to perform this command INF_INVALID if CATID not found INF_OK

L Login /logout user. (V3.09)

If logged in and no parameters, then this command logs out the user.

Parameter 1=user id Parameter 2=authenticator Parm3=random (optional) Parm4=encryption key (optional) – indicates to encrypt this channel Returns response codes: INF_FAIL – not authorised to log in INF_INVALID – number of paramaters incorrect INF_OK – logged in okay

M Get Modem Status (Parameter 1 empty or 0). Returns response codes: INF_NOT_READY - hung up INF_PENDING – is dialling INF_REVERSAL_PENDING – online, but last transaction is reversal pending INF_OK – online

M Hangup Modem (Parameter 1 = 1). Returns response codes: INF_FAIL – not authorised to perform this command INF_OK

M Dial Modem (Parameter 1 = 2). Returns response codes: INF_FAIL – not authorised to perform this command INF_OK

N Rename file Parameter 1 in all three response sub-directories. (V3.5) Parameter 2 = new name for ResponseDirectory0 file Parm3 = new name for ResponseDirectory1 file Parm4 = new name for ResponseDirectory2 file Returns response codes: INF_OK INF_FAIL.

Q Closes the socket that this request has come from. (V3.3) Returns response code: INF_PEND.

R Release All – releases all virtual terminals from the Hold state. Returns response code: INF_FAIL – not authorised to perform this command INF_OK

R Release Merchant Facility (Parameter 1 = CAIC) - releases all virtual terminals associated with merchant id CAIC from the Hold state. (V4.2) Returns response code: INF_FAIL – not authorised to perform this command INF_OK INF_INVALID – Merchant id/CAIC not found


S Return status of Virtual Terminal (Parameter 1 = CATID or virtual terminal number (1..)). (V3.2)

Returns response codes: INF_FAIL – not authorised to perform this command INF_INVALID – Terminal number/CATID not found INF_NOT_READY - waiting for host connection INF_IDLE – Ready INF_PENDING – Waiting on response INF_REVERSAL_PENDING - Waiting on reversal response

Command Response field 930 is returned with further fixed length, comma delimited and labelled status fields:

dd/mm/yy hh:mm:ss.mmm - current date & time CATID=nnnnnnnn - CATID of terminal being interrogated STAN=nnnnnn – Systems trace audit number InUse=n - 0 if idle, 1 if in use State=nn - where nn = 00 NOT READY 1 01 WAIT LOGON 02 READY 03 WAIT RESPONSE 04 reserved 05 WAIT ACK 06 NOT READY 2 07 WAIT ADVICE RESPONSE 08 NOT READY 3

Retries=nnn – number of retries SecsLeft=nnn – countdown timer - seconds before timeout Debits=nnnnnnnnn - number of debit transactions since last forced reconciliation DebitAmt=nnnnnnnnnnnn - amount in cents of debit transactions since last forced reconciliation Credits=nnnnnnnnn - number of credit transactions since last forced reconciliation CreditAmt=nnnnnnnnnnnn - amount in cents of credit transactions since last forced reconciliation Label=aaaaaaaaaaaaaaaaaaaa - comment field from terminal.txt

U Update virtual terminals from terminal.txt file. (Parameter 1 empty or 0) (V3.6) Returns response codes: INF_BUSY - if could not proceed due to terminals being busy INF_FAIL – not authorised to perform this command INF_OK.

U Update access control list from cardgate.acl file. (Parameter 1 not 0) (V3.9) Returns response codes: INF_FAIL – not authorised to perform this command INF_OK

V Add virtual terminal to terminal.txt file. (V3.7) Parameters 1onwards represent each tab delimited field in the text file, ie Parameter 1= CAIC, Parameter 2=CATID, Parm3=Key, Parm3=Flags, Parm4=Comment, Parm5=Spare Returns response codes INV_INVALID - not enough fields (must have at least Parameter 1..Parm3) INF_OK


For example, to hang up the modem, issue the following:

0 0 0 M 1

The response would be:

900=0 901=000000 902=CMD[M,1,0,,,] 903=60 904=OK 914=127.0.0.1 915=3814 916=myid

To return the status of virtual terminal with CATID 82512345, issue this:

0 0 0 S 82512345

If the state of the virtual terminal is waiting for a reversal, the response would be:

900=0 901=000000 902=CMD[S,82512345,,,] 903=25 904=Reversal Pending! 914=127.0.0.1 915=3814 916=myid 930=20/04/2001 17:48:03.172,CATID=82512345,STAN=001234,Inuse=1,Ret ries=001,Secs=010,Debits=000000231,DebitAmt=000001234567,Credit s=0,CreditAmt=000000000000,Label=Dev


4.8 Training Mode / Host Emulation To aid in the integration process, CardGate provides Training Mode with the Pre-Authorisation, Financial and Financial Capture transactions. Here, Bank responses are emulated when the appropriate message type (ie "a", "f" or "o") is used. Note that for sockets communications, the emulated response is NOT saved to the Record Of Transaction file, thereby allowing Training Mode to be safely used with a LIVE CardGate system for development and training purposes.

Test Mode is another integration facility provided by setting the registry entry "Test Mode" to 1. Here CardGate emulates host responses for ALL requests put to it.

With both Training and Test modes, the responses will differ from a live response in a number of ways.

A) The Systems Trace Audit Number is "000000", which is illegal in the LIVE system.

B) Bit 37, Retrieval Reference Number, is returned for approved transactions as "999999999999". It is typically not returned in LIVE responses.

C) Bit 38 is not returned for approved transactions, whereas it typically is in LIVE responses.

D) The response will consistently come back within 2 seconds.

Training and Test modes were not designed to be used for advanced testing of Merchant Systems. The Bank's development system should be used for this. It was provided to assist in the early stages of systems integration and debugging. For example, Training and Test Modes don't handle reversals or reconciliation requests.

When the Success Rate registry value is set to 0, if the card number ends in an even digit (eg 0, 2, 4…) the transaction will be TEST APPROVED. If the card number ends in an odd digit (eg 1, 3, 5 …) the cents portion of the amount determines the emulated response code 39. For example, $1.05 will return response code 05. The following cent portion values return non numeric response codes:

85 Q5 86 Z2 87 Z3 88 NO 89 N7

A cents portion value of 99 will emulate non-response from the Bank. Also, the last digit of the amount is also used to determine the DE47, Additional Data, response for emulated declined transactions:

7 CCVP\ 8 CCVS\ 9 CCVU\ Otherwise CCVN\


5. Traceability, Logging and Anomalies

5.1 CardGate Record Of Transaction Log CardGate keeps a Record Of Transaction (ROT) log file of all bank responses and CardGate error responses for rejected requests for batch files. Record of Transaction files are also optionally written for sockets connections (as flagged in the terminal.txt configuration file) (this is highly recommended).

Each of these log records has the Merchant Application's originating source id/sequence number and Merchant Application's originating reference text appended.

The bank traces transactions by way of the Systems Trace Audit Number (STAN) and the Card Acquirer Terminal ID (CATID) pair. These numbers are assigned by CardGate to each request sent to the bank.

Transactions can be traced through the system from the Merchant Application's end by using the reference text (typically a customer or invoice number) and matching it in the Record Of Transaction log to the assigned CATID and STAN. Conversely, given a transaction from the bank side, using the CATID and STAN, one can trace this back to the originating request.

5.2 Monitor Log CardGate optionally maintains a local time stamped log file of high level transactional details. It is a standard ASCII text file that can be viewed with the Windows Notepad text editor. This log file is "MONITOR_YYYYMMDD.TXT" (where YYYYMMDD represents the date).

It is recommended that this logging facility be enabled as it proves most useful in tracking down production issues. To enable it, you set the registry value “Debug Log” to 1.

Each line in the log is time stamped and represents an activity of note. Here is a typical line:

04/04/2005 13:00:49.653 Tx(0100,23000001,000011,00, test)

The activities logged are:

Meaning Template

Message sent to host Tx(MessageType,CATID,STAN,00,C omment) Eg: Tx(0200,82121700,010094,00,DEV)

Message received from host Tx(MessageType,CATID,STA N,ResponseCode,Comment) Eg: Rx(0210,82121700,010094,56,DEV)

Acknowledgement from Merchant Application

Ak(Type,CATID,STAN,Comment) Where type = CONF, CONFE, VOID, VOIDE, NONE, LATE, BADSTAN Eg: Ak(CONF,82121700,010094,DEV) CONF – Confirm command received okay CONFE – Enhance Confirm command received okay VOID – Void command received VOIDE – Enhance Void command received NONE - acknowledgement NOT been received from the merchant application within 30 seconds LATE – Confirm command received too late, transaction has been reversed BADSTAN – STAN in confirm command not found.

Terminal busy, cannot send accept transaction request

Busy(CAIC,Comment) Eg: Busy(3110000620000, DEV)

Simulated Message to host ST(MessageType,CATID,STAN ,00,Comment) Eg: ST(0200,82121700,010094,00,DEV)


Simulated Message received SR(MessageType,CATID,STA N,ResponseCode,Comment) Eg: Rx(0210,82121700,010094,56,DEV)

Message could not be transmitted as waiting on ACK from communications adapter

WA(slot,CATID,STAN,Comment)

Connected state Disconnected

Connected state Connect

Data Carrier Detect DCD Down

Data Carrier Detect DCD Up

Reset Modem ResetModem

Asserting Data Terminal Ready/Request To Send pins on communications port

Assert DTR/RTS

Update command issued and have held all terminals (return Busy!)

Global(Hold,Update Cmd)

Update command completed and have released all terminals

Global(Release,Update Cmd)

Hold command issued Global(Hold,Hold Cmd)

Release command issued Global(Release,Release Cmd)

Hold all terminals (return Busy!) as could not write out to any Record Of Transaction files

Global(Hold,Write Fault)

Confirm CONF

The monitor log proves to be most useful for tracking issues. A number of examples are provided below in tracking various scenarios.

Normal pre-authorisaton transaction sequence. You c an determine turnaraound time for host response, the transaction was declined with re sponse code 56: 04/04/2005 13:00:49.653 Tx(0100,23000001,000011,00, test) 04/04/2005 13:00:59.267 Rx(0110,23000001,000011,56, test) 04/04/2005 13:00:59.397 Ak(CONF,23000001,000011,tes t) Normal financial transaction sequence. 04/04/2005 16:20:24.407 Tx(0200,23000001,000014,00, TEST) 04/04/2005 16:20:25.599 Rx(0210,23000001,000014,56, TEST) 04/04/2005 16:20:25.719 Ak(CONF,23000001,000014,TES T) Communications adapter going offline and then back on: 04/04/2005 12:10:27.648 DCD Down 04/04/2005 12:10:27.658 Disconnected 04/04/2005 12:14:25.660 DCD Up 04/04/2005 12:14:25.670 Connect 04/04/2005 12:25:13.712 DCD Down 04/04/2005 12:25:13.712 Disconnected 04/04/2005 12:25:45.297 DCD Up 04/04/2005 12:25:45.297 Connect No bank response after timeout, so reversal request sent and then reversal response received: 04/04/2005 12:56:59.402 Tx(0100,23000001,000142,00, test) 04/04/2005 12:57:27.442 Tx(0420,23000001,000142,01, test) 04/04/2005 12:57:57.496 Tx(0421,23000001,000142,02, test) 04/04/2005 12:57:59.198 Rx(0430,23000001,000142,21, test) No bank response at all, so reversal request sent f ollowed by multiple reversal request repeats: 04/04/2005 16:24:07.207 Tx(0200,23000001,000015,00, test) 04/04/2005 16:24:37.371 Tx(0420,23000001,000015,01, test) 04/04/2005 16:25:07.414 Tx(0421,23000001,000015,02, test)


04/04/2005 16:25:37.457 Tx(0421,23000001,000015,03, test) 04/04/2005 16:26:07.490 Tx(0421,23000001,000015,04, test) 04/04/2005 16:26:37.524 Tx(0421,23000001,000015,05, test) 04/04/2005 16:27:07.587 Tx(0421,23000001,000015,06, test) 04/04/2005 16:27:37.620 Tx(0421,23000001,000015,07, test) 04/04/2005 16:28:07.653 Tx(0421,23000001,000015,08, test) 04/04/2005 16:28:37.696 Tx(0421,23000001,000015,09, test) 04/04/2005 16:29:07.750 Tx(0421,23000001,000015,10, test) 04/04/2005 16:29:37.793 Tx(0421,23000001,000015,11, test) 04/04/2005 16:34:38.255 Tx(0421,23000001,000015,12, test) 04/04/2005 16:39:38.657 Tx(0421,23000001,000015,13, test) 04/04/2005 16:44:39.079 Tx(0421,23000001,000015,14, test) 04/04/2005 16:49:39.521 Tx(0421,23000001,000015,15, test) 04/04/2005 16:54:39.943 Tx(0421,23000001,000015,16, test) 04/04/2005 16:59:40.385 Tx(0421,23000001,000015,17, test) Ran out of available virtual terminsl as indicated by Busy() 15/03/2005 17:38:14.629 Tx(0200,23000001,000025,00, test) 15/03/2005 17:38:14.629 Busy(311000062000000,test) 15/03/2005 17:38:16.912 Rx(0210,23000001,000025,00, test) 15/03/2005 17:38:16.972 Ak(CONF,23000001,000025,tes t) Normal transaction sequence, but no acknowledgement received from the merchant application as indicated by Ak(NONE…. This leads to a reversal request being raised. In this case, it is an “Approved Reversal” (funds t aken, then reversal): 05/04/2005 02:14:13.544 Tx(0200,23000001,073444,00, test) 05/04/2005 02:14:20.564 Rx(0210,23000001,073444,00, test) 05/04/2005 02:14:46.281 Ak(NONE,23000001,073444,tes t) 05/04/2005 02:14:46.321 Tx(0420,23000001,073444,00, test) 05/04/2005 02:14:50.888 Rx(0430, 23000001,073444,00 ,test)

5.2 Monitor Log via Socket Stream As well as optionally writing to the monitor log file, CardGate Version 4 will write the monitor log output to socket clients (eg telnet terminal such as Windows Hyperterminal) that have connected to the CardGate monitor TCP/IP port. The monitor port is the listen port configured in the registry plus one. As the default listen port is 4000, then the default monitor port is 4001.

This enables one to remotely view the real-time status of transactions by simply “telnetting” to port 4001 (say). An example command line to run a telnet session to do this is:

telnet 127.0.0.1 4001

5.4 Socket Request Log CardGate optionally maintains a local time stamped log file of all sockets requests to aid tracking of online transactions. It is a standard ASCII text file that can be viewed with the Windows Notepad text editor. This log file is "ONLINE_YYYYMMDD.TXT" (where YYYYMMDD represents the date).

This logging facility should normally only be enabled during integration testing phases of the implementation and is disabled by default. To enable it, you set the registry value “Online Log” to 1.

The example below shows a typical sockets transaction - at 14:31:43 CardGate received a Financial request from the Merchant Application. At 14:31:44, CardGate passed on the Bank response to the Merchant Application. At 14:31:45, the Merchant Application sent a Confirm positive acknowledgment response.

13/11/1997 14:31:43.310 6000006E O/L Rx 021 037462 F 311000062320900 JVD9MVC44BS12GTX00LHR40S11 S 4532667109000088 500 9912

13/11/1997 14:31:44.401 6000006F O/L Tx 000=0210 003=003000 004=000000000500 011=048268 012=143048 013=1113 015=0225 039=05 041=82320905 042=311000062320900


900=021 901=037462 902=JVD9MVC44BS12GTX00LHR40S11 910=Do not honour

13/11/1997 14:31:45.403 6000006E O/L Rx 021 037462 C 311000062320900 82320905

It is highly recommended that this log be disabled in full production as it:

a) contains card numbers in the clear

b) slows down processing

c) grows quickly

5.5 Host Communications Log CardGate optionally maintains a local time stamped log file of all communications to and from the host computer. It is a standard ASCII text file that can be viewed with the Windows Notepad text editor. This log file is "COMMS_YYYYMMDD.TXT" (where YYYYMMDD represents the date).

This logging facility should normally only be enabled during integration testing phases of the implementation and is disabled by default. To enable it, you set the registry value “Comms Log” to 1.

Note that three lines are printed for each buffer dump: the first line is the time stamp, the second the hexadecimal value of each character and the third line the ASCII representation of each character.

The example below shows a transaction - at 14:31:43 CardGate sent an 0200 Financial request message to the host. At 14:31:44, CardGate received an 0210 Financial response message fromt the host.

13/11/1997 14:31:43.430 60000065 Tx 60 bytes

02007024048000C000001645326671090000880030000000000 00500039192991200121538323332303930363331313030303036323332303930300D

. . p $ . . . . . . . E 2 $ q . . . . . 0 . . . . . . . . . . . . . . . 8 2 3 2 0 9 0 6 3 1 1 0 0 0 0 6 2 3 2 0 9 0 0 .

13/11/1997 14:31:44.291 60000064 Rx 1 bytes

60

`

13/11/1997 14:31:44.381 60000064 Rx 59 bytes

000000000210303A000002C0000000300000000000050004826 814304811130225303538323332303530353331313030303036323332303930300D

. . . . . . 0 : . . . . . . . 0 . . . . . . . . . h . 0 H . . . % 0 5 8 2 3 2 0 9 0 5 3 1 1 0 0 0 0 6 2 3 2 0 9 0 0 .

It is recommended that this log be disabled in full production as it:

d) contains card numbers in the clear

e) slows down processing

f) grows quickly


5.6 Event Logging CardGate makes extensive use of Windows NT Event logging to log application level errors. Event Logging provides a standard, centralized way for applications (and the operating system) to record important software and hardware events. It also supplies a standard user interface for viewing the logs and a programming interface for examining the logs.

The Event viewer is found under the following NT menu structure: Start:Programs:Administrative Tools(common):Event Viewer.

The Event viewer should be utilised whenever there are problems to be traced. A list of response codes generated by CardGate is provided in Appendix B. Note that CardGate only puts "system" and "data error" errors to the NT event log. The following error codes are NOT logged :

ERR_BUSY, ERR_DATE_INVALID, RET_REVERSAL, RET_ACK, ERR_CHECK_DIGIT, ERR_EXPIRY_DATE, ERR_REVERSAL_PENDING, FRAME_RX, FRAME_TX,ONLINE_RX and ONLINE_TX.

The NT event will provide the following information:

- Time and date of event.

- Source of the event. This is "CardGate" for CardGate generated events.

- Event id. This corresponds to either a CardGate response code or an operating system error code, eg event id 13 is INF_STARTUP.

- Description. For CardGate response codes, this will contain the corresponding response description as given in Appendix B. It will also give the name of the function that in which the event was generated, eg "Application starting! InitCG() Win NT".

- Data. Certain events will display binary data that corresponds to important information that will help resolve the anomaly. Typically the event description will contain the text "Data is …" to indicate what the binary data represents, eg "Data is rx buffer" indicates that the contents of the communications receive buffer is displayed.


5.7 Typical Anomalies

5.6.1 Event ID 7 and ID 37 Event ID 7 (ERR_SLOT_CLASH) " Virtual Terminal was found to be NOT in use. ActOnFrame() - Frame received has problem. Data is rx buffer (incl TPDU): "

Event ID 37 (ERR_MSG_TYPE_BAD) "Message Type Identifier unexpected! ActOnFrame() - Frame received has problem. Date is rx buffer (incl TPDU):"

These events indicate that an unexpected response has been received. Typically this is due to the host being slow to respond, as shown in the following examples:

Tx Rx

0200

0420

0421

0430

0210 � Event ID 7 error - rejected and never seen by Merchant Application

0430 � Event ID 7 error - rejected and never seen by Merchant Application

0200 #1

0420 #1

0421 #1

0430 #1

0200 #2

0210 #1 � Event ID 37 error - rejected and never seen by Merchant Application

0210 #2

5.7.2 Event ID 24 Event ID 24 (ERR_STUCK_TRANSACTION) "Stuck transaction being cleared from system! REPORT DETAILS TO BANK!"

This event indicates that the 30 minute time out period has expired without a response from the host for a transaction. This is termed a "STUCK TRANSACTION" and the details should be reported to the Bank, ESPECIALLY for 0221 Financial Capture Advice.

5.7.3 Event ID 34 Event ID 34 (ERR_TPDU_BAD) "Bad TPDU header! Data is rx buffer" This event indicates that garbage has been received on the communications line. CardGate will recover if it is not received during a transaction.


6. User Interface CardGate's user interface consists of two windows

- the graphical "state view" which shows the state of the application, and,

- the textual "console view", which show events as they happen on a time basis.

6.1 State View The state view provides a method of viewing the real-time activity on the first eight virtual terminals (as defined in the terminalv4.txt file). For each terminal, the CATID, state of the protocol, the count down timer, retry count and comment is displayed.

The View:Terminal menu option allows the transaction details of a specified terminal to be displayed.

The state view also shows the number of messages sent to, and received from, the host. In the ideal situation, the host messages sent will equal the number of messages received.

An open socket count is also displayed for client, monitor and host (not implemented) connections.

6.2 Console View The console view provides a simple textual log of events as they occur. This provides a means of tracking activity in real time which proves to be useful in production as well as during integration testing.

7. Support CardGate.net provides 24 hour x 7 days per week telephone support via (03) 9582 7099. For non-urgent problem rectification, email [email protected].

The Bank provides 24 hour help desk to support COMMLINK and communications related issues only (ie anything past the computer). Telephone 1800 022 966 and have your Merchant ID (CAIC) or Terminal Number (CATID) ready.

Daily reconciliation reports, report number CM5070, can be ordered from the Bank by phoning Merchant Enquiries on 1800 230 177. This report contains the STAN and truncated credit card numbers for each transaction.


8. Revision History Issue Date By Comments

1 19/07/11 HR Copied Issue 14 (16/07/08) of CardGatev4-TM. Updated to meet with CBA Commlink v2.33 and CardGatev5 + specifications – Added flags 15 and higher to terminalv4.txt configuration

2 14/11/11 HR - Additional Data ECMm3 – Instalment Payment value was removed from CBA Commlink v2.33 specification – References to terminalv5.txt changed to terminalv4.txt – Emulation now includes DE47 Additional Data response for 0110 and 0210 message types – Documented emulation mode responses

3 23/08/12 HR - Added CBA IP @ POS communications channel option setup via GHL netAccess Payment Router

4 28/02/13 HR - Updated Appendix H CBA IP @ POS communications channel option setup with latest advice


Appendix A. COMMLINK Response Codes The Merchant Application should only accept a financial transaction if the response code returned is '00'.

Code Description Response Text

00 Transaction approved APPROVAL CODE auth no

01 Phone card issuer PLEASE CALL ISSUER

03 Phone the Authorisation Referral Centre ERROR - S/E NUMBER

05 Credit transaction is not allowed DO NOT HONOUR

12 Invalid Transaction - declined ERROR-INVLD TRAN

13 The Transaction Amount is invalid ERROR-INVLD AMOUNT

14 The Card Number is invalid ERROR-INVLD CARD

19 Enter the Transactin again RE-ENTER TRANSACTION

21 No Action is taken for this transaction no message...

25 The Terminal is not Active or Able ERROR-TERM. INACTIVE

30 The message contains invalid Data ERROR-INVLD FORMAT

31 The Card is not accepted by the Host/Interchange

ERROR - N S

39 No credit Account attached to Card NO CREDIT ACCOUNT

51 Not sufficient Funds in the Account DECLINED

54 The Card has Expired EXPIRED CARD

56 No record exists for this Card NO CARD RECORD

57 The transaction is not permitted for the Card TRANS NOT PERMITTED

58 The transaction is not allowed at the terminal TRANS NOT ALLOWED

61 The withdrawal limit has been exceeded LIMIT EXCEEDED

76 An incorrect descriptor has been entered ERROR - DESCRIPTOR

91 The Host is currently unavailable - try later ERROR - HOST UNAVAIL.

94 The Sequence Number is incorrect or the transaction is out of sequence

ERROR - SEQUENCE NO

95 The Reconciliation Totals have not matched No message...

97 Reconciliation Totals have been reset No message...

N0 CSC not provided – credit transaction is not allowed

DO NO HONOUR

N7 Decline for CVV2 failure (for Visa cards only) DO NO HONOUR

Q5 Already settled - can't settle twice in a day SYSTEM ALREADY SETTLED

Z2 The transaction has already been reversed No message…

Z3 Transaction amount is greater than authorised AMOUNT TOO LARGE


Appendix B. CardGate Response Codes

Status Code (Field 903)

Response Text (Field 904)

Severity

1 Software error trap #0! ERR 2 Software error trap #1! ERR 3 Too long! ERR 4 Not numeric! ERR 5 Invalid! ERR 6 Busy! INF 7 Virtual Terminal was found to be NOT in use. ERR 8 Date invalid! INF 9 Reversal requested from Payment Application. RET

10 Acknowledgement received from Payment Application.

RET

11 Must be in ONLINE mode, not Batch! ERR 12 Refunds and Voids barred! ERR 13 Application starting! INF 14 Unable to unlock using key! ERR 15 Not found! ERR 16 Application closing! INF 20 Card number invalid! INF 21 Expiry date exceeded! INF 22 Command Code invalid! ERR 23 Sticky transaction, possibly stuck! ERR 24 Stuck transaction being cleared from system!

REPORT DETAILS TO BANK! ERR

25 Reversal pending! ERR 26 Reversal! ERR 27 Missing field or paramet ERR 28 Warning Bulletin Alert! INF 29 No Warning Bulletin! INF 30 Timeout! ERR 31 Bad frame! ERR 32 Unexpected! ERR 33 Communications error! ERR 34 Bad TPDU header! ERR 35 CATID unexpected! ERR 36 CAIC unexpected! ERR 37 Command Code Identifier unexpected! ERR 38 Processing Code unexpected! ERR 39 Amount unexpected! ERR 40 INI File/Registry parameter of bad type! ERR 41 INI File/Registry parameter out of range! ERR 42 Sockets error! ERR 50 Requested CAIC not installed! ERR 51 STAN not found! ERR 52 Sequence number too low! INF 53 Sequence number not found! ERR 60 OK INF 61 PENDING INF 62 REVERSAL PENDING INF 63 FAIL INF 64 NOT READY INF 65 INVALID INF 66 IDLE INF


67 EMPTY INF 100 Rx Frame INF 101 Tx Frame INF 110 Rx Online Rec INF 111 Tx Online Rec INF 120 Wait aborted! INF 121 Wait timed out! INF


Appendix C. Version Differences

C.1 Version 5 differences Version 5 adds a number of improvements. For full details refer to the version history file cardgate-version.txt.


Appendix D. Sample Reference Visual Basic Client ' R288C - CardGate Example Client Application (Written in VB5) ' Connects to UMD Server/ CardGate using sockets. ' Operator inputs Reference, Card Number, Expiry da te and amount ' then waits for response from CardGate. ' Note that this application is a reference example only, ' requires production facilities such as configurat ion parameters. ' ' Version History ' 11/07/97 - HR ' - Created ' 14/07/97 - HR ' - Form_Load() now sets up registry keys BEFORE connecting ' 04/03/98 - HR ' - Confirm command now matches V2.17 CardGate ' - Now confirms 0530 messages as well as 0210 ' Dim gstrClientID, gstrCAIC, gstrSeqNr As String Dim gTransactionState As Integer ' Constants used by gTransactionState Const tsIdle = 0 Const tsRequest = 1 Const tsAcking = 2 Const tsReversing = 3 Const tsCompleted = 4 Private Sub Form_Load() ' The name of the Winsock control is Winsock1. ' Note: to specify a remote host, you can use eithe r the IP address (ex: "121.111.1.1") ' or the computer's "friendly" name Dim strEntry As String Dim rc, intEntry As Integer ' Get registry settings for this session gstrClientID = GetSetting("UMD", "UMDR288C", "C lient ID", "000") ' Having a Client ID of 0 implies that this is a new installation ' so set up the registry with new keys If (gstrClientID = 0) Then SaveSetting "UMD", "UMDR288C", "Seq Nr", 1 SaveSetting "UMD", "UMDR288C", "Client ID", "001" SaveSetting "UMD", "UMDR288C", "CAIC", "000 000000000000" SaveSetting "UMD", "UMDR288C", "Remote Host ", "0.0.0.0" SaveSetting "UMD", "UMDR288C", "Remote Port ", 4000 rc = MsgBox("Have set up default Registry k eys", vbOKOnly, "UMD CardGate Client") End If gstrCAIC = GetSetting("UMD", "UMDR288C", "CAIC" , "ERR NOT DEFINED") gTransactionState = tsIdle ' Get host/port details for socket communicatio ns ' eg "128.0.0.2" Winsock1.RemoteHost = GetSetting("UMD", "UMDR28 8C", _ "Remote Host", "0.0.0.0") Winsock1.RemotePort = GetSetting("UMD", "UMDR28 8C", _ "Remote Port", "4000") TextIP.Text = Winsock1.LocalIP ' display w ho we are Winsock1.Connect TextStatus.Text = Winsock1.State End Sub Private Sub Winsock1_Connect() ' Winsock Connect event action TextStatus.Text = "Connected" End Sub Private Sub SubmitButton_Click()


' Submits the request ' ie operator has clicked submit button after filli ng out all fields Dim strRequest As String Dim SeqNr As Long Dim rc As Integer TextStatus.Text = Winsock1.State If (Winsock1.State = sckConnected) Then ' Stop sending another transaction unless t he last was completed If (gTransactionState <> tsCompleted) And ( gTransactionState <> tsIdle) Then rc = MsgBox("Last transaction not compl ete. Wait!", _ vbOKOnly + vbInformation, _ " CardGate Client Error") Exit Sub End If TextResponse.Text = "" TextMessage.Text = "" ' Get unique sequence number from registry and bump and save back SeqNr = GetSetting("UMD", "UMDR288C", "Seq Nr") gstrSeqNr = Format(SeqNr, "000000") ' eg convert SeqNr to "nnnnnn" SeqNr = SeqNr + 1 If SeqNr > 999999 Then SeqNr = 1 SaveSetting "UMD", "UMDR288C", "Seq Nr", Se qNr ' Build request record - "F" for financial transaction, "S" for sale strRequest = gstrClientID & vbTab & _ gstrSeqNr & vbTab & _ "F" & vbTab & _ gstrCAIC & vbTab & _ TextRef.Text & vbTab & _ "S" & vbTab & _ TextPAN.Text & vbTab & _ TextAmount.Text & vbTab & _ TextExpDate.Text & vbCr ' Send request to CardGate gTransactionState = tsRequest Winsock1.SendData strRequest Else ' could not submit - display error rc = MsgBox("Could not submit request. WSAS tate=" & Winsock1.State, _ vbOKOnly + vbCritical, _ " CardGate Client Error") End If End Sub Private Sub Winsock1_DataArrival(ByVal bytesTotal A s Long) ' Winsock DataArrival event action. ' We have recieved a response from CardGate Dim strData As String Dim strField As String Dim strCATID As String Dim rc, State As Integer TextStatus.Text = "Response received" Winsock1.GetData strData, vbString TextResponse.Text = strData ' Display CardGate error message or CBA suggest ed response text If ParseROT(strField, strData, 904) Then TextMessage.Text = strField ' Display CardG ate error text ' See if this is a "Reversal Pending!" resp onse from CardGate. ' If it is, then this means that we now awa it the Reversal response If ParseROT(strField, strData, 903) Then If StrComp(strField, "25") = 0 Then gTransactionState = tsReversing Exit Sub End If End If GoTo TransCompleted ' as no need to acknowl edge CardGate Else


If ParseROT(strField, strData, 910) Then '9 10=CBA suggested response If strField = "" Then strField = "Blank CBA message" TextMessage.Text = strField ' Display C BA suggested response Else ' No CardGate error text or CBA sug gested response ' We should not get this! Is a syst em error TextMessage.Text = "No message - system error" End If End If ' Was this a 0210 or 530 response? If so, then we need to acknowledge CardGate ' with a "CONFIRM" command that we have success fully received ' To get here, must have had a CBA response, so no field "000" is ' a system error of some sort? State = 0 If ParseROT(strField, strData, 0) = 0 Then GoTo SanityFail ' We have a CBA Message - extract Message Type If (StrComp(strField, "0210") <> 0) And _ (StrComp(strField, "0530") <> 0) Then GoTo TransCompleted ' We have a 0210/0530 response - respond with ' C' Confirm command ' but some sanity checks first ' Sanity check 1 - does ClientID match that sen t? State = 1 If ParseROT(strField, strData, 900) = 0 Then Go To SanityFail State = 2 If StrComp(strField, gstrClientID) <> 0 Then Go To SanityFail ' Sanity check 2 - does SeqNr match that sent? State = 3 If ParseROT(strField, strData, 901) = 0 Then Go To SanityFail State = 4 If StrComp(strField, gstrSeqNr) <> 0 Then GoTo SanityFail ' Sanity check 3 - have we got a CATID? State = 5 If ParseROT(strCATID, strData, 41) = 0 Then SanityFail: rc = MsgBox("SEE SUPERVISOR - RESPONSE NOT FOR ME! State=" & State, _ vbOKOnly + vbCritical, " Ca rdGate Client Error") TransCompleted: gTransactionState = tsCompleted TextStatus.Text = "Completed" Exit Sub End If ' Okay - passed sanity checks - send 'C' comman d If (Winsock1.State = sckConnected) Then gTransactionState = tsAcking ' Indicate waiting on ACK to complete Winsock1.SendData gstrClientID & vbTab & _ gstrSeqNr & vbTab & _ "C" & vbTab & _ gstrCAIC & vbTab & _ strCATID & vbCr Else ' Problem! Could not acknowledge 0210 - BE WARE this means that ' the 210 message will be reversed... rc = MsgBox("SEE SUPERVISOR - CANNOT ACK RE SPONSE! WSAState=" & Winsock1.State, _ vbOKOnly + vbCritical, " Ca rdGate Client Error") End If End Sub Private Sub Winsock1_SendComplete() ' Winsock SendComplete event action. ' This either means ' a) Financial Request was sent okay ' b) An ACK to a Financial Response was sent okay ' c) A VOID command was sent okay ' Display status of transaction to operator If (gTransactionState = tsRequest) Or _ (gTransactionState = tsReversing) Then TextStatus.Text = "Waiting for response ..." ElseIf gTransactionState = tsAcking Then


TextStatus.Text = "Completed" ' A CK sent ok! gTransactionState = tsCompleted Else TextStatus.Text = "Send completed..." ' c onfusion here! End If End Sub Private Sub Winsock1_Error(ByVal Number As Integer, Description As String, ByVal Scode As Long, ByVal Source As String, ByVal HelpFile As String, ByVal HelpContext As Long, CancelDisplay As Boolean) ' Winsock Error event action TextStatus.Text = "Err:" & Description End Sub Private Sub Form_Unload(Cancel As Integer) Winsock1.Close End Sub


Appendix F. Optus/TNS Configuration After May 2005, the Bank will have phased out their Enterprise Network Gateway service for leased line access to their COMMLINK host. In its place is the Optus/Transaction Network Services (TNS) secure VPN solution which uses TCP/IP with an ADSL service over a PSTN line. The ADSL connection, router and Managed Terminal Adapter ("MTA") will be provided by Optus, with the merchant providing the telephone line.

The MTA connects to the Optus managed router via Ethernet and the CardGate PC connects to the MTA using it's serial port. This means that you will not need to install a router/firewall in front of the ADSL router as there is no practical connection between your TCP/IP network and the ADSL VPN solution.

It is suggested that CardGate be started with a command line parameter that reflects the mode of communication, eg

cardgate TNS


"\\HKEY_LOCAL_MACHINE\SOFTWARE\UMD\CardGate TNS"

F.1 CardGate Registry Settings The following are the CardGate registry settings that need to be set for connection to the Optus/TNS solution:

Value name Type Default SET TO

Line Mode 0 DWORD 0 5

5 = Asynchronous Block Protocol (ABP) wrapping Transport Protocol Data Unit (TPDU) …..- used by Optus/TNS Solution via MTA serial port


Comms Port string "COM2" As appropriate



Comms Mode string "9600,N,8,2" "9600,N,8,2"



Appendix G. Telstra Argent Configuration The CardGate Payment Gateway can also connect to Telstra’s Argent® service.

The Argent Terminal Adapter (ATA) connects to the Telstra managed network and the CardGate PC connects to the ATA using it's serial port.

It is suggested that CardGate be started with a command line parameter that reflects the mode of communication, eg

cardgate Argent.


"\\HKEY_LOCAL_MACHINE\SOFTWARE\UMD\CardGate Argent"

G.1 CardGate Registry Settings The following are the CardGate registry settings that need to be set for connection to the Telstra/Argent® solution:



4 = Asynchronous Block Protocol (ABP) wrapping Connectionless Network Protocol (CLNP) - used by Telstra Argent®








NSAP SHA DWORD 0 .. 0

Telstra Argent® - Network Service Access Point Symbolic Host Address (supplied by the Bank). Typically supplied as a hexadecimal number, eg hexadecimal 82805100



Telstra Argent® - Network Service Access Point Terminal Identifier (supplied by Telstra, tied to the Terminal Adapter). Typically supplied as a hexadecimal number, eg hexadecimal 68f6e


Appendix H. CBA IP@POS Configuration The CardGate Payment Gateway also connects to CBA’s IP @ POS service which allows transactions to be conducted over the public internet.

H.1 CBA IP@POS Mandate CBA is providing a secure direct telco agnostic IP/SSL connection to their new IP@POS service.

As of February 2013, IP@POS is the Bank preferred channel for COMMLINK traffic:

The Bank is decommissioning all legacy mainframe Front End Processors (FEP’s) which have been servicing their direct connect X25, Optus/TNS MTA’s and Argent ATA’s customers for many years. All COMMLINK customers must be migrated to GHL IP/SSL before the end of April 2013.

H.2 GHL netAccess Payment Router The Bank will provide a communications appliance, the GHL Systems netAccess L-100 or L-200 3G Payment Router, to COMMLINK merchants. The GHL connects to the merchant’s LAN to gain access to the internet and the CardGate server connects to it via its serial port.

H.3 Set up Firewall rules for GHL IP As the GHL connects to the public internet, it should sit behind the merchant’s firewall. Here are the firewall rules that need to be implemented:

Rule#1 - Allow <GHL DHCP IP address or subnet> to 202.129.171.220 using TCP 5222

(Note: The GHL device will periodically contact the GHL Management Console, notifying it’s status)

Rule#2 - Allow <GHL DHCP IP address or subnet > to NTP Primary 202.174.101.10

(o.oceanic.pool.ntp.org) using UDP 123

Rule#3 - Allow <GHL DHCP IP address or subnet > to NTP Secondary 202.158.218.239

(2.oceanic.pool.ntp.org) using UDP 123

Rule#4 - Allow <GHL DHCP IP address or subnet > to Google DNS 8.8.8.8, 8.8.4.4, 4.2.2.2 and using

ICMP/Ping/DNS

Rule#5 - Allow <GHL DHCP IP address or subnet > to i1.paywide.nps.commbank.com.au using TCP

9001


H.4 CardGate Registry Settings It is suggested that CardGate be started with a command line parameter that reflects the mode of communication, eg

cardgate IP@POS

CardGate would then use registry sub-key:

\\HKEY_LOCAL_MACHINE\SOFTWARE\UMD\CardGate IP@POS

The following are the CardGate registry settings that need to be set for connection to the Bank’s IP @ POS solution:



4 = Asynchronous Block Protocol (ABP) wrapping Connectionless Network Protocol (CLNP) - used by Telstra Argent® and CBA IP@POS







Value name Type Limits SET TO

NSAP SHA DWORD 0 .. 82805100 (hexadecimal)

Network Service Access Point Symbolic Host Address (supplied by the Bank).



Network Service Access Point Terminal. This is ignored by the GHL.


H.3 GHL Device Setup

General Setup - Connect the GHL ETH Ethernet port to your LAN

- Connect the GHL Serial Port 3 (located above the ETH port) using the supplied serial cable to your Cardgate server’s serial port as selected in the “Comms Port” registry value

- If you were supplied with a 3G mobile SIM (held in the SIM1 position located at the front of the GHL), and you do not intend to use 3G mobile communications fallback should your LAN connection fail, simply remove the SIM. Note: DO NOT remove SIM 2 from the back of the GHL!

- Connect power to the GHL

How to setup the GHL with a static IP By default, the GHL uses DHCP. Should you want to configure it to have a static IP address, follow this section:

1. Change the IP address of your PC to 10.0.0.100 \ 255.0.0.0 2. Temporarily connect a 'cross-over' Ethernet cable between your PC's

Ethernet port and the ETH port on the GHL unit (Note: If you don't have a 'cross-over' Ethernet cable connect both the GHL Unit and the PC to the same Ethernet hub or switch)

3. Open a web browser on your PC then browse to http:\\10.0.0.99 . (Note: This is the secondary IP address of the device which is only used for configuration purposes)

4. Enter the system password. This must be obtained from CardGate.net support by telephoning (03) 9582 7099.

5. Go to the 'System Tools' tab then set the Primary IP/Subnet Mask and Gateway as per your static IP address requirements.

6. Click 'Set'. 7. Click 'Restart netRouter'. 8. Remove cross-over cable then plug the GHL ETH port directly into your

Ethernet LAN, i.e. COMMLINK/Cardgate Server (COM Port) <-> GHL Serial Port (ie. port above ETH) <-> GHL ETH Port to Ethernet LAN <-> Eth ernet LAN to ISP/Firewall <-> CBA IP@POS .

9. Power off the device and then back on


10. OPTIONAL – how do I validate the firewall rules and GHL connectivity? From a PC on GHL’s Ethernet LAN segment, logon to the GHL at http://<GHL static primary ip> or the secondary interface on http://10.0.0.99, and browse to System Tools > Test > Ping Enter a public internet address such as 8.8.8.8. You can also test connectivity to the CBA IP@POS host by browsing to System Tools > Test > Connect Test and entering 140.168.74.78 (ie i1.paywide.nps.commbank.com.au) port 9001. You could also try, from a PC on the LAN segment: telnet i1.paywide.nps.commbank.com.au 9001 or telnet 140.168.74.78 9001 in order to confirm that the GHL can connect through your firewall to our CBA IP@POS host.

11. OPTIONAL - How do I validate the static IP address? From a PC on GHL’s Ethernet LAN segment, at the 'Start -> Run -> cmd' command prompt type 'ping <GHL static primary ip> -t'. Where the static address is what was entered in step5.


Appendix I. Configuring Windows

I.1 Starting CardGate without logging on

To enable auto logging on, edit the registry using REGEDIT.EXE or REGEDT32 programs.

Edit registry sub-key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\Current Version\WinLogon" setting:

AutoAdminLogon: "1"

DefaultDomainName: domain

DefaultUserName: username

DefaultPassword: password

DontDisplayLastUserName : "0"


Appendix J. Upgrading from Version 4 to 5 The following provides a suggested upgrade path from Version 4 to 5. Other methods and sequences can readily be envisaged. Please call for advice!

J.1 Set up directory If you are upgrading CardGate Version 4 to 5 on the same machine, it is suggested that a new directory be created “c:\Program Files\CardGateV5”. Copy the contents of the cardgatev5.zip archive into it.

J.2 Update the Terminal Definition File Copy the terminal definition file “terminalv4.txt” from your current CardGate installation in the new directory. Edit it, copying its contents into the clipboard. Next, open terminalv4-sample.txt in your text editor and paste the clipboard contents at the bottom of the file. Save the file as “terminalv4.txt”. This is your new terminal definition file. [It is suggested that you go through this process so that you incorporate the flag definition comments from the sample terminal file.]

Next, enhance each terminal definition line with comments and refund/sale limits (even if you will not be enabling this new feature). Enable the new Version 5 features that you want by way of the flags field. For example:

OLD DEFINITION TERMINAL DEFINITION 311000062000000 23000001 85765 112 New terminal definition: 311000062000000 23000001 85765 112020010001 samplem erch 300000 50000

J.3 Transfer state file Once you are ready to go live, copy the “state.dat” from the old installation to the new. This is important as it file holds the highest Systems Trace Audit Number (STAN) for each terminal. If the STAN’s are too low, the Bank host will not respond to transaction requests.

Documents

CardGate.net Pty Ltd CardGate® Payment Gateway V5 ... · 5.6.1 Event ID 7 and ID 37 54 5.7.2 Event ID 24 54 5.7.3 Event ID 34 54 6. USER INTERFACE 55 6.1 State View 55 6.2 Console