Samport Host2t 2.2.0

SAMPORT HOST2T 2.2.0

Created by Jens Lindblad

Classification For public use

(49)

Revision date 2015-05-18

Previous version 2.1.0

Version 2.2.0

STOCKHOLM KARLAVÄGEN 108 115 26 STOCKHOLM SWEDEN

HALMSTAD LINJEGATAN 5 302 50 HALMSTAD SWEDEN

OSLO KARENLYST ALLÉ 8 B 0278 OSLO NORWAY

OFFICE +46 8 400 15 400 WWW.SAMPORT.COM

SAMPORT HOST2T PROTOCOL SPECIFICATION Issued by: Jens Lindblad Creation date: 2012-11-30 Revision date: 2015-05-18 Version: 2.2.0




(49)



Version 2.2.0





1 Revision history

Rev Section Description Date and sign

1.0 All Initial version. 2012-11-30 – JL

1.0.1 5.7.5 5.7.7 5.8.2 5.10

Updated fields present in REVERSAL response. Updated fields present in SETTLE response. New result codes for network messages. State machine sequence number handling corrected.

2012-12-28 – JL

1.0.2 5.7 5.7.8 5.7.13-16 5.8.1 5.8.6 5.8.19-20 5.8.46 5.9

Added echoData in responses. Removed enableExternalNetworking field. Corrected present amount fields. Corrected spelling error of acquirerId. Corrected Danish language code. Clarified internal and external reference. Additional maintenance status values. New link layer state machine.

2013-01-31 – JL

2.0.3 All 5.9.3

New versioning scheme. PING handling updated. Reset of TACK when sending message.

2013-03-15 – JL

2.1.0 All 5.1 5.4.3 6 6.23 6.24, 7.2 7 7.1 7.2 7.46 7.54 7.59 7.69 7.72 8 8.1

Corrections to spelling and style. Added section on connection options. Added information about Bluetooth terminals. Added information about RFU. Changed message naming style, updated descriptions, and removed request and response lists. Added interactive dialogs. Updated dialog data fields. Added read card message. Changed data element naming style, removed data type from titles, added availability to data element list. Dialog result type changed to string. Enable dialog changed to char. Data now binary. Removed unused data elements. Added ‘no communication’ and ‘terminal busy’ result codes. Clarified format of custom data. Corrected usage of echo data. Added token field. Added information about card data request. Added closing reference field. Added request and response matrices. Refund had authorization method as input parameter. Changed to authorization option. Added transaction type to responses.

2013-07-03 – JL,GL




(49)



Version 2.2.0





9.1 9.2 10.3 11

Added reversal reference to get transaction response. Added token element. Corrected example sale request message. Added example sale response message. Detection of STX corrected in IDLEREC and ACKREC. Added receipt formatting specification.

2.2.0 5.1 6.12, 8 6.19-6.22 7.6 7.45 7.1, 7.74-7.81, 8 11.8

Clarified connection methods and added Bluetooth to supported interfaces. GET INFORMATION no longer accepts request list, and returns all available information. Clarified network messages. Added languages. Added values to MAINTENANCE STATUS. Added PROTOCOL VERSION, PREFERRED

PROTOCOL VERSION, KEY, SOFTWARE VERSION, SOFTWARE COMPATIBILITY, TARGET SOFTWARE

VERSION, TARGET SOFTWARE COMPATIBILITY, and UNMASKED PAN. Corrected receipt examples.

2015-05-18 – JL




(49)



Version 2.2.0





2 Abbreviations ACK Acknowledgement message DLE Data Link Escape ECR Electronic Cash Register EMV Europay, MasterCard, and Visa ESC Escape ETX End of Text LF Line Feed LRC Longitudinal Redundancy Check NAK Negative Acknowledgement message PCI Payment Card Industry POS Point of Sale RS Record Separator STX Start of Text US Unit Separator XOR Exclusive OR




(49)



Version 2.2.0





3 Index 1 Revision history ................................................................................................................. 2 2 Abbreviations ..................................................................................................................... 4 3 Index ................................................................................................................................. 5 4 Introduction ........................................................................................................................ 9 5 Sending and receiving data ..............................................................................................10

5.1 Connection ..................................................................................................................10 5.2 Encoding .....................................................................................................................11 5.3 Communication endpoints ...........................................................................................11 5.4 Message format ...........................................................................................................11

5.4.1 Frame .....................................................................................................................11 5.4.2 Sequence numbering ..............................................................................................12 5.4.3 Data ........................................................................................................................12 5.4.4 Data elements .........................................................................................................12

5.4.4.1 Data content encoding......................................................................................13 5.4.5 LRC .........................................................................................................................13 5.4.6 DLE substitution ......................................................................................................14

5.5 Message max length ....................................................................................................14 5.6 Timeouts and resends .................................................................................................14 5.7 PING messages...........................................................................................................15

6 Messages .........................................................................................................................16 6.1 Message type identifiers ..............................................................................................16 6.2 Sale .............................................................................................................................16 6.3 Logon ..........................................................................................................................16 6.4 Refund .........................................................................................................................16 6.5 Reversal ......................................................................................................................17 6.6 CFT (not yet implemented) ..........................................................................................17 6.7 Settle ...........................................................................................................................17 6.8 Get Transaction ...........................................................................................................17 6.9 Transaction List ...........................................................................................................17 6.10 Initialize .......................................................................................................................17 6.11 Software Update ..........................................................................................................17 6.12 Get Information ............................................................................................................17 6.13 Authorize .....................................................................................................................18 6.14 Increment (not yet implemented) .................................................................................18 6.15 Finalize ........................................................................................................................18 6.16 Release .......................................................................................................................18 6.17 Print .............................................................................................................................18 6.18 Cancel .........................................................................................................................18 6.19 Connect .......................................................................................................................18 6.20 Send ............................................................................................................................18 6.21 Receive .......................................................................................................................19 6.22 Disconnect ...................................................................................................................19 6.23 Dialog ..........................................................................................................................19 6.24 Read Card ...................................................................................................................19

7 Data elements ..................................................................................................................20 7.1 Data element types and identifiers ...............................................................................20




(49)



Version 2.2.0





7.2 Result ..........................................................................................................................22 7.3 Status ..........................................................................................................................23 7.4 Transaction Result .......................................................................................................23 7.5 Print Receipt ................................................................................................................23 7.6 Cardholder Language ..................................................................................................23 7.7 Merchant Language .....................................................................................................23 7.8 Cashier Id ....................................................................................................................23 7.9 Register Id ...................................................................................................................23 7.10 Transaction Type .........................................................................................................24 7.11 Currency Code ............................................................................................................24 7.12 Currency Symbol .........................................................................................................24 7.13 Base Amount ...............................................................................................................24 7.14 VAT Amount ................................................................................................................24 7.15 Surcharge Amount .......................................................................................................24 7.16 Cashback Amount .......................................................................................................24 7.17 Extra Amount ...............................................................................................................24 7.18 Total Amount ...............................................................................................................24 7.19 Internal Reference .......................................................................................................25 7.20 External Reference ......................................................................................................25 7.21 Original Internal Reference ..........................................................................................25 7.22 Original External Reference .........................................................................................25 7.23 Batch Reference ..........................................................................................................25 7.24 Samport Reference ......................................................................................................25 7.25 Retrieval Reference .....................................................................................................25 7.26 Reversal Reference .....................................................................................................25 7.27 Settle Reference ..........................................................................................................25 7.28 Internal Reference List .................................................................................................25 7.29 Timestamp ...................................................................................................................25 7.30 Entry Mode ..................................................................................................................25 7.31 Verification Method ......................................................................................................26 7.32 Verification Option .......................................................................................................26 7.33 Onboard (not yet implemented) ...................................................................................26 7.34 Authorization Method ...................................................................................................26 7.35 Authorization Option ....................................................................................................26 7.36 Authorization Responder .............................................................................................27 7.37 Account Type ...............................................................................................................27 7.38 Financial Institution ......................................................................................................27 7.39 SPDH Response Code ................................................................................................27 7.40 Approval Code .............................................................................................................27 7.41 Masked PAN ................................................................................................................27 7.42 EMV Data ....................................................................................................................28 7.43 Encrypted Information ..................................................................................................28 7.44 Merchant Information ...................................................................................................28 7.45 Maintenance Status .....................................................................................................28 7.46 Custom Data ................................................................................................................29 7.47 Host .............................................................................................................................29 7.48 Data .............................................................................................................................29 7.49 Dialog Id ......................................................................................................................29 7.50 Dialog Text ..................................................................................................................30




(49)



Version 2.2.0





7.51 Dialog Result ...............................................................................................................30 7.52 Enable Dialog ..............................................................................................................30 7.53 Card Insertion Timeout ................................................................................................30 7.54 Echo Data ....................................................................................................................30 7.55 Terminal Id...................................................................................................................30 7.56 Acquirer Id ...................................................................................................................30 7.57 Merchant Id ..................................................................................................................31 7.58 Enable External Networking .........................................................................................31 7.59 Token ..........................................................................................................................31 7.60 Product Name ..............................................................................................................31 7.61 Cardholder Name ........................................................................................................31 7.62 ISO Response Code ....................................................................................................31 7.63 Max Length ..................................................................................................................31 7.64 Timeout .......................................................................................................................31 7.65 Receipt Data ................................................................................................................31 7.66 Dialog Title...................................................................................................................31 7.67 Dialog Type .................................................................................................................32 7.68 Dialog Options .............................................................................................................32 7.69 Card Data Request ......................................................................................................32 7.70 Card Data ....................................................................................................................32 7.71 Entry Option .................................................................................................................33 7.72 Closing Reference .......................................................................................................33 7.73 Bonus ..........................................................................................................................33 7.74 Protocol Version ..........................................................................................................33 7.75 Preferred Protocol Version ...........................................................................................33 7.76 Key ..............................................................................................................................33 7.77 Software Version .........................................................................................................33 7.78 Software Compatibility .................................................................................................33 7.79 Target Software Version ..............................................................................................33 7.80 Target Software Compatibility ......................................................................................34 7.81 Unmasked PAN ...........................................................................................................34

8 Request and response matrices .......................................................................................35 8.1 Financial messages .....................................................................................................35 8.2 Dialog and network messages .....................................................................................36 8.3 Other messages ..........................................................................................................36

9 Sample messages ............................................................................................................37 9.1 Sale request message .................................................................................................37 9.2 Sale response message ..............................................................................................37 9.3 Application layer example cases ..................................................................................42

9.3.1 Sale .........................................................................................................................42 9.3.2 Sale with dialogs and external networking ...............................................................42 9.3.3 Cancelled sale ........................................................................................................42

10 Link layer state machine ...................................................................................................43 10.1 Registers .....................................................................................................................43 10.2 Operations ...................................................................................................................43 10.3 State table ...................................................................................................................44

11 Receipt formatting ............................................................................................................46 11.1 Syntax .........................................................................................................................46 11.2 Command scope..........................................................................................................46




(49)



Version 2.2.0





11.3 Receipt sections ..........................................................................................................46 11.4 Conditions....................................................................................................................46 11.5 Alignment ....................................................................................................................47 11.6 Style ............................................................................................................................47 11.7 List of commands .........................................................................................................48 11.8 Examples .....................................................................................................................48

11.8.1 Shopping items .......................................................................................................48 11.8.2 Replace header and footer ......................................................................................48




(49)



Version 2.2.0





4 Introduction This document describes the Host to Terminal (Host2T) protocol which is used for communication between Samport payment terminals and other POS devices such as cash registers and taximeters. By using the protocol another POS device can initiate transactions such as sales, refunds and settlements which are then securely completed by the terminal in accordance with industry regulations. The initiating party in a transaction is referred to as a host in this document. Note that this document only specifies Host2T version 2 and later as version 2 is not backwards compatible. Some of the content of this document originates from earlier specifications.




(49)



Version 2.2.0





5 Sending and receiving data Data sent using Host2T is encapsulated in messages which consist of a header, a footer and optionally one or several data elements. A message may be either a transaction command or response, a PING, an acknowledgement (ACK) or a negative acknowledgement (NAK). The host initiates a transaction such as a sale by sending a corresponding command. If the command is received correctly by the terminal, the host will get an acknowledgement back. The terminal then completes the sale and finally sends a response. The host acknowledges the response and the terminal is then ready to receive a new command. In some cases the terminal needs to exchange information with the host during the execution of a command. In these cases the terminal sends the appropriate request message and the host sends the appropriate response message in the course of the transaction, and finally the terminal sends the transaction response. The host can always send a cancel message during a transaction. The terminal will acknowledge the cancel message and then make a best effort to actually cancel the transaction. There is no cancel response message, the result of the cancel request will instead be available in the transaction response. Depending on the configuration of the host and terminal respectively, the terminal may sometimes send messages outside of any host initiated transaction. This is the case for example if the terminal initiates an automatic settlement and needs to communicate with the host to complete the transaction. The details of the data transmission process should preferably be abstracted in the host and terminal applications to a link layer which manages acknowledgements, message resends etc. The header and footer part of the message format is intended to be used by the link layer while the data part is intended to be used by the application layer.

5.1 Connection Connection to the terminal is established through RS232, USB (virtual serial port profile), Bluetooth (serial port profile), or TCP/IP. For RS232, USB, and Bluetooth based communication the baud rate is 115200 with 8 data bits, no parity, one stop bit, and no flow control. For TCP/IP based communication the terminal acts as a server, and the port used is configured per terminal. The terminal will accept only one TCP connection at a time. If the connection is dropped, the terminal will automatically start listening on the specified port. It is recommended to keep the connection open for multiple transactions. The method of communication is configured using a web interface and is outside the scope of this document. Note that certain terminal configurations will default to the only viable method of communication no matter the web interface setting. For example an iPP350 connected using a serial cable will default to Host2T 2 over RS232. Terminals using Bluetooth to communicate will enter sleep mode after a while. This will make the terminal inaccessible from the cash register as it’s shutting down the Bluetooth hardware. There are two workarounds for this problem – increasing the sleep mode timeout, or having




(49)



Version 2.2.0





the merchant press a key in order to wake the terminal to make it ready for communication. When using the latter solution, the cash register needs to close and reopen the serial port.

5.2 Encoding Data sent in Host2T is generally encoded using Latin-1 and textual representation of numeric data, e.g. the integer value 2 is represented by the byte value 0x32 which corresponds to the character ‘2’ in the Latin-1 code page. The only exceptions to this encoding rule are those data elements that are defined to carry binary content, and also the control characters ETX, STX, RS, US and DLE which are defined in ASCII to have the following values:

Control character Value

STX (start of text) 0x02

ETX (end of text) 0x03

DLE (data link escape) 0x10

RS (record separator) 0x1E

US (unit separator) 0x1F Table 1 - Control characters

5.3 Communication endpoints The terminal may send packages that are intended for an internet resource rather than the host itself. This is indicated by the Target endpoint field in the message header. This field may have the following values:

Target endpoint value Intended receiver

‘000’ If the message is sent by the terminal, the intended receiver is the host.

‘001’ If the message is sent by the terminal, the intended receiver is an internet host.

Table 2 - Communication endpoints

By using the endpoint 001, the terminal can take advantage of an external internet connection (possibly provided by the host) which is beneficial if the terminal’s own connection is slow or non-existing. Note that this functionality must be enabled in the terminal and/or in a request message.

5.4 Message format

5.4.1 Frame

The data frame is used by the link layer and encloses the actual data. The content of the data section is not relevant to the link layer.

Field Length [bytes] Description

STX 1 Package start token.

Protocol version 6 The Host2T version that the package corresponds to.

Target endpoint 3 The intended receiving endpoint.




(49)



Version 2.2.0





Sequence number 3 The sequence number of this message, or the sequence number of the message being ACK:ed/NAK:ed.

Type 1 Either: ‘0’: application message with data content ‘1’: PING ‘2’: ACK ‘3’: NAK

Content length 6 The length of the content part. The content length is ‘000000’ for ACKs and NAKs.

[Data] Variable The content carried by this message, if any. This part of the frame is not parsed by the link layer.

LRC 3 Longitudinal Redundancy Check value.

ETX 1 Package end token. Table 3 – The Host2T message format. Please refer to the data element section of this specification for the

format of the data elements.

5.4.2 Sequence numbering

The host and terminal each keep a separate message sequence number counter for each target endpoint. The sequence number should be increased in every new message, unless the same message is resent due to a NAK or missing ACK. After initialization, the counter of the initialized entity should be set to the highest possible value (999) and the receiving entity should always ACK messages with this sequence number (on link layer level, the function corresponding to the message may still be denied on application level). The following messages use the range 0-998 with wrap around after 998. By starting with the highest possible sequence number it is guaranteed that messages from an entity that has been restarted are always accepted.

5.4.3 Data

The content part of a frame with type 0 is a Host2T application message as defined below:

Field Length (bytes) Description

Message type 3 A valid Host2T function command or response type as defined by this specification.

RFU 1 Reserved for future use. This byte should be ignored.

Number of data elements.

3 The number of data elements carried by this package. May be ‘000’.

[Data elements] Variable The data elements carried by this message, if any.

Table 4 - Data format.

5.4.4 Data elements

Most messages carry one or several data elements. A sale response for example may contain data elements concerning amount, currency and other details of the sale. Some data elements are mandatory in specific messages but normally they are optional. A command message may contain elements specifying transaction options and a response may contain optional elements




(49)



Version 2.2.0





holding data that was used in the transaction. Mandatory elements may only be mandatory under specific circumstances. It is important that the host application does not assume that data elements are always available because there is no guarantee that they are.

Field Length [chars] Description

Type 3 The data element type.

Content length 6 The length of the following content.

Content Variable The actual data content. Table 5 - Data element format.

5.4.4.1 Data content encoding

The content field of a data element can hold several different types of data. The encoding is done in the following way:

Data type

Encoding

Integer 12 character Latin-1 decimal string, left padded with ‘0’. For example, the value 210 is encoded as ‘000000000210’. Negative values are encoded using a preceding ‘-‘ character. For example, the value -210 is encoded as ‘-00000000210’. This encoding allows the integer value to be parsed using the C sscanf function with the %d conversion type. Implementers needs to make sure that the integer type used internally can represent the largest possible value ‘9999 9999 9999’ and lowest possible value ‘-999 9999 9999’ respectively. In C, this could be the int64 type.

Boolean 1 character Latin-1, either ‘1’ (TRUE) or ‘0’ (FALSE).

Char Latin-1 alphanumeric character.

String Latin-1 alphanumeric string. The data element content length indicates the length of the string.

String list

A list of Latin-1 strings, separated by US characters. There is no US after the last string. The data element content length indicates the length of the list.

String map

Uses the same encoding as the string list. The first item in the list represents the first key, the second item represents the first value etc. Note that the list must be of even length to be a valid map since keys and values always comes in pairs.

Binary (bytes)

Raw binary data, encoded using DLE substitution to make sure that any STX and ETX characters are handled correctly at the receiving end. See the section on DLE substitution for details.

Table 6 - Data content encoding rules for different types.

Amounts are always represented in the lowest value of the currency, i.e. the fractional unit of the currency. For example, 20 SEK is represented as 2000 öre and 20 Euro is represented as 2000 cents. Amount fields do not include any currency symbol. That information is sent in a separate currency code field.

5.4.5 LRC

The LRC is a check sum calculated by XOR of each character in the message, from STX up until the last data element character (if any). The LRC should be verified each time a message is received. If the LRC is correct an acknowledgment message should be sent, otherwise a negative acknowledgement (NAK) should be sent.




(49)



Version 2.2.0





Figure 1 - LRC algorithm.

5.4.6 DLE substitution

The STX and ETX characters that are used to indicate the start and the end of messages respectively may also occur in the content of binary data elements. To make sure that the receiving end of the link layer interprets STX and ETX characters correctly at all times, substitution using the DLE character is used on the binary data before it is sent. The substitution is done in the following way:

Binary data Substituted data

STX (0x02) DLE, DC1 (0x10, 0x11)

ETX (0x03) DLE, DC2 (0x10, 0x12)

DLE (0x10) DLE, DLE (0x10, 0x10) Table 7 - binary data substitution table.

Note that the data length is increased if substitution is done (single characters is replaced by two characters) and the message content length value needs to be adjusted appropriately. The receiving end uses inverse substitution to recreate the original data. The procedure is clarified by the example below:

Message before subsitution: [Header: STX..][Data: ..STX..DLE,DLE..][Footer: ..ETX]

Message after DLE substitution

[Header: STX..][Data: ..DLE,DC1..DLE,DLE,DLE,DLE..][Footer: ..ETX]

5.5 Message max length All messages, except where otherwise noted, are limited to 4096 bytes. The max length is the length of the message before DLE substitution (after inverse substitution).

5.6 Timeouts and resends If a message is not acknowledged within 1 second after it has been sent it is assumed to be lost in transmission and should be resent using the same sequence number. Each message may be sent up to 5 times. If an entity receives a message with an identical sequence number as the last ACK:ed message, it should respond with a new ACK since the last one can be assumed to have been lost in transmission. If a message results in a NAK it should also be resent up to 5 times.

LRC = 0;

for each char c in Message

{

LRC = LRC XOR c;

}




(49)



Version 2.2.0





5.7 PING messages The host or terminal may send a PING message at any time to verify that the link is working correctly. When a PING is received it should be acknowledged by the receiving entity immediately. Note that this message is only sent by the link layer, never by the application layer. The link layer may inform the application layer about the status of the link through callbacks.




(49)



Version 2.2.0





6 Messages

6.1 Message type identifiers

Message type Identifier (Request )

Identifier (Response)

Sale 0 1

Refund 2 3

Reversal 4 5

CFT 6 7

Authorize 8 9

Increment 10 11

Finalize 12 13

Release 14 15

Logon 16 17

Settle 18 19

Get Transaction 20 21

Transaction List 22 23

Initialize 24 25

Software Update 26 27

Get Information 28 29

Connect 30 31

Send 32 33

Receive 34 35

Disconnect 36 37

Dialog 38 39

Cancel 40 n/a

Print 42 43

Read Card 44 45 Table 8 - Message types and identifiers.

6.2 Sale Performs a sale transaction. CURRENCY CODE is mandatory if any amount is specified.

6.3 Logon Forces the terminal to go online and send any locally stored offline transactions online.

6.4 Refund Performs a refund where money is transferred from the merchant to a customer account. CURRENCY CODE is mandatory if any amount is specified. For AUTHORIZATION METHOD only “2” (offline) is valid if this data element is present.




(49)



Version 2.2.0





6.5 Reversal Performs a reversal of a previous sale or refund. A reversal can only be performed if the original transaction has not yet been settled, if it has been settled a refund should be performed instead. If a receipt is required and not printed by the terminal, the host must call GET TRANSACTION using REVERSAL REFERENCE to obtain the original transaction data.

6.6 CFT (not yet implemented) A CFT (Credit Fund Transfer) transfers money to the cardholder’s account. The difference between a CFT and a refund is that a refund is used to reimburse a customer for a previous payment while a CFT is not connected to a previous sale. CFT is only supported if there is an agreement in place between the merchant and the acquirer.

6.7 Settle A settlement performs a logon to upload any offline transactions, and sends a settlement message to settle all unsettled transactions for the terminal. The total amount is calculated as debit totals – credit totals.

6.8 Get Transaction Retrieves data from a previous transaction. The ORIGINAL INTERNAL REFERENCE or ORIGINAL

EXTERNAL REFERENCE can be used to retrieve a specific transaction. If none of these fields are present, the last transaction will be returned. If the PRINT RECEIPT flag is set, the original transaction receipt will also be printed by the terminal.

6.9 Transaction List Retrieves a list of all transactions in the current batch. If the PRINT RECEIPT flag is set, the list will also be printed by the terminal. Note that the message length may exceed 4096 bytes.

6.10 Initialize Updates the configuration parameters of the terminal. This operation may end with the device rebooting. In this case the calling application will get a response with the appropriate result code first.

6.11 Software Update Performs software update. This operation may take several minutes and normally ends with the device rebooting. In this case the calling application will get a response with the appropriate result code first.

6.12 Get Information Requests terminal information such as terminal id and merchant id. As of Host2T 2.2 it is no longer possible to specify which information to request, and all available information is returned in discrete elements.




(49)



Version 2.2.0





6.13 Authorize Used for post charge transactions. Performs an authorization for a token resulting in a reserved amount on the cardholder’s bank account.

6.14 Increment (not yet implemented) Used for post charge transactions. Increases the reserved amount for a token.

6.15 Finalize Used for post charge transactions. Finalizes the transaction associated with a token and releases the token.

6.16 Release Used for post charge transactions. Reverses a previous authorization and releases a token.

6.17 Print Print text using the terminal printer. The text to print is supplied in the RECEIPT DATA element and should be formatted according to section 11.

6.18 Cancel Cancels an ongoing function if possible. CANCEL is used by the host to abort an ongoing function, or by the terminal to abort a terminal-to-host function (not yet implemented). There is no corresponding CANCEL response message, instead the result code of the function response indicates if the cancellation was successful or not. Note that the endpoint indicates the message flow to cancel. It is possible for the terminal to send CANCEL for both a DIALOG and a RECEIVE message independently.

6.19 Connect CONNECT is sent by the terminal to an external entity (normally the host) to set up a TCP/IP connection using an external network interface. The host should return RESULT 0 if a connection was established, or RESULT 300 if an error occurred. The CONNECT message may be sent by the terminal outside of a host initiated transaction, for example as part of an automatic settlement. Note that the external networking option must be selected in the terminal settings or specified in the ENABLE EXTERNAL NETWORKING data element of a request from the host to enable network (CONNECT, SEND, RECEIVE, and DISCONNECT) messages. External networking is automatically enabled for terminals which have no other means of communication, for example an iPP350 connected using a serial cable.

6.20 Send SEND is sent by the terminal to an external entity (normally the host) to send data using an external network interface. Note that a connection is always opened first using the CONNECT command. The host should return RESULT 0 when the data has been sent or queued on an output buffer. The terminal may send several SEND messages before the connection is closed.




(49)



Version 2.2.0





6.21 Receive RECEIVE is sent by the terminal to an external entity (normally the host) to receive data using an external network interface. This message is always preceded by a CONNECT message. The host should return RESULT 0 when data is available, or RESULT 301 when the timeout has expired. Other network errors should return RESULT 300. The length of the data returned may not exceed MAX LENGTH.

6.22 Disconnect DISCONNECT is sent by the terminal to an external entity to close a TCP/IP connection on an external network interface. The host should always return RESULT 0.

6.23 Dialog DIALOG is sent by the terminal to the host to inform about the current progress for display purposes and/or to request information. Note that the dialog option must be selected in the terminal settings or specified in the ENABLE DIALOG data element of a request from the host to enable DIALOG messages. The DIALOG message may be sent by the terminal outside of a host initiated transaction, for example to inform about an automatic settlement.

6.24 Read Card READ CARD uses the terminal to read data from a card. Each item of data to be read is specified in the CARD DATA REQUEST list and any data read is returned in the CARD DATA field. The time to wait for a card to be read is specified in the CARD INSERTION TIMEOUT field. When a READ CARD request has been issued, the terminal will wait for a card to be read until the timeout expires or CANCEL is sent to the terminal. If a card is swiped, inserted, or tapped but cannot not be read, result code 210 (card not read) will be returned. Please note that magnetic stripe track data will not be returned for payment cards due to PCI regulations. For these cards result code 211 (card not allowed) will be returned. Only cards with a PAN starting with ‘9’ (national assignment) are allowed.




(49)



Version 2.2.0





7 Data elements This section specifies the data elements used as parameters to, and returned from, the Host2T functions. Most elements are “printer ready”, meaning that they conform to the requirements for receipt printing without modification. All Host2T response data elements except the Host2T protocol result should be assumed optional. The application should handle missing elements appropriately. Request elements are optional if not mandatory in the function description. Many output parameters are intended to be used for receipt printing in configurations where the host is responsible for printing the transaction receipt, e.g. AUTHORIZATION METHOD and VERIFICATION METHOD. The host does not need to regard this type of parameters in configurations where they are not relevant.

7.1 Data element types and identifiers

Data element Type Identifier Availability

Result integer 0 2.0

Status integer 1 2.0

Transaction Result integer 2 2.0

Print Receipt boolean 3 2.0

Cardholder Language string 4 2.0

Merchant Language string 5 2.0

Cashier Id string 6 2.0

Register Id string 7 2.0

Transaction Type integer 8 2.0

Currency Code string 9 2.0

Currency Symbol string 10 2.0

Base Amount integer 11 2.0

VAT Amount integer 12 2.0

Surcharge Amount integer 13 2.0

Cashback Amount integer 14 2.0

Extra Amount integer 15 2.0

Total Amount integer 16 2.0

Internal Reference string 17 2.0

External Reference string 18 2.0

Original Internal Reference string 19 2.0

Original External Reference string 20 2.0

Batch Reference string 21 2.0

Samport Reference string 22 2.0

Retrieval Reference string 23 2.0

Reversal Reference string 24 2.0

Settle Reference string 25 2.0

Internal Reference List string list 26 2.0

Timestamp string 27 2.0

Entry Mode char 28 2.0

Verification Method char 29 2.0

Verification Option char 30 2.0




(49)



Version 2.2.0






Onboard boolean 31 2.0

Authorization Method char 32 2.0

Authorization Option char 33 2.0

Authorization Responder char 34 2.0

Account Type char 35 2.0

Financial Institution string 36 2.0

SPDH Response Code string 37 2.0

Approval Code string 38 2.0

Masked PAN string 39 2.0

EMV Data string map 40 2.0

Encrypted Information string list 41 2.0

Merchant Information string map 42 2.0

Maintenance Status integer 43 2.0

Reserved n/a 44 n/a

Reserved n/a 45 n/a

Custom Data string map 46 2.0

Reserved n/a 47 n/a

Reserved n/a 48 n/a

Terminal Info Request string list 49 2.0

Terminal Info string map 50 2.0

Host string 51 2.0

Data binary 52 2.0

Dialog Id integer 53 2.0

Dialog Text string 54 2.0

Dialog Result string 55 2.0

Enable Dialog char 56 2.0

Card Insertion Timeout integer 57 2.0

Echo Data string 58 2.0

Terminal Id string 59 2.0

Acquirer Id string 60 2.0

Merchant Id string 61 2.0

Enable External Networking boolean 62 2.0

Token string 63 2.0

Product Name string 64 2.0

Cardholder Name string 65 2.0

ISO Response Code string 66 2.0

Timeout integer 67 2.0

Max Length integer 68 2.0

Receipt Data string 69 2.0

Dialog Title string 70 2.1

Dialog Type integer 71 2.1

Dialog Options string map 72 2.1

Card Data Request string list 73 2.1

Card Data string map 74 2.1

Entry Option char 75 2.1

Closing Reference string 76 2.1




(49)



Version 2.2.0






Bonus integer 77 2.1

Protocol Version string 78 2.2

Preferred Protocol Version string 79 2.2

Key string 80 2.2

Software Version string 85 2.2

Software Compatibility string list 86 2.2

Target Software Version string 87 2.2

Target Software Compatibility string list 88 2.2

Unmasked PAN string 89 2.2 Table 9 - Data element types and identifiers.

7.2 Result The Host2T result code. For some functions there are other data elements that give a more detailed description of the function result. Result codes in the 1XX range indicates that there was an error on the protocol level (such as a broken message), while result codes in the 2XX range indicates exceptional conditions (not necessarily errors) on the application level. The 3XX range is used for network messages and is never returned as a result of a transaction.

0 – successful

100 – general (unspecified) error

101 – service not responding

102 – service timeout

103 – broken message

104 – illegal field

105 – missing field

106 – field format error

107 – unsupported protocol version (for 2.2 and later)

200 – cancelled

201 – parameter update error

202 – software update error

203 – software update will reboot

204 – settlement required

205 – password error

206 – failed to get transaction

207 – parameters invalid

208 – general configuration error

209 – no communication

210 – card not read (READ CARD command)

211 – card not allowed (READ CARD command)

212 – token already acquired

213 – token already released

214 – token limit reached

215 – acquired tokens exist, please finalize or release.

216 – token locked

217 – amount too high

218 – terminal busy




(49)



Version 2.2.0





300 – network error

301 – network timeout

7.3 Status Payment kernel status value, for informational purposes only. Should be printed on the receipt for declined transactions.

7.4 Transaction Result Indicates the result of a transaction. The following values are defined:

0 – Approved

1 – Declined

2 – Cancelled

7.5 Print Receipt The print receipt flag is a boolean value telling the payment application to either print the transaction receipt (true), or let the host print the receipt (false). Note that it is up to the host to handle eventual signature verification if the payment application does not print receipts. A transaction must be reversed if the cardholder’s signature is not approved. The verificationMethod response message parameter is used by the host to find out if the transaction is to be verified by signature or not.

7.6 Cardholder Language The default language used to display information directed to the card holder. If another language is set during the transaction, this setting will have no effect. The language is encoded as a two character string, following the ISO639-1 standard. Currently, the following language codes are accepted:

“en” – English

“sv” – Swedish

“no” – Norwegian

“da” – Danish

“fi” – Finnish

“de” – German

“es” – Spanish

“fr” – French

7.7 Merchant Language The language used to display information directed to the merchant. The language is encoded as a two character string, following the ISO639-1 standard. Please see the list of supported languages in the CARDHOLDER LANGUAGE parameter description.

7.8 Cashier Id The cashier id is a 1-6 digit string used to identify the cashier initiating the transaction.

7.9 Register Id The register id is a 1-6 digit string used to identify the register initiating the transaction.




(49)



Version 2.2.0





7.10 Transaction Type The type of transaction according to the list below.

0 – logon

1 – sale

2 – refund

3 – reversal

4 – settle

5 – authorize

6 – increment

7 – finalize

8 – release

7.11 Currency Code The currency used in the transaction, with codes according to ISO4217. The value should be a string composed of four digits, e.g. Swedish kronor is coded as “0752”.

7.12 Currency Symbol The currency symbol in ASCII, e.g. ‘SEK’ for Swedish kronor.

7.13 Base Amount The base amount specified in the lowest unit of the currency. All amounts are assumed specified using exponent 0.

7.14 VAT Amount Value added tax specified in the lowest unit of the currency.

7.15 Surcharge Amount Surcharge amount specified in the lowest unit of the currency. The surcharge amount is calculated by the terminal and only present in response messages.

7.16 Cashback Amount Cashback amount specified in the lowest unit of the currency.

7.17 Extra Amount Extra amount (for example TIP) specified in the lowest unit of the currency.

7.18 Total Amount Total amount specified in the lowest unit of the currency. The total amount is the sum of the base amount, VAT amount, surcharge amount, cashback amount, and extra amount.




(49)



Version 2.2.0





7.19 Internal Reference The internal reference is a 6 digit string generated by the kernel at transaction start. The internal reference shall be printed on the receipt as “receipt no”. The internal reference is unique within one batch.

7.20 External Reference The external reference is a 6 character alphanumeric string which may be supplied by the host at transaction start. The external reference must be unique within one batch.

7.21 Original Internal Reference Used in reversal transactions to specify which transaction that is to be reversed.

7.22 Original External Reference Used in reversal transactions to specify which transaction that is to be reversed.

7.23 Batch Reference The batch reference is a 3 digit string reference to the current batch.

7.24 Samport Reference The samport reference is a 12 digit string uniquely identifying the transaction in Samport’s system. The samport reference is returned in response to an online message.

7.25 Retrieval Reference The retrieval reference is a 12 digit string generated by the terminal at authorization.

7.26 Reversal Reference The reversal reference is the internal reference of the reversing transaction, or for the reversing transaction, the internal reference of the reversed transaction.

7.27 Settle Reference The settle reference is the internal reference of the settlingt transaction. For direct capture transactions this is normally the internal reference of the transaction itself.

7.28 Internal Reference List A list of internal references in the current batch.

7.29 Timestamp Time of transaction (authorization) as “YYMMDDHHMMSS”, or in case of a settlement, an object with two timestamps “from” and “to” denoting the time span of the batch.

7.30 Entry Mode Entry mode describing how the card information was obtained, according to:

“C” – chip




(49)



Version 2.2.0





“D” – magnetic stripe

“T” – manually entered using PIN pad

7.31 Verification Method Verification method describing how the cardholder was verified, according to:

“@” – signature

“A” – online PIN

“a” – offline PIN

“B” – online PIN and signature

“b” – offline PIN and signature

“/” – no CVM required

“-“ – no CVM performed

“ “ (space character) – failed

7.32 Verification Option Sent by the host to request that a specific method of cardholder verification is used during the transaction according to the values below:

“1” – force signature verification if possible

“2” – force PIN verification if possible Note that the terminal may decline the transaction if the requested option is not allowed. If this element is not supplied in the request the terminal will find the appropriate verification option depending on its configuration, the card, and possibly cashier selection during the transaction.

7.33 Onboard (not yet implemented) Used to specify that a transaction should be performed as an onboard sale if necessary (i.e. if it cannot be authorized as an online or normal offline sale). In response messages, the flag signals that the transaction was performed as an onboard sale. Onboard sales are only allowed if corresponding agreements between the merchant, the aquirer, and Samport are in place.

7.34 Authorization Method Authorization method describing how the transaction was authorized or attempted to be authorized, according to:

“1” – online

“2” – offline

“4” – phone, called bank for approval code

“5” – none, not authorized

7.35 Authorization Option Sent by the host request that a specific method of authorization is used during the transaction according to:

“1” – online authorization

“2” – offline authorization

“3” – phone authorization




(49)



Version 2.2.0





Note that the terminal may decline the transaction if the requested option is not allowed. If this element is not supplied in the request the terminal will find the appropriate authorization option depending on its configuration, the card, and possibly cashier selection during the transaction.

7.36 Authorization Responder Authorization responder describing which network entity responded to the authorization, according to:

“1” – authorized locally in terminal

“3” – authorized by DPC

“4” – authorized by DPC

“5” – authorized by issuer

“6” – interchange

“7” – interchange

“9” – authorized by merchant

“M” – manually entered approval code

7.37 Account Type If applicable to the card use, contains the account type chosen by the cardholder, according to:

“C” – credit account

“D” – debit account This data element is not directly printable as it is expected to result in a text string such as “debited savings account”.

7.38 Financial Institution The financial institution is a three character string containing an abbreviation for the financial institution handling the authorization, for example “AMX” for American Express.

7.39 SPDH Response Code The SPDH response code is a 3 digit string returned by Samport’s system at authorization. This code is only intended for receipt printing and no assumptions should be made based on the value. The host should use the transactionResult parameter to find out if a transaction was approved or not.

7.40 Approval Code The approval code is a 2-6 character alphanumeric string returned by the host or manually entered by the cashier in cases when a phone call to the bank has been required. Note, this element is only intended for receipt printing and should not be used to determine if the transaction was approved or not.

7.41 Masked PAN String containing the card’s primary account number, masked according to card scheme rules. Example: “XXXX XXXX XXXX 1234”




(49)



Version 2.2.0





7.42 EMV Data Array containing a list of EMV tag names and values intended for receipt printing. The following tags may be included in a transaction response (depending on the specific transaction and terminal configuration):

AID

TVR

TSI

IAD

ARC

ATC

PSN

AED

7.43 Encrypted Information Encrypted card information intended for receipt printing of offline transactions. Ensures that transactions are not lost if the terminal is damaged. Note that the information should only be printed on the merchant copy.

7.44 Merchant Information Merchant information as a key-value map. The information is normally printed at the top of the receipt, excluding the keys. The following keys are provided:

“name” – sales location name, e.g. “My sales location”

“address” – street address, e.g. “Shopping street 5”

“city” – postal code and city name, e.g. “12345 Big city”

“orgnr” – organization number, e.g. “1234567890”

“phonenr” – phone number, e.g. “08123456”

7.45 Maintenance Status The terminal maintenance status notifies the host of maintenance which should be performed.

0 – Terminal blocked. The terminal is prevented from making transactions by the backend system. This has to be cleared by Samport technical support. Once cleared, a settlement will reactivate the terminal.

1 – Parameter update available. New parameters are available and should be downloaded as soon as possible.

2 – Parameter update required. New parameters are available and must be downloaded before further transactions can be processed.

3 – Software update available. New software is available and should be downloaded as soon as possible.

4 – Software update required. New software is available and must be downloaded before further transactions can be processed.

5 – Software update available, but incompatible with current protocol version.

6 – Software update required, but incompatible with current protocol version.




(49)



Version 2.2.0





7.46 Custom Data A map of key-value pairs which can be used by the host to associate custom data with the transaction. The host cannot include more than 5 key-value pairs in a request message. The maximum length of each key and value is 16 alphanumeric characters and 32 alphanumeric characters respectively. The custom data is stored in the terminal and is returned to the host if the transaction is looked up using the GET TRANSACTION function.

7.47 Host The address of an internet resource that data is sent to using the send command. The address should be on the form IP:PORT, e.g. 123.456.789.000:25000.

7.48 Data The data that is sent to, or received from, an internet resource during the execution of a send command.

7.49 Dialog Id The dialog id is used to identify the type of dialog that a dialog message corresponds to. This information is used by the host together with the DIALOG TEXT data element (if present) to display the correct dialog to the operator. The following dialog id:s are defined:

ID Dialog Type Primary responder

0 Informational, undefined none n/a

1 Interactive, undefined none n/a

101 Enter cashier id numeric entry operator

102 Enter register id numeric entry operator

103 Select currency selection operator

104 Enter base amount amount entry operator

105 Enter VAT amount amount entry operator

106 Enter cashback amount amount entry operator

107 Enter extra amount amount entry cardholder

108 Amount ok? confirmation cardholder

109 Read card information cardholder

Options: 1 – Manual entry

110 Card read information n/a

111 Card not read information n/a

112 Force fallback? confirmation operator

113 Enter PAN information operator*

114 Enter expiration information operator*

115 Enter CVV information operator*

116 Select application selection cardholder

117 Card selected information n/a

Extra fields: Product Name

118 Select language selection cardholder

119 Select account type selection cardholder

Options: 1 – Debit, 2 – Credit




(49)



Version 2.2.0





120 Enter PIN information cardholder

Options: 1 – Bypass PIN

121 Bypass PIN? confirmation operator

122 Signature ok? confirmation operator

123 Force approval?** confirmation operator

124 Approve offline? confirmation operator

125 Call bank/Enter approval code text entry operator

126 Remove card information cardholder

*entry must be performed by operator directly on terminal **reserved for future use

7.50 Dialog Text In dialog request messages this is the dialog text displayed to the cardholder but in the operator’s language. Note that the host should not use this data element to determine the type of dialog; the DIALOG ID element is used for that purpose.

7.51 Dialog Result If a dialog message requires input from the operator, for example answering yes or no, selecting from a list of options, or entering data, DIALOG RESULT shall contain the decision.

7.52 Enable Dialog Enables dialog messages, either informational or interactive. The dialog messages will be sent during the execution of the current transaction.

“0” – disabled

“1” – informational dialogs only, operator interaction performed on terminal

“2” – interactive dialogs enabled, operator interaction performed on host

7.53 Card Insertion Timeout The time in milliseconds that the terminal will wait for card insertion before aborting a sale or refund. Specifying 0 disables the timeout.

7.54 Echo Data The ECHO DATA element is a text string which can be used to identify a particular message session (request message – response message). If specified in the a request message it will be echoed in the corresponding response message.

7.55 Terminal Id The terminal identification string. This element is intended for receipt printing only.

7.56 Acquirer Id The merchant’s account number in the acquiring bank. This element is intended for receipt printing only.




(49)



Version 2.2.0





7.57 Merchant Id The merchant’s identification number in Samport’s system. This element is intended for receipt printing only.

7.58 Enable External Networking If set to TRUE, the terminal may use an external network interface (possibly provided by the host) to communicate with internet resources during the execution of a command. If set to FALSE, the terminal will only use its own internet connection. By allowing the terminal to use an external interface the transaction time can sometimes be reduced and since all terminal communication is encrypted from end to end there is no negative impact on security. If this element is not supplied, the terminal will default to an internal setting.

7.59 Token A token is used for post charge transactions and is associated with a reservation on a cardholder’s account. The AUTHORIZE, INCREMENT, FINALIZE, and RELEASE operations all use tokens. The token consists of 1 to 32 numeric characters.

7.60 Product Name The card product name, e.g. VISA.

7.61 Cardholder Name The name of the cardholder.

7.62 ISO Response Code The two digit response code according to ISO8583.

7.63 Max Length This element indicates the maximum amount of data that a RECEIVE call may return. Note that there may be additional data available that can be accessed through additional calls to RECEIVE.

7.64 Timeout The maximum time [milliseconds] to wait for networking functions to complete. This may be the wait time for connection in the CONNECT call, the wait time for incoming data in the RECEIVE call or the wait time for data being sent in the SEND call.

7.65 Receipt Data Formatted receipt data according to section 11. The receipt data is added to the cardholder receipt and/or the merchant receipt. The receipt data field is also used when utilizing the terminal as a printer with the PRINT message.

7.66 Dialog Title The dialog title is a short string indicating the context of the current dialog, for example “SALE SEK 45,00”, which may be displayed to the operator.




(49)



Version 2.2.0





7.67 Dialog Type The dialog type specifies how the supplied dialog fields should be interpreted and what values are allowed in the dialog result field. The following dialog types are defined:

1 – Information The message in DIALOG TEXT should be displayed to the operator. If the DIALOG

OPTIONS list is empty no action is necessary. If the DIALOG OPTIONS field contains one or more items, the operator may be required to select an action to proceed.

2 – Confirmation The message in DIALOG TEXT should be displayed to the operator. Option “0” is “no” and option “1” is “yes”.

3 – Selection The message in DIALOG TEXT along with the list of options in DIALOG OPTIONS should be displayed to the operator. The operator may be required to select an item to proceed.

4 – Amount entry The message in DIALOG TEXT should be displayed to the operator. The operator may be required to enter an amount to proceed. The entered amount should always be represented in the smallest unit of the currency.

5 – Numeric entry The message in DIALOG TEXT should be displayed to the operator. The operator may be required to enter a number to proceed.

6 – Text entry The message in DIALOG TEXT should be displayed to the operator. The operator may be required to enter a text to proceed.

7 – Password entry The message in DIALOG TEXT should be displayed to the operator. The operator may be required to enter a password to proceed.

It is not necessary for a host to handle this field. If all texts and options are displayed to the operator, and a generic input method is provided, the operator can fully control the terminal by entering the appropriate actions into the DIALOG RESULT field.

7.68 Dialog Options The DIALOG OPTIONS field is a string map where each key is an action to be specified in the DIALOG RESULT field, and each value is a description of the action. Some dialogs have predefined options. See the description for DIALOG ID and DIALOG TYPE for more information.

7.69 Card Data Request The CARD DATA REQUEST field is a string list where each item represents some item of information to obtain from a card. Currently the following information can be requested:

“track2” – track 2 data from a magnetic stripe

“uid” – UID from an NFC device or tag Number of options in CARD DATA REQUEST is currently limited to one.

7.70 Card Data Card data read from a card as a string map where the key is the tag of the requested information as specified in the CARD DATA REQUEST field and the value is the data read, if any. The following information can be returned:




(49)



Version 2.2.0





“track2” – track 2 data as an ASCII string including start and end sentinels.

“uid” – NFC UID

7.71 Entry Option The entry option can be sent by the host to request that a specific method is used to read the card:

“T” – Manual entry of PAN

7.72 Closing Reference For an AUTHORIZE transaction the closing reference is the internal reference of the corresponding FINALIZE transaction, if any.

7.73 Bonus BONUS is an integer specifying the bonus related amount of the transaction. The exact interpretation of this field is up to the acquiring bank. The BONUS field is not counted towards the TOTAL AMOUNT.

7.74 Protocol Version The PROTOCOL VERSION element specifies the Host2T protocol version used for a request, for example “020200” for version 2.2. If no protocol version is specified, the terminal will assume 2.1. If the protocol version sent by the host is not supported by the terminal it will be signaled using result code 107 (unsupported protocol version) without processing the request.

7.75 Preferred Protocol Version The PREFERRED PROTOCOL VERSION element indicates the preferred (current) Host2T protocol version, for example “020200”. The host may continue using its current version, but should be upgraded to ensure future compatibility.

7.76 Key The KEY element is used to specify the unique key identifying a certified host system. The key is validated by the terminal and forwarded to Samport.

7.77 Software Version The SOFTWARE VERSION element contains the terminal software version, for example “SP900__103v1”.

7.78 Software Compatibility The SOFTWARE COMPATIBILITY element is a list of protocol versions supported by the current software version. Host2T 2.2 is represented as “HOST2T_020200”.

7.79 Target Software Version The TARGET SOFTWARE VERSION element contains the version of the software that the terminal would receive if updated, for example “SP900__104v1”.




(49)



Version 2.2.0





7.80 Target Software Compatibility The TARGET SOFTWARE COMPATIBILITY element is a list of protocol versions supported by the target software version. Host2T 2.2 is represented as “HOST2T_020200”. The terminal cannot be updated automatically if the protocol version implemented by the host is not present in the list. An update can still be forced by initiating it manually from the terminal menu.

7.81 Unmasked PAN The unmasked pan element is a string containing the clear text pan of the card. This element is only available for specific card schemes under specific circumstances, for example when a BankAxept card is used offline.




(49)



Version 2.2.0





8 Request and response matrices The following tables indicate ▼ mandatory, ♦ conditional, and ● optional fields in request and response messages. Please see the respective message and data element descriptions for specific information.

8.1 Financial messages

Lo

go

n r

eq

Lo

go

n r

sp

Sa

le r

eq

Sa

le r

sp

Refu

nd

req

Refu

nd

rsp

Reve

rsa

l re

q

Reve

rsa

l rs

p

CF

T r

eq

CF

T r

sp

Se

ttle

re

q

Se

ttle

rsp

Ge

t T

ran

s.

req

Ge

t T

ran

s.

rsp

Au

tho

rize r

eq

Au

tho

rize r

sp

Incre

men

t re

q

Incre

men

t rs

p

Fin

aliz

e r

eq

Fin

alz

ie r

sp

Rele

ase

re

q

Rele

ase

rsp

Result ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Status ● ● ● ● ● ● ● ● ● ● ● Transaction Result ● ● ● ● ● ● ● ● ● ● ● Print Receipt ● ● ● ● ● ● ● ● ● ● Cardholder Language ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● Merchant Language ● ● ● ● ● ● ● ● ● ● Cashier Id ● ● ● ● ● ● ● ● ● ● ● ● Register Id ● ● ● ● ● ● ● ● ● ● ● ● Transaction Type ● ● ● ● ● ● ● ● ● ● ● Currency Code ♦ ● ♦ ● ♦ ● ● ♦ ● ● ● ● Currency Symbol ● ● ● ● ● ● ● ● Base Amount ● ● ● ● ● ● ● ● ● ● ● ● ● ● Vat Amount ● ● ● ● ● Surcharge Amount ● ● ● ● ● ● Cashback Amount ● ● ● Extra Amount ● ● ● ● ● Total Amount ● ● ● ● ● ● ● ● ● Internal Reference ● ● ● ● ● ● ● ● ● ● ● External Reference ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● Original Internal Ref ● ● Original External Ref ● ● Batch Reference ● ● ● ● ● ● ● ● ● ● ● Samport Reference ● ● ● ● ● ● ● ● Retrieval Reference ● ● ● ● ● ● ● ● Reversal Reference ● ● Settle Reference ● ● ● ● ● ● ● ● Timestamp ● ● ● ● ● ● ● ● ● ● ● Entry Mode ● ● ● ● ● ● ● ● Verification Method ● ● ● ● ● ● ● ● Verification Option ● ● Onboard ● ● ● ● ● ● ● ● Authorization Method ● ● ● ● ● ● ● ● Authorization Option ● ● ● Auth. Responder ● ● ● ● ● ● ● ● Account Type ● ● ● ● ● ● ● ● Financial Institution ● ● ● ● ● ● ● ● SPDH Response Code ● ● ● ● ● ● ● ● ● ● Approval Code ● ● ● ● ● ● ● ● Masked PAN ● ● ● ● ● ● ● ● EMV Data ● ● ● ● ● ● ● ● Encrypted Information ● ● ● ● ● ● ● ● Merchant Information ● ● ● ● ● ● ● ● ● ● ● Maintenance Status ● ● ● ● ● ● ● ● ● ● ● Custom Data ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● Enable Dialog ● ● ● ● ● ● ● ● ● ● ● Card Insertion Timeout ● ● ● ● Echo Data ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● Terminal Id ● ● ● ● ● ● ● ● ● ● ● Acquirer Id ● ● ● ● ● ● ● ● ● ● ● Merchant Id ● ● ● ● ● ● ● ● ● ● ● Enable Ext. Network. ● ● ● ● ● ● ● ● ● ● Token ● ▼ ● ▼ ● ▼ ● ▼ ● Product Name ● ● ● ● ● ● ● ● Cardholder Name ● ● ● ● ● ● ● ● ISO Response Code ● ● ● ● ● ● ● ● ● ● Receipt Data ● ● ● ● ● ● ● ● ● ● Entry Option ● ● ● ● Closing Reference ● Bonus ● ● ● ● ● ● ● Protocol Version ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Preferred Protocol Version ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Key ● Target Software Version ● Target Software Compatibility ● Unmasked PAN ● ● ● ● ● ● ● ●




(49)



Version 2.2.0





8.2 Dialog and network messages

Can

ce

l re

q

Can

ce

l rs

p

Con

ne

ct

req

Con

ne

ct

rsp

Se

nd

re

q

Se

nd

rsp

Rece

ive r

eq

Rece

ive r

sp

Dis

co

nn

ect

req

Dis

co

nn

ect

rsp

Dia

log

re

q

Dia

log

rsp

Result ▼ ▼ ▼ ▼ ▼ Host ▼ Data ▼ ♦ Dialog Id ▼ Dialog Title ● Dialog Text ● Dialog Result ▼ Echo Data ● ● ● ● ● ● ● ● ● ● Product Name ● Max Length ▼ Timeout ▼ ▼ ▼ Dialog Type ▼ Dialog Options ●

8.3 Other messages

Tra

ns. L

ist

req

Tra

ns. L

ist

rsp

Initia

lize r

eq

Initia

lize r

sp

Sw

Upd

ate

re

q

Sw

Upd

ate

rsp

Ge

t In

fo r

eq

Ge

t In

fo r

sp

Pri

nt

req

Pri

nt

rsp

Rea

d C

ard

re

q

Rea

d C

ard

rsp

Result ▼ ▼ ▼ ▼ ▼ ▼ Print Receipt ● Internal Reference List ● Timestamp ● Merchant Information ● Maintenance Status ● ● ● Enable Dialog ● ● ● Card Insertion Timeout ● Echo Data ● ● ● ● ● ● ● ● ● ● ● ● Terminal Id ● Merchant Id ● Enable Ext. Networking ● ● Receipt Data ▼ Card Data Request ▼ Card Data ♦ Protocol Version ▼ ▼ ▼ ▼ ▼ ▼ Preferred Protocol Version ▼ ▼ ▼ ▼ ▼ ▼ Software Version ● Software Compatibility ● Target Software Version ● Target Software Compatibility ●




(49)



Version 2.2.0





9 Sample messages The following examples show the encoding of a complete message.

9.1 Sale request message In the following message, a sale transaction with base amount 15 and currency code 0752 (SEK) is requested:

Index Byte Description

0 0x02 Start of message token (See section 5.2.)

1-6 0x30 0x32 0x30 0x31 0x30 0x30 Protocol version (02 01 00) (See section 5.4.1.)

7-9 0x30 0x30 0x30 Target endpoint (terminal: 0) (See section 5.3.)

10-12

0x30 0x30 0x31 Sequence number (001) (See section 5.4.2.)

13 0x30 Type (message with data: 0) (See section 5.4.1.)

14-19

0x30 0x30 0x30 0x30 0x34 0x31 Content length (41) (See section 5.4.1.)

20-22

0x30 0x30 0x30 Type (sale request: 0) (See section 6.1.)

23 0x30 RFU

24-26

0x30 0x30 0x32 Number of data elements (2)

27-29 0x30 0x30 0x39 Currency code element type (9) (See section 7.11.)

30-35 0x30 0x30 0x30 0x30 0x30 0x34 Content length (4)

36-39 0x30 0x37 0x35 0x32 Currency code (“0752”)

40-42 0x30 0x31 0x31 Base amount element type (11) (See section 7.13.)


49-60 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x31 0x35 0x30 0x30

Base amount (15.00)

61-63 0x30 0x31 0x33 LRC (13) (See section 5.4.5.)

64 0x03 End of message token (See section 5.2.)

Table 10 - Sample message.

9.2 Sale response message The following message is a response for the request message above.




(49)



Version 2.2.0





Index Byte Description

0 0x02 Start of message token (See section 5.2.)

1-6 0x30 0x32 0x30 0x31 0x30 0x30 Protocol version (02 01 00) (See section 5.4.1.)

7-9 0x30 0x30 0x30 Target endpoint (terminal: 0) (See section 5.3.)

10-12

0x30 0x33 0x33 Sequence number (033) (See section 5.4.2.)

13 0x30 Type (message with data: 0) (See section 5.4.1.)

14-19

0x30 0x30 0x30 0x36 0x30 0x32 Content length (000602) (See section 5.4.1.)

20-22

0x30 0x30 0x31 Type (sale response: 001) (See section 6.1.)

23 0x30 RFU

24-26

0x30 0x32 0x39 Number of data elements (29)

27-29 0x30 0x30 0x30 Result element type (0) (See section 7.2.)


36-47 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30

Content (“0”)

48-50 0x30 0x30 0x31 Status element type (1) (See section 7.3.)


57-68 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x35 0x31 0x35

Content (“515”)

69-71 0x30 0x30 0x32 Transaction result element type (2) (See section 7.4.)


78-89 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30

Content (“0”)

90-92 0x30 0x30 0x34 Cardholder Language element type (4) (See section 7.6.)


99-100 0x73 0x76 Content (“sv”)

101-103 0x30 0x30 0x38 Transaction type element type (8) (See section 7.10.)


110-121 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x31

Content (“1”)




(49)



Version 2.2.0





122-124 0x30 0x30 0x39 Currency code element type (9) (See section 7.11.)


131-134 0x30 0x37 0x35 0x32 Content (“752”)

135-137 0x30 0x31 0x30 Currency symbol element type (10) (See section 7.12.)


144-146 0x53 0x45 0x4B Content (“SEK”)

147-149 0x30 0x31 0x31 Base amount element type (11) (See section 7.13.)


156-167 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x31 0x35 0x30 0x30

Content (“1500”)

168-170 0x30 0x31 0x36 Total amount element type (16) (See section 7.18.)


177-188 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x31 0x35 0x30 0x30

Content (“1500”)

189-191 0x30 0x31 0x37 Internal reference element type (17) (See section 7.19.)


198-203 0x30 0x30 0x30 0x30 0x35 0x33 Content (“53”)

204-206 0x30 0x32 0x31 Batch reference element type (21) (See section 7.23.)


213-215 0x30 0x30 0x33 Content (“3”)

216-218 0x30 0x32 0x32 Samport reference element type (22) (See section 7.24.)


225-236 0x33 0x30 0x30 0x30 0x30 0x30 0x33 0x30 0x31 0x38 0x33 0x33

Content (“300000301833”)

237-239 0x30 0x32 0x33 Retrieval reference element type (23) (See section 7.25.)


246-257 0x31 0x33 0x30 0x38 0x32 0x33 0x31 0x34 0x31 0x36 0x30 0x30

Content (“130823141600”)

258-260 0x30 0x32 0x37 Timestamp element type (27) (See section 7.29.)





(49)



Version 2.2.0





267-278 0x31 0x33 0x30 0x38 0x32 0x33 0x31 0x34 0x31 0x35 0x35 0x30

Content (“130823141550”)

279-281 0x30 0x32 0x38 Entry mode element type (28) (See section 7.30.)


288 0x43 Content (“C”)

289-291 0x30 0x32 0x39 Verification method element type (29) (See section 7.31.)


298 0x61 Content (“a”)

299-301 0x30 0x33 0x32 Authorization method element type (32) (See section 7.34.)


308 0x31 Content (“1”)

309-311 0x30 0x33 0x34 Authorization responder element type (34) (See section 7.36.)


318 0x33 Content (“3”)

319-321 0x30 0x33 0x36 Financial institution element type (36) (See section 7.38.)


328-330 0x53 0x57 0x45 Content (“SWE”)

331-333 0x30 0x33 0x37 SPDH response code element type (37) (See section 7.39.)


340-342 0x30 0x30 0x30 Content (“000”)

343-345 0x30 0x33 0x38 Approval code element type (38) (See section 7.40.)


352-357 0x37 0x31 0x35 0x35 0x39 0x32 Content (“715592”)

358-360 0x30 0x33 0x39 Masked PAN element type (39) (See section 7.41.)


367-382 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x2A 0x31 0x36 0x30 0x33

Content (“************1603”)

383-385 0x30 0x34 0x30 EMV data element type (40) (See section 7.42.)





(49)



Version 2.2.0





392-440 0x41 0x49 0x44 0x1F 0x41 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x34 0x33 0x30 0x36 0x30 0x1F 0x50 0x53 0x4E 0x1F 0x30 0x30 0x1F 0x54 0x53 0x49 0x1F 0x45 0x38 0x30 0x30 0x1F 0x54 0x56 0x52 0x1F 0x30 0x30 0x30 0x30 0x30 0x30 0x31 0x30 0x30 0x30

Content (“AID-A0000000043060PSN-00TSIE800TVR-0000001000”)

441-443 0x30 0x34 0x32 Merchant information element type (42) (See section 7.44.)


450-539 0x61 0x64 0x64 0x72 0x65 0x73 0x73 0x1F 0x4C 0x69 0x6E 0x6A 0x65 0x67 0x61 0x74 0x61 0x6E 0x20 0x35 0x1F 0x63 0x69 0x74 0x79 0x1F 0x33 0x30 0x32 0x35 0x34 0x20 0x48 0x61 0x6C 0x6D 0x73 0x74 0x61 0x64 0x1F 0x6E 0x61 0x6D 0x65 0x1F 0x53 0x61 0x6D 0x70 0x6F 0x72 0x74 0x1F 0x6F 0x72 0x67 0x6E 0x72 0x1F 0x30 0x30 0x31 0x32 0x33 0x34 0x2D 0x35 0x36 0x37 0x38 0x1F 0x70 0x68 0x6F 0x6E 0x65 0x6E 0x72 0x1F 0x30 0x33 0x35 0x32 0x34 0x31 0x30 0x38 0x34 0x30

Content (“address-Linjegatan 5city30254 HalmstadnameSamport-orgnr001234-5678-phonenr0352410840”)

540-542 0x30 0x35 0x39 Terminal id element type (59) (See section 7.55.)


549-563 0x31 0x32 0x32 0x34 0x33 0x43 0x54 0x37 0x31 0x37 0x34 0x36 0x33 0x34 0x34

Content (“12243CT71746344”)

564-566 0x30 0x36 0x30 Acquirer id element type (60) (See section 7.56.)


573-577 0x32 0x30 0x32 0x32 0x32 Content (“20222”)

578-580 0x30 0x36 0x31 Merchant id element type (61) (See section 7.57.)


587-594 0x36 0x30 0x30 0x30 0x30 0x30 0x32 0x34 Content (“60000024”)

595-597 0x30 0x36 0x34 Product name (64) (See section 7.60.)


604-610 0x4D 0x41 0x45 0x53 0x54 0x52 0x4F Content (“MAESTRO”)

611-613 0x30 0x36 0x36 ISO response code element type (66) (See section 7.62.)


620-621 0x30 0x30 Content (“00”)

622-624 0x30 0x39 0x33 LRC (93) (See section 5.4.5.)




(49)



Version 2.2.0





625 0x03 End of message token (See section 5.2.)

9.3 Application layer example cases The following examples show the message flow on the application level.

9.3.1 Sale

Host Terminal SALE request

SALE response

9.3.2 Sale with dialogs and external networking

Host Terminal SALE request

DIALOG request DIALOG response

DIALOG request DIALOG response (possibly additional DIALOG requests and responses)

CONNECT request CONNECT response

SEND request SEND response

RECEIVE request RECEIVE response

DISCONNECT request DISCONNECT response

DIALOG request DIALOG response (possibly additional DIALOG requests and responses)

SALE response

9.3.3 Cancelled sale

Host Terminal SALE request CANCEL

SALE response* *The result code of the response indicates if the transaction was actually cancelled.




(49)



Version 2.2.0





10 Link layer state machine This section contains a formalized model of the link layer using a state machine. While each implementation will differ in technologies used, the general flow control should comply with this specification. The diagram below illustrates the states and possible transitions, and the complete state machine is specified in the state table.

Figure 2 – Link layer state machine

10.1 Registers Register Default value Description

QIN empty Queued messages from host to terminal

QOUT empty Queued messages from terminal to host

QRES empty Queued send result of terminal to host message

CIN 999 Input sequence number counter for each endpoint

COUT 999 Output sequence number counter for each endpoint

CRET 0 Retry counter

BIN empty Serial input buffer

BOUT empty Serial output buffer

MIN empty Input message

MOUT empty Output message

TCHR 100 ms Character timeout (optional)

TMSG 1000 ms Message timeout

TACK 1000 ms Acknowledgement timeout

Table 11 – Link layer registers

10.2 Operations Operation Description

Reset Reset the register to its default value.

Increment Increment value by one. Sequence numbers are wrapped to 0 when reaching 999.

Put Put item/message into queue/buffer. Put(MOUT, COUT, BOUT) writes MOUT using endpoint sequence number COUT to BOUT.

Get Get item/character from queue/buffer. Cannot happen if the queue/buffer is empty. Get(BIN, MIN) = STX reads from non-empty BIN into MIN and checks if the character received was an STX.

Valid True if the complete message is valid (supported protocol version, LRC correct, etc.) or if the partial message is not invalid.

Type Type of message.

Seq Endpoint sequence number of message.

Timeout True if timer has expired.

Table 12 – Link layer operations

IDLE

IDLEREC

ACK

ACKREC




(49)



Version 2.2.0





10.3 State table State name in bold specifies the current state. Conditions are scanned top to bottom and if a condition is satisfied the corresponding action is executed and the next state is entered. If the next state is the same as the current state this is regarded as a reentry.

State Name Condition(s) Action(s)

IDLE Entry Reset(MIN)

Exit

IDLE Get(BIN, MIN) ≠ STX

IDLEREC Get(BIN, MIN) = STX Reset(TMSG)

ACK

New outgoing message queued from application layer. Send using current sequence number.

Get(QOUT, MOUT) Put(MOUT, COUT, BOUT) Reset(TACK) Reset(CRET)


IDLEREC Entry Reset(TCHR)

Exit

IDLEREC Get(BIN, MIN) = STX Reset(MIN)

Reset(TMSG)

IDLEREC Get(BIN, MIN) ≠ ETX

IDLE

Ping received. Send ACK, do not inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = PING Seq(MIN) ≠ CIN or Seq(MIN) = 999

Put(ACK, Seq(MIN), BOUT) CIN := Seq(MIN)

IDLE

New data message received. Send ACK and inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = DATA Seq(MIN) ≠ CIN or Seq(MIN) = 999

Put(ACK, Seq(MIN), BOUT) Put(MIN, QIN) CIN := Seq(MIN)

IDLE

Resent message received. Send ACK, do not inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = PING or DATA

Put(ACK, Seq(MIN), BOUT)

IDLE

Stray ACK or NAK received, ignore.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = ACK or NAK

IDLE Get(BIN, MIN) = ETX Put(NAK, Seq(MIN), BOUT)*

IDLE Timeout(TCHR) or Timeout(TMSG)

ACKREC

New outgoing message queued from application layer. Send using currenct sequence number.

Get(QOUT, MOUT) Put(MOUT, COUT, BOUT) Reset(TACK) Reset(CRET)


ACK Entry Reset(MIN)

Exit

ACK Get(BIN, MIN) ≠ STX

ACKREC Get(BIN, MIN) = STX Reset(TMSG)

ACK

No ACK received, retries not exceeded. Resend message.

Timeout(TACK) CRET < 5

Put(MOUT, COUT, BOUT) Reset(TACK) Increment(CRET)

IDLE No ACK received, retries exceeded. Inform application layer of failure.

Timeout(TACK) CRET ≥ 5

Put(NAK, QRES) Increment(COUT)


ACKREC Entry Reset(TCHR)

Exit

ACKREC Get(BIN, MIN) = STX Reset(MIN)

Reset(TMSG)

ACKREC Get(BIN, MIN) ≠ ETX




(49)



Version 2.2.0





ACK

Ping received. Send ACK, do not inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = PING Seq(MIN) ≠ CIN or Seq(MIN) = 999

Put(ACK, Seq(MIN), BOUT) CIN = Seq(MIN)

ACK

New data message received while waiting for ACK. Send ACK and inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = DATA Seq(MIN) ≠ CIN or Seq(MIN) = 999

Put(ACK, Seq(MIN), BOUT) Put(MIN, QIN) CIN := Seq(MIN)

ACK

Resent message received while waiting for ACK. Send ACK, do not inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = PING or DATA

Put(ACK, Seq(MIN), BOUT)

IDLE

ACK received for currenly sent message. Inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = ACK Seq(MIN) = COUT

Put(ACK, QRES) Increment(COUT)

ACK

NAK received for currently sent message, retries not exceeded. Resend message.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = NAK Seq(MIN) = COUT CRET < 5

Put(MOUT, COUT, BOUT) Reset(TACK) Increment(CRET)

IDLE

NAK received for currently sent message, retries exceeded. Inform application layer.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = NAK Seq(MIN) = COUT CRET ≥ 5


ACK

Stray ACK or NAK received, ignore. TACK will expire and initiate a resend if a new message is not received.

Get(BIN, MIN) = ETX Valid(MIN) Type(MIN) = ACK or NAK

ACK

Invalid or unknown message, send NAK. TACK will expire and initiate a resend if a new message is not received.

Get(BIN, MIN) = ETX Put(NAK, Seq(MIN), BOUT)* Increment(CRET)

ACK Timeout(TCHR) or Timeout(TMSG) CRET < 5

IDLE Timeout(TCHR) or Timeout(TMSG) CRET ≥ 5


Table 13 – Link layer state table

* Sending a NAK is optional, but may be used to actively refuse an incoming message.




(49)



Version 2.2.0





11 Receipt formatting As of specification 2.1.0 it is possible to supply extra receipt data to the terminal when performing a transaction. The terminal can also be used as a printer. This section details the format used to build receipts.

11.1 Syntax The receipt formatting syntax is based on Latin-1 encoded text with escape sequences to control alignment, style etc. An escape sequence consists of two bytes, 0x1B (ASCII escape) followed by the command, for example 0x52 (bold).

11.2 Command scope An issued command is valid until another command of the same group is issued. Thus if the text style is set to bold, all text will be bold even if alignment and condition commands are issued afterwards. For some groups it may be possible to combine several commands, for example approved cardholder.

11.3 Receipt sections A transaction receipt can be divided into the following sections (see Figure 3):

Header

Content (transaction information)

Footer The header and footer can be replaced by specifying the corresponding sections in the receipt data. The content cannot be replaced. It is also possible to insert text relative to the specified sections, for example between the header and content. Specifying the section has no effect if the receipt is not a transaction receipt.

11.4 Conditions In some cases it might not be necessary to add information to the transaction receipt. For example a declined transaction may not need additional information regarding a sale. In addition it may only be necessary to print the information for the cardholder receipt. The following conditionals can be used to decide what information to print:

All

Approved

Declined

Merchant

Cardholder It is possible to combine approved and cardholder to print text only on an approved cardholder receipt.




(49)



Version 2.2.0





Figure 3 – Receipt sections.

11.5 Alignment Alignment can be used to add columns to a receipt. The following alignments are available:

Left

Center

Right Each alignment should only be used once for each line of text. If an alignment is specified several times the results are undefined.

11.6 Style It is possible to add simple styling to the text:

Normal – resets styling

Italic

Bold

Double height Due to driver limitations it may not be possible to combine styles on all terminals.

Samport Example Linjegatan 5

30250 Halmstad ORG.NR 123456-7890

TERMINAL 12181WL60854149 MERCHANT 123456 60000029 DATE:2013-02-18 TIME:10:03

SALE APPROVED

AMOUNT SEK 5,00 TOTAL SEK 5,00 MasterCard PERSONAL CODE ************1234

SAMPORT Ca1 3 ABC 063 202995 RECEIPT:001244 REF:300000284727 AID:A0000000041010 TVR:80C0001000 TSI:6800 SAVE RECEIPT, CUSTOMER’S COPY

Header

Content

Footer




(49)



Version 2.2.0





11.7 List of commands The table below contains all supported commands.

Group Sequence Description

Sections 0x1B 0x20 Above header

0x1B 0x21 Header

0x1B 0x22 Below header (above content)

0x1B 0x23 Above footer (below content)

0x1B 0x24 Footer

0x1B 0x25 Below footer

Conditions 0x1B 0x30 All receipts (default)

0x1B 0x31 Approved receipts

0x1B 0x32 Declined receipts

0x1B 0x33 Merchant receipts

0x1B 0x34 Cardholder receipts

Alignment 0x1B 0x40 Left aligned (default)

0x1B 0x41 Center aligned

0x1B 0x42 Right aligned

Styling 0x1B 0x50 Normal text (default)

0x1B 0x51 Italic text

0x1B 0x52 Bold text

0x1B 0x53 Double height Table 14 – List of printer commands.

11.8 Examples

In the following examples ESCXX, for example ESC22, is short for binary 0x1B 0x22. LF is

short for 0x0A and causes a new line. See Figure 4 for the final receipts.

11.8.1 Shopping items

This receipt data will add a list of shopping items between the header and content, but only for approved cardholder receipts: ESC22 ESC31 ESC34 ESC40 Item ESC41 Qnty ESC42 Amnt LF ESC40 Apples

ESC41 2.0kg ESC42 6.50 LF ESC40 Blackberries ESC41 1.0kg ESC42 4.00

LF ESC40 ESC52 TOTAL ESC42 10.50

11.8.2 Replace header and footer

This receipt data will replace the header and footer text for all receipts: ESC21 My header ESC24 My footer LF consists of LF many LF lines




(49)



Version 2.2.0





Figure 4 – (left) shopping items (right) replaced header and footer

Samport Example Linjegatan 5

30250 Halmstad ORG.NR 123456-7890

Item Qnty Amnt Apples 2.0kg 6.50 Blackberries 1.0kg 4.00 TOTAL 10.50 TERMINAL 12181WL60854149 MERCHANT 123456 60000029 DATE:2013-02-18 TIME:10:03

SALE APPROVED


SAMPORT Ca1 3 ABC 063 202995 RECEIPT:001244 REF:300000284727 AID:A0000000041010 TVR:80C0001000 TSI:6800 SAVE RECEIPT, CUSTOMER’S COPY

My header TERMINAL 12181WL60854149 MERCHANT 123456 60000029 DATE:2013-02-18 TIME:10:03

SALE APPROVED


SAMPORT Ca1 3 ABC 063 202995 RECEIPT:001244 REF:300000284727 AID:A0000000041010 TVR:80C0001000 TSI:6800

My footer consists of

many lines

Samport Host2t 2.2.0

Documents

Transcript of Samport Host2t 2.2.0