PinPad Functions
PinPad presence test#
You can check the presence of the PinPad device and whether it is operational. To this end, logical opening and opening commands are sent closure of the communication channel.
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 sent fewer commands to the pinpad, and without the pinpad display 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
Set permanent message for the PinPad#
Allows you to define a permanent message to be displayed on the PinPad during the time it is not in use. The activation format routine is as follows:
int EscreveMensagemPermanentePinPad (Message)
ASCII Interface
EscreveMensagemPermanentePinPadA (Result, Message)
| 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 erase the message and leave the display blank, simply call this function passing the empty Message field.
The application, if desired, can include the character '|' (Vertical bar) to indicate a line change.
Reading track 3 of the card#
This function allows the app to capture a magnetic 3 track generic.
Note that the PinPad must support reading track 3.
It should not be used to process payment transactions but only for reading internal cards of the commercial establishment (e.g. supervisor card). The activation format is as follows:
int LeTrilha3 (Message)
| 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. |
Upon return, the routine returns the same values as the payment. The application obtains the tracks by calling the continuation of the iterative process.
IMPORTANT: This function NOT can be used during execution of the ContinuaFuncaoSiTefInterativo loop.
Card reading - secure capture routines#
The following routines have their operation conditioned by two prerequisites:
1) Configuration of the .cha key file on the SiTef server. If the configuration is not done, these functions return the error 12 (SAFE MODE NOT ACTIVE).
2) After installing the .cha key file on the server SiTef, Automation must, at least once, communicate with the SiTef server. This is necessary for the POS station to make the download of data that allows the execution of the Reading routines of the secure card). To do this, perform a Communication Test or a financial transaction.
int LeCartaoSeguro (Message)
ASCII Interface
LeCartaoSeguroA (Result, Message)
| 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. |
Upon return, the routine returns the same values as the payment routine. The application obtains the tracks by calling the continuation function of the iterative process.
The fields returned in the iterative process are those referring to the fields sensitive (2021 to 2046).
Observation:
These functions are not available for Mobile environments. Because difficulties in using function entrypoints, and aiming to facilitate its implementation, "Function" 430 was made available, which is an alternative to using the "LeCartaoSeguro" function.
This "Function" follows the flow of a "Managerial" transaction and is accessed through IniciaFuncaoSiTefInterativo (See item "5.2 - Start of Payment or Management transaction").
• To use "Function" 430, the "Message" parameter to be displayed on the pinpad display, Commercial Automation will be requested in the flow of transaction through command 29 (See item "5.3.1 - Table of transaction codes Command"). If not provided by Automation, the default message "SPIN THE CARD".
• To read the card using function 430, the parameter was included additional "SementeHash" (not used when the LeCartaoSeguro function is call directly) which is optional and will be requested in the call flow. transaction. If the "SementeHash" parameter is used, optionally can be provided through the "ParamAdic" parameter in the call function IniciaFuncaoSiTefInterativo, in this case, it will not be requested in the transaction flow.
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 Automation Commercial will be hash generated from the informed seed (Type field 203x. See "Fields that can be returned" table below).
Parameter format in "ParamAdic":
{SementeHash=XX...XX}
Where: XX...XX: Maximum 64 characters.
IMPORTANT: These functions cannot be used during execution of the ContinuaFuncaoSiTefInterativo loop. For this type of In this situation, there are versions that provide direct access to the reader card described below.
int LeCartaoDiretoSeguro (Message, TypeCampoTrilha1, Trail1, TypeCampoTrilha2, Trail2, Timeout, TestaCancellation)
ASCII Interface
LeCartaoDiretoSeguroA (Result, Message, TypeCampoTrilha1, Track1, TypeCampoTrilha2, Track2, Timeout)
| 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. |
| TypeFieldTrack1 | Output, by value | char * | Fixed 12 | Indicates the type of field that was returned in track 1, whether it is masked, encrypted or Hashed. |
| Track1 | Output, by value | char * | Max. 128 | The return contains, if any, 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. |
| Track2 | Output, by value | char * | Max. 80 | The return contains, if any, Track 2 read |
| Timeout | Input, 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 |
| TestaCancellation | 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 resulted in a card number that is not made up of just digits. |
| 8 | Invalid input data |
The fields TipoCampoTrilha1 and TipoCampoTrilha2 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 * |
Where x is represented by the table below:
| x | Field |
|---|---|
| 1 | Card PAN |
| 2 | Card expiration date (AAMM) |
| 3 | Name of customer/carrier |
| 4 | Track 1 |
| 5 | Track 2 |
| 6 | Track 3 |
* New implementations must use the 203x field, as the field 205x returns an encrypted hash using the encryption key inserted by the customer in the .cha file. This form of use (205x) exists just for compatibility, as the ideal is to use Hash with Salt (Seed - 203x) since the information used to generate the hash is hidden only within the applications that use it, making the process of reversing the hash until obtaining the original data practically impossible to execute by brute force.
IMPORTANT: These functions cannot be used during execution of the ContinuaFuncaoSiTefInterativo loop. For this type of In this situation, there are versions that provide direct access to the reader card described below.
int LeCartaoDiretoSeguroEx (Message, DataOut, TamDadosOut, Timeout, TestaCancellamento)
ASCII Interface
LeCartaoDiretoSeguroExA (Result, Message, DataOut, TamDadosOut, Timeout)
| 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. |
| Output Data | Output, by value | char * | Variable | Returns the same data from 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). |
| OutDataTam | Input, by value | char * | Fixed 6 | OutData buffer size. |
| Timeout | Input, 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 |
| TestaCancellation | 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 |
int LeTrilhaChipInterativo (Modality)
LeTrilhaChipInterativoEx (Modality, ParamAdic)
ASCII Interface
LeTrilhaChipInterativoA (Result, Modality)
| 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 | Input, by value | Int | Fixed | Selects the type of payment: |
| 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 "LeTrilhaChipInterativoA" are not exported to the Mobile environment. Due to difficulties in using function entrypoints, in this environment, and aiming to facilitate its implementation, the "Function" 431 for access to the "LeTrilhaChipInterativoEx" function. It is "Function" follows the flow of a "Managerial" transaction and is accessed through of IniciaFuncaoSiTefInterativo (See item "3.2 Start of transaction Payment or Management").
• To use "Function" 431, the "Modality" parameter (Type of payment) and "ParamAdic"(SementeHash), will be requested to Automation Commercial in the transaction flow through command 29 (See item 3.3.1 Command code table).
• If the "SementeHash" parameter is used, it can optionally be provided through the "ParamAdic" parameter in the function call IniciaFuncaoSiTefInterativo, in this case, you 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 empty field.
If this parameter is used, the data returned to Automation Commercial will be hash generated from the informed seed (Type field 203x. See "Fields that can be returned" table above).
Password reading#
This function allows the application to capture a password from a PinPad card customer of the commercial establishment itself (card owner). It must not, under any circumstances, be used to capture traditional card passwords. For more details, see the document "Access to Customer Password for Proprietary Card CliSiTef.doc".
int LeSenhaInterativo (SecurityKey)
ASCII Interface
LeSenhaInterativoA (Result, SecurityKey)
| 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 | Input, by value | char * | Fixed 64 | Data generated by a security library provided by Software Express to enable the capture of the customer's password. 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 by calling the continuation function of the iterative process.
IMPORTANT: These functions cannot be used during execution of the ContinuaFuncaoSiTefInterativo loop. For this type of In this situation, there are versions that provide direct access to the reader passwords described below.
int LeSenhaDireto (SecurityKey, CustomerPassword)
ASCII Interface
LeSenhaDiretoA (Result, SecurityKey, CustomerPassword)
| 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 | Input, by value | char * | Fixed 64 | Data generated by a security library provided by Software Express to enable the capture of the customer's password. 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 | Client password, in encrypted format, which must be passed to a custom routine per client for decryption |
Upon return, the routine returns the value 0 (zero) if it was executed correctly and a non-zero value in case of error or cancellation by the user.
Reading Confirmation by Customer on PinPad#
These functions allow the application to request confirmation on the PinPad. The activation format is as follows:
int LeSimNaoPinPad (Message)
ASCII Interface
LeSimNaoPinPadA (Result, Message)
| 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. |
Upon return, the routine returns 0 if the client pressed the key Cancellation, 1 if he pressed the Confirm key and another value in case of error when accessing the PinPad.
Note that this function is not iterative, i.e., execution control only returns to the application after pressing the key.
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)
| Parameter | Type | Default Interface | Description |
|---|---|---|---|
| Message | Input, 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 erase the message and leave the display blank, simply call this function passing the empty Message field.
The application, if desired, can include the character '\r' (carriage return) to indicate a newline.
Reading special PinPad keys#
This function is used to wait for a key to be pressed on the pinpad, returning its corresponding code. The activation format of the routine is:
int LeTeclaPinPad (void)
Upon return, the routine returns:
| Value | Key | Description |
|---|---|---|
| 0 | [OK] or [ENTER] | Press the OK or ENTER key |
| 4 | [F1] | Pressed the F1 key |
| 5 | [F2] | Pressed the F2 key |
| 6 | [F3] | Pressed the F3 key |
| 7 | [F4] | Pressed the F4 key |
| 8 | [CLEAR] | CLEAN key pressed |
| 13 | [CANCEL] | CANCEL key pressed |
| -43 | Any other key or an error occurred in the process. | Problem executing one of the routines on the pinpad. |
For security reasons, this command does not return numeric keys, and pressing these keys 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 pressing a key.
Note about using this function to obtain the F1, F2, F3 and F4: there are some pinpads on the market that do not have the F1, F2, F3 keys and F4. Therefore, when using this function, you must leave a plan B for these cases.