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:
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.
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:
ASCII interface#
| Parameter | Type | Standard interface | ASCII Interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call. |
| Message | Input,by value | char * | Variable | Message to be displayed on the PinPad display. It is recommended that it has a maximum of 32 characters in order to be compatible with the PinPads currently in the field. |
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:
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call. |
| Message | Entry, by value | char * | Variable | Message to be displayed on the PinPad display. |
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.
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call. |
| Message | Entry, by value | char * | Variable | Message to be displayed on the PinPad display. |
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.
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call. |
| Message | Input, by value | char * | Variable | Message to be displayed on the PinPad display. |
| FieldTypeTrack1 | Output, by value | char * | Fixed 12 | Indicates the type of field that was returned in track 1, whether it is masked, encrypted or hashed. |
| Trail1 | Output, by value | char * | Max 128 | The return contains, if it exists, Track 1 read |
| TypeFieldTrack2 | Output, by value | char * | Fixed 12 | Indicates the type of field that was returned in track 2, whether it is masked, encrypted or hashed. |
| Trail2 | Output, by value | char * | Max 80 | When returning, it contains, if any, Track 2 read |
| Timeout | Entry, by value | short | Fixed 6 | Defines the maximum waiting time for the card to be swiped in seconds. If zero, wait until the card is swiped |
| TestCancellation | Entry, by value | Routine | Not used | Automation application routine that returns 0 if it is to continue waiting for the card and 1 if it must interrupt the process of waiting for the card to be swiped |
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:
| Value | Description |
|---|---|
| 0 | No error occurred |
| 1 | Insufficient output field |
| 2 | BIN NOT ENABLED |
| 3 | Invalid CNPJ |
| 4 | Expired access key |
| 5 | Invalid version |
| 6 | Invalid encryption key |
| 7 | Unencrypted data with the key provided as a parameter: decryption decryption resulted in a card number that is not made up of just digits. |
| 8 | Invalid input data |
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:
| FieldType | Description |
|---|---|
| 202x | Open fields, masked. |
| 203x | Dynamic hash of fields |
| 204x | Encrypted fields |
| 205x | Fixed hash of fields * |
| x | Field |
|---|---|
| 1 | Card PAN |
| 2 | Card expiry (AAMM) |
| 3 | Customer/carrier name |
| 4 | Track 1 |
| 5 | Track 2 |
| 6 | Track 3 |
*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.
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call. |
| Message | Entry, by value | char * | Variable | Message to be displayed on the PinPad display. |
| DataOut | Output, by value | char * | Variable | Returns the same data as the LeCartaoDiretoSeguro routine, concatenated in TLV format, where T corresponds to the field type (size 5), L is the field size (size 3) and V is the field (field size) |
| TamDadosOut | Entry, by value | char * | Fixed 6 | DataOut buffer size. |
| Timeout | Entry, by value | short | Fixed 6 | Defines the maximum waiting time for the card to be swiped in seconds. If zero, wait until the card is swiped |
| TestCancellation | Entry, by value | Routine | Not used | Automation application routine that returns 0 if it is to continue waiting for the card and 1 if it must interrupt the process of waiting for the card to be swiped |
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call. |
| Modality | Entry, by value | Int | Fixed | Select the payment type: 2: Debit 3: Credit |
| ParamAdic | Input, by value | char * | Variable | Additional parameters, such as {SementeHash=XXX..}. It is optional and can be empty |
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”
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call |
| SecurityKey | Entry, by value | char * | Fixed 64 | Data generated by a security library provided by Software Express to enable customer password capture. In this case, CliSiTef may interact with SiTef to obtain or validate the security data necessary for the capture |
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
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call |
| SecurityKey | Entry, by value | char * | Fixed 64 | Data generated by a security library provided by Software Express to enable customer password capture. In this case, CliSiTef may interact with SiTef to obtain or validate the security data necessary for the capture |
| Password | Output, by value | char * | Fixed 20 | Customer password, in encrypted format, which must be passed to a custom routine per customer for decryption |
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:
ASCII interface#
| Parameter | Type | Standard interface | ASCII interface | Description |
|---|---|---|---|---|
| Result | Output, by value | Not used | Fixed 6 | Contains the result of the response to the routine call |
| Message | Entry, by value | char * | Variable | Message to be displayed on the PinPad display. |
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:
| Parameter | Type | Standard interface | Description |
|---|---|---|---|
| Message | Entry, by value | char * | Message to be displayed on the PinPad display. It is recommended that it has a maximum of 32 characters in order to be compatible with PinPads currently in the field. |
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:
Upon return, the routine returns:
| Value | Key | Description |
|---|---|---|
| 0 | [OK] or [ENTER] | Press the OK or ENTER key |
| 4 | [F1] | Press the F1 |
| 5 | [F2] | Press the F2 |
| 6 | [F3] | Press the F3 |
| 7 | [F4] | Press the F4 |
| 8 | [CLEAN] | Press the CLEAN |
| 13 | [CANCEL] | Press the CANCEL |
| -43 | Any other key or an error occurred in the process. | Problem executing any of the routines on the pinpad. |
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.