PinPad Functions

6.1 PinPad Presence Test

You can check the presence of the PinPad device and whether it is operational. To this end, logical commands to open and close the communication channel are sent.

There are two functions for this purpose.

The original function has the following format:

int VerificaPresencaPinPad (void)

Starting with version 4.0.114.4, a second function was created, where fewer commands are sent to the pinpad, and without the pinpad display turning on/off.

int KeepAlivePinPad (void)

Both routines have no input parameters, and can return the following values:

1 - There is an operational PinPad connected to the computer;

0 - There is no PinPad connected to the computer;

-1 - PinPad access library not found;

another number - errors detected internally by the routine or by the PinPad access library

6.2 Define permanent message for the PinPad

Allows you to define a permanent message to be displayed on the PinPad for as long as
it is not in use. The routine activation format is as follows:

int EscreveMensagemPermanentePinPad (Message)

ASCII interface

EscreveMensagemPermanentePinPad (Result, Message)

To delete the message and leave the display blank, simply call this function by passing the empty Message field.

The application, if desired, can include the character ‘|’ (vertical bar) to indicate a line change.

6.3 Reading card track 3

This function allows the application to capture a generic magnetic 3 track.

Note that the PinPad must support reading track 3.

It should not be used to process payment transactions but only to read the commercial establishment's internal cards (e.g. supervisor card). The activation format is as follows:

int LeTrilha3 (Message)

Upon return, the routine returns the same values ​​as the payment routine. The application obtains the tracks by calling the iterative process continuation function.

---

IMPORTANT: This function NOT can be used during loop execution
ContinueFuncaoSiTefInterativo.

---

6.4 Card reading - secure capture routines

The following routines are subject to two prerequisites:

1) Configuration of the .cha key file on the SiTef server. If the configuration is not done, these functions return error 12 (SAFE MODE NOT ACTIVE).

2) After installing the .cha key file on the SiTef server, Automation must, at least once, communicate with the SiTef server . This is necessary for the POS station to download the data that
allow the execution of secure card reading routines). To do this, run a Communication Test
or a financial transaction.

int LeCartaoSeguro (Message)

ASCII interface

LeCartaoSeguroA (Result, Message)

Upon return, the routine returns the same values ​​as the payment routine. The application obtains the tracks by calling the iterative process continuation function.

The fields returned in the iterative process are those referring to sensitive fields (*2021 to 2046).

Observation:

These functions are not available for Mobile environments. Due to difficulties in using function entrypoints, and aiming to facilitate their implementation, “Function” 430 was made available, which is an alternative to using the “LeCartaoSeguro” function.

This “Function” follows the flow of a “Management” transaction and is accessed through IniciaFuncaoSiTefInterativo (See item “5.2 - Start of the Payment or Management transaction”).

• To use “Function” 430, the “Message” parameter to be displayed on the pinpad display will be requested from Commercial Automation in the transaction flow through command 29 (See item “5.3.1 - Code table
  Command”). If it is not provided by Automation, the default message “PASS THE CARD” will be displayed.

• To read the card using function 430, the additional parameter “SementeHash” was included (not
  used when the LeCartaoSeguro function is called directly) which is optional and will be requested in the flow of
  transaction. If the “SementeHash” parameter is used, it can optionally be provided through the parameter
  “ParamAdic” in the IniciaFuncaoSiTefInterativo function call, in this case, will not be requested in the flow of
  transaction.

If requested in the transaction flow through command 29 and the parameter is not used, return the field
empty.

If this parameter is used, the data returned to Commercial Automation will be a hash generated from the informed seed (Field type 203x. See table “Fields that can be returned” below).

Parameter format in “ParamAdic”:

{SementeHash=XX...XX}

Where: XX...XX: Maximum 64 characters.

---

IMPORTANT: These functions cannot be used during loop execution
ContinueSiTefInteractive Function. For this type of situation, there are versions that provide direct access to the reader.
cards described below.

---

int LeCartaoDiretoSeguro (Message, TypeCampoTrilha1, Trail1, TypeCampoTrilha2, Trail2, Timeout, TestaCancellation)

ASCII interface

LeCartaoDiretoSeguroA (Result, Message, TypeCampoTrilha1, Track1, TypeCampoTrilha2, Track2, Timeout)

Upon return, the routine returns the value 0 (zero) if it was executed correctly and a non-zero value in case of error or interruption.

For this specific routine, the error codes returned are:

The TypeFieldTrack1 and TypeFieldTrack2 fields indicate the type of field returned, respecting the value established for sensitive fields, with 202x for masked open fields, 203x for the Hash of the fields, 204x for encrypted fields and 205x. Fields that can be returned:

*New implementations must use the 203x field, as the 205x field returns an encrypted hash
using the encryption key entered by the customer in the .cha file. This form of use (205x) exists only because
compatibility, as the ideal is to use the Hash with Salt (Seed - 203x) since the information used to
generating the hash is hidden only within the applications that use it, making the process of reversing the hash
until obtaining the original data that is practically impossible to execute by brute force

---

IMPORTANT: These functions cannot be used during loop execution
ContinueSiTefInteractive Function. For this type of situation, there are versions that provide direct access to the reader.
cards described below.

---

int LeCartaoDiretoSeguroEx (Message, DataOut, TamDadosOut, Timeout, TestaCancellation)

ASCII interface

LeCartaoDiretoSeguroExA (Result, Message, DataOut, TamDadosOut, Timeout)

int LeTrilhaChipInterativo (Modality) LeTrilhaChipInterativoEx (Modality, ParamAdic)

ASCII interface

LeTrilhaChipInterativoA (Result, Modality)

These functions work in the same way as LeCartaoSeguro/LeCartaoSeguroA, with the difference that they accept chip cards.

Observation:

These functions, “LeTrilhaChipInterativo”, “LeTrilhaChipInterativoEx” and “LeTrilhaChipInt erativoA” are not
exported to the Mobile environment. Due to difficulties in using function entrypoints in this environment,
and aiming to facilitate its implementation, “Function” 431 was made available to access the function
“LeTrilhaChipInterativoEx”. This “Function” follows the flow of a “Managerial” transaction and is accessed through
IniciaFuncaoSiTefInterativo (See item “3.2 Start of Payment or Management transaction”).

• To use “Function” 431, the “Modality” parameter (Type of payment) and
  “ParamAdic”(SementeHash), Commercial Automation will be requested in the transaction flow through the command
  29 (See item 3.3.1 Command code table).
• If the “SementeHash” parameter is used, it can optionally be provided through the parameter
  “ParamAdic” when calling the IniciaFuncaoSiTefInterativo function, in this case, it will not be requested in the flow of
  transaction. If requested in the transaction flow through command 29 and the parameter is not used, return the
  empty field.

If this parameter is used, the data returned to Commercial Automation will be hash generated
from the informed seed (Field type 203x. See “Fields that can be returned” table above).

6.5 Password reading

This function allows the application to capture a password from one of its own card customers on the PinPad.
commercial establishment (proprietary card). It should not, under any circumstances, be used to capture
traditional card passwords. For more details, see the document “Accessing the Customer Password for
CliSiTef.doc Owner Card”

int LeSenhaInterativo (SecurityKey)

ASCII interface

LeSenhaInterativoA (Result, SecurityKey)

Upon return, the routine returns the same values ​​as the payment routine. The application obtains the password through
call the continuation function of the iterative process.

---

IMPORTANT: These functions cannot be used during loop execution
ContinueSiTefInteractive Function. For this type of situation, there are versions that provide direct access to the reader.
of passwords described below

---

int LeSenhaDireto (SecurityKey, ClientPassword)

ASCII interface

LeSenhaDiretoA (Result, SecurityKey, CustomerPassword)

Upon return, the routine returns the value 0 (zero) if it was executed correctly and a value other than
zero in case of error or cancellation by the user.

6.6 Reading Confirmation by the Customer on PinPad

These functions allow the application to request confirmation on the PinPad. The activation format is
Following:

int LeSimNaoPinPad (Message)

ASCII interface

LeSimNaoPinPadA (Result, Message)

Upon return, the routine returns 0 if the customer pressed the Cancel key, 1 if he pressed the Confirmation key and another value in case of an error accessing the PinPad.

Note that this function is not iterative, that is, execution control only returns to the application after pressing the key.

6.7 Sets a momentary message for the PinPad

Allows you to define a momentary message to be displayed on the PinPad display. The routine activation format is:

int EscreveMensagemPinPad (Message)

To delete the message and leave the display blank, simply call this function by passing the empty Message field.

The application, if desired, can include the character ‘\r’ (carriage return) to indicate a line change.

6.8 Reading PinPad special keys

This function is used to wait for a key to be pressed on the pinpad, returning its code
corresponding. The routine activation format is:

int LeTeclaPinPad (void)

Upon return, the routine returns:

For security reasons, this command does not return numeric keys, and pressing these
keystrokes is simply ignored by the pinpad during command execution.
Note that this function is not iterative, i.e., execution control only returns to the application after the
pressing a key.
Note about using this function to get the F1, F2, F3, and F4 keys: There are some pinpads on the market that do not have the F1, F2, F3, and F4 keys. Therefore, when using this function, you must leave a plan B for these cases.