Integration Guide
Sumary#
New TLS Software Express (TLSGWP)
Starting M-Sitef by another app
Request example of m-SiTef by another app
Example of handling m-SiTef return
Example of integration using Androidx
Introduction#
M-Sitef is an application developed by Software Express for the Android platform, both in mobile or tablet and in POS, which performs Transactions (TEF) through the Sitef server.
This application contains the Clisitef library and enables the integrator to interact easily with Clisitef's features, without the necessity to control the flow of transactions.
Objetive#
Be a reference guide on how to make the integration with m-Sitef.
Target Audience#
Partners who want to integrate with M-Sitef.
Minimum requirements#
M-Sitef is compatible with Android version 4.4 or higher.
M-Sitef#
Before presenting the forms of integration, we will describe in this Chapter The General Characteristics of M-Sitef.
It makes available to the integrator the same features as Clisitef that are described in the document "Sitef - Simplified integration with the application" in the Function Codes Table.
To perform these functions, it is mandatory to send 4 parameters to M-Sitef: CompanySitef, AddressSitef, Modality and CNPJ_CPF. For modality 0, is also required the parameter value.
IMPORTANT: All these parameters presented in this document in code parts are only illustrative and must be replaced by valid values.
The following are all parameters accepted in the application.
Table 1 - input parameters of m-SiTef#
| Parameter | Type | Description |
|---|---|---|
| empresaSitef | Mandatory | SiTef company. The size is 8 alphanumeric digits. |
| enderecoSitef | Mandatory | Address of SiTef servers. The field can be composed of 1 to 3 addresses separated by ‘;’. The address format can be: 1. IP, IP:PORT; 2. Server name, NAME:PORT. When the port is not specified, the default port (4096) is assumed. Do not enter URL in this field. |
| terminalSitef | Optional | SiTef terminal number. If not entered, m-SiTef will use the APOS serial number or the UUID of the Android device |
| modalidade | Required | CliSiTef functionality you want to execute. For example: 0 – Payment 200 – Cancellation 114 – Reprint The complete list can be found in the document “SiTef - Simplified Interface with the application” in the Code Table functions. |
| CNPJ_CPF | Required | CNPJ or CPF of the establishment. This field must not contain special characters and can be used in subacquiring data and in ParmsClient. |
| Valor | Mandatory for payment | Sales value. The field is numeric with a length of up to 12 digits, where the last two digits are decimals. |
| restricoes | Optional | Payment options that will not appear in the collection flow. The field must have the following format:<Option>;<Option>; ....The option values are in the document “SiTef - Simplified Interface with the application”, in the Function Code Table. Note: the option TransacoesHabilitadas=T1,T2 can also be passed in this parameter and will have preference over the TransacoesHabilitadas parameter |
| operador | Optional | Operator code. The field is alphanumeric with a length of up to 20 characters. |
| Data | Optional | Tax date in YYYYMMDD format. |
| Hora | Optional | Fiscal time in HHMMSS format. |
| numeroCupom | Optional | Tax coupon number corresponding to the sale. The field is alphanumeric with a length of up to 20 characters. |
| numParcelas | Optional | Number of installments, in case of purchase in installments. The field is numeric and varies depending on the card used. |
| Otp | Optional | Mandatory code when communication with TLS GSurf is used. |
| transacoesHabilitadas | Optional | Payment options that will be enabled. The field must have the following format { <Functionality1>;<Functionality2>;...}. The option values are in the document “SiTef - Simplified Interface with the application”, in the Function Code Table. |
| pinpadMac | Optional | MAC Address Bluetooth address of the Pinpad for the m-SiTef to connect directly with the pinpad. If this parameter is not passed, m-SiTef presents a list of Bluetooth devices paired with the device for the user to select which one to use. Format: 00:00:00:00:00:00 |
| comExterna | Required | Field to define which TLS service will be used: 0 – Without (only for dedicated SiTef) 1 – TLS Software Express 2 – TLS WNB Comnect 3 – TLS Gsurf |
| isDoubleValidation | Mandatory for TLS Software Express | Field to define which type of validation will be used: 0 – For single validation 1 – For double validation |
| cnpj_automacao | Optional | CNPJ of the company that developed the commercial automation. Data used in ParmsClient. |
| cnpj_facilitador | Optional | CNPJ of the Facilitator (Van). Data used in ParmsClient. |
| timeoutColeta | Optional | Defines the timeout time for transaction flow collections and interactions. The value must be filled in “seconds” and if it is not filled in, the default value is 60 seconds. If set to 0 or negative numbers, the collection timeout will be disabled. The timeout is applied if the user does not interact with the collection for the specified number of seconds. In this case, the transaction is automatically canceled and the application receives the value RESULT_CANCELED in the resultCode parameter. This timeout does not apply to QRCode reading, PIN collection and card removal from the reader. |
| acessibilidadeVisual | Optional | Field to define whether visual accessibility should be enabled: 0 – To disable (default value) 1 – To enable Enabling visual accessibility consists of some visual and sound. If this field is enabled, m-SiTef will have the following changes: · Larger fonts for better visualization · High contrast in colors for better visualization in case of color blindness · Activation of text- to-speech (screen reading) throughout the flow · If applicable, activates screen adaptation for compatibility with the accessibility layer when entering a password or pin (applicable on pre-defined models).< br/> Note: for screen reading to be performed by the text-to-speech module, the operating system must have previously installed the corresponding language package. In the case of GPOS700, the package PT-BR language will be made available by Gertec. |
| tipoPinpad | Mandatory for USB devices. | ANDROID_USB – Try to connect only with USB pinpads. ANDROID_BT – Try to connect only with Bluetooth pinpads. |
| dadosSubAdqui | Optional | Set of complementary information that allows the retailer to customize what will be printed on the buyer's invoice. Format: <id1><tam1><val1><id2><tam2></tam2 ><val2>...<idn><tamn></tamn><valn>Where: Id - 2-byte field identifier, according to values defined in the specification table” Sub-acquiring Information (Soft Descriptor) CliSiTefI and CliSiTef Libraries” size - field size with 2 bytes. Val – field value. Sending example:< br/>i.putExtra("dadosSubAdqui", "0022STL*SOFTWARE EXPRESS"); For more information regarding the data, consult the specification: “Sub-acquiring Information (Soft Descriptor) CliSiTefI and CliSiTef Libraries ” |
| tipoCampos | Optional | Allows you to enter pre-determined values for the fields that CliSiTef requests for the application during the transaction flow. The fields and their respective values must be entered in the JSON format below. Values must always be entered as a String value. And it is important to note that in this format, it is possible to define only one value per field type. JSON format: {"campo1":"val1", "campo2":"val2"..."campon":"valn"}Send examples: i.putExtra("tipoCampos","{\"147\":\"8000\", \"516\":\ "99900021\"}"); i.putExtra("tipoCampos","{\"1025":\"Product Description\"}"); |
| habilitaColetaTaxaEmbarqueIATA | Optional | When enabled, it indicates that it is an IATA credit sale transaction and a field will be available for collecting the boarding tax amount. 0 – To disable (default value) |
| habilitaColetaValorEntradaIATA | Optional | When enabled, it indicates the collection of the down payment in case of installments of the sale on IATA credit. This collection will only be allowed for IATA sales, that is, enabling this item will only take effect if you enableIATAEmbarkationCollection=1. |
| clsit | Optional | To be able to add, update and remove fields from the package's CLSIT configuration file. See section Changing the CLSIT. |
Integration using TLS#
M-Sitef is compatible with 4 TLS Providers: Express Software, Gsurf, Wnb Comnect and TLSGWP. Below will be explained how to use each of them.
TLS Software Express#
TLS WNB Comnect Integration#
TLS Gsurf Integration#
New TLS Software Express (TLSGWP)#
Alternatively, the terminal record to use the new TLSGWP can be performed through modalities 699 (terminal registration) or 110 (Administrative Menu).In this case, Clisitef will open a collection for the token to be informed and from that moment the terminal will be registered and should inform in the next transactions that the type of connection will be TLSGWP informing the parameter comExterna = 4 as the follow example.
Manual Register (TLSGWP)#
Integration with another app#
Starting M-Sitef by another app#
The first step is to instantiate an Intent object passing the name of the application as an argument – in this case, the name is br.com.softwareexpress.sitef.msitef.ACTIVITY_CLISITEF. Using this information, Android will automatically search for m-SiTef among the applications installed on the mobile device. Next, four mandatory parameters must be configured using the putExtra(String, String) function: empresaSitef, enderecoSitef, CNPJ_CPF and modalidade. These and other parameters will be detailed in item 5. Finally, the native Android function startActivityForResult(Intent, int) is executed, passing the Intent object and an arbitrary integer as parameters. This number will be used as an ID to retrieve information that m-SiTef will send, after finishing its processing, to the application that triggered it. In this document, we will use ID = 1234.
Request example of m-SiTef by another app#
a) Payment
Upon being triggered, the M-Sitef may present the following screens:
b) Debit
c) Cash credit
d) Credit installment
e) Cancellation
f) Reprint
ATTENTION: Coupon printing is not performed by M-Sitef. The reprint service conducts a consultation to coupons previously saved on the sitef.The information collected in this consultation is passed on the return of INTENT. The impression of the coupons returned by Intent is under application responsibility which made the call to M-Sitef.
g) Administrative menu
Pix request example#
To perform Pix the automation must follow the example below, choosing the digital wallet menu.Important: The “cnpj_automacao” field is extremely important that it is sent, because it is through it that Express software will be able to recognize the settelment and thus make the financial transfer.
If desired, automation can call pix directly restricting digital wallet options and passing the type 122 (digital wallets), as shown below.
M-Sitef Response to Another App#
M-Sitef Response to Another App#
After executing m-SiTef, the flow is returned to the application that triggered it and some parameters are returned. Through them, the application will be able to know whether the transaction processing was successful and also obtain other information. To receive this data, the application must implement the protected void onActivityResult(int requestCode, int resultCode, Intent data) function, which is executed because the startActivityForResult(Intent i, int requestCode) method was called to start m-SiTef. The requestCode argument is used to check the correspondence of the call to m-SiTef with its return. The resultCode shows the execution status of the m-SiTef flow (values belong to Android RESULT_OK (-1) RESULT_CANCELED (0)). The data argument is used to retrieve the data sent by m-SiTef. The onActivityResult implementation must contain a condition comparing whether the requestCode is equal to the number passed in startActivityForResult and, within this condition, it is checked whether m-SiTef was executed successfully and the parameters sent by it are retrieved through the data.getExtras().getString() function.
The application integrated with m-SiTef can only handle the parameters it needs.
Table 2 - output parameters of m-SiTef#
| Parameter | Description |
|---|---|
| CODRESP | Response code for the transaction carried out with SiTef. See the following table for more details |
| COMP_DADOS_CONF | Data that must be passed to CliSiTef, in order to confirm the transaction carried out. |
| CODTRANS | Indicates code of the transaction carried out. Possible values: · ‘00’: Check Inquiry · ‘01’: Debit Card · ‘02’: Credit Card |
| TIPO_PARC | Possible values: · “00”: Cash · “01”: Pre-Dated · “02”: Establishment Installments · “03”: Administrator Installments |
| VLTROCO | Contains the approved amount for cash change. (Used when purchasing with Withdrawal available for some Networks). |
| REDE_AUT | Field containing the network authorizing the TEF transaction carried out. The codes are in the document "Especificação Técnica – Interface com os meios de pagamento do SiTef"", in the Authorizing Networks Code Table. |
| BANDEIRA | Field containing the flag of the TEF transaction carried out. The codes are in the document "Especificação Técnica – Interface com os meios de pagamento do SiTef"", in the Flag Code Table. |
| NSU_SITEF | SiTef server NSU. |
| NSU_HOST | Authorizing Host NSU. |
| COD_AUTORIZACAO | Credit transaction authorization code. (Only present in credit card transactions). |
| NUM_PARC | Field containing the number of installments of the transaction. If it is absent, or has a value of “0” or “1”, consider selling it in cash. |
| VIA_ESTABELECIMENTO | Coupon referring to the establishment’s route. |
| VIA_CLIENTE | Coupon referring to the customer's copy. |
| TIPO_CAMPOS | JsonObject containing all the fields of the transaction with CliSiTef, including the other fields in this table. Format:{"Id TipoCampo N" : [ "value 1", ....]}The values are always passed in JsonArray, even if there is only one occurrence of the field by CliSiTef. To discover the meaning of each field contained in this list, please look at the table “Table of values for TipoCampo” in the SiTef document - Simplified Interface with the application section 5.3.2. Not all parameters from table 5.3.2 may be present in all transactions, some parameters may not be sent depending on the payment method or if the transaction is not completed. |
Tabela 3 - Valores do CODRESP#
| CODRESP | Descrição |
|---|---|
| 0 | Success in the execution of the function. |
| 1 | IP address invalid or unresolved |
| 2 | Invalid Store Code |
| 3 | Invalid Terminal Code |
| 6 | TCP/IP startup error |
| 7 | Lack of memory |
| 8 | Clisitef not found |
| 9 | Sitef server configuration has been exceeded. |
| 10 | Access error in the Clisitef folder (possible lack of writing permission) |
| 11 | Invalid data passed by automation. |
| 12 | secure mode inactive |
| 13 | Invalid Way (the full library path is very large). |
| Another positive value | denied by the authorizer. |
| -1 | Non -initial module.The POS tried to call some routine without first performing the function configures. |
| -2 | Operation canceled by operator. |
| -3 | The function / modality parameter is nonexistent / invalid. |
| -4 | Lack of memory in the POS. |
| -5 | Communication with the sitef interrupted. |
| -6 | User canceled operation (in Pinpad). |
| -9 | Automation request the routine ContinuaFuncaoSitefInterativo without starting first an iterative function. |
| -10 | Some Required parameter was not passed on by commercial automation. |
| -12 | Error in the execution of the iterative routine. Probably the previous iterative process was not executed until the end (while the return is 10000). |
| -13 | Tax document not found in CliSiTef records. Returned in query functions such as ObtemQuantidadeTransaçõesPendentes. |
| -15 | Operation canceled by commercial automation. |
| -20 | Invalid parameter passed to the function. |
| -25 | Bank correspondent error: Must perform bleeding. |
| -30 | Error of access to the file.Make sure the user who runs the application has reading/writing rights. |
| -40 | Transaction denied by the sitef server. |
| -41 | Invalid data. |
| -43 | Problem in performing any of the routines in the pinpad. |
| -50 | Non-secure transaction. |
| -100 | Internal module error. |
| Another negative value | Errors detected internally by routine. |
Example of handling m-SiTef return#
Changing CLSIT#
From version 3.167 you can change the CLSIT file. The change can only be made once, after that it will only be possible to change the CLSIT by changing the company or forcing the application stop in the Android configuration menu. The CLSIT file has the following format:
Here are examples of how to use this functionality and a CLSIT model that will be used as example.
Changing fields#
Notice on CLSIT below that the keys DiretoryTrace and EnableTransactions they were updated with the values sent by the example above, it is important to note that if the key does not exist it will be added in the section sent and if its value already exists the new values will be added.
Adding fields#
Notice that the keys EnablePickupOnboardingTax and PickupEntryValueIATA were added to general section and the Newsection was created, as it did not exist yet.
Removing fields#
You can notice that SizeTraceRotative was removed from CLSIT. If a section no longer contains keys it will be excluded as well.
Important: To know exactly which sections, keys and values must be passed to assemble your CLSIT file, please confirm with our support. M-Sitef has a default CLSIT that will be applyed if no change specified in this chapter is made. Here is the image:
Example of integration using Androidx#
If you are integrating M-Sitef using Androidx libraries, the startActivityForResult e onActivityResult methods are depreciated. There is an example below of M-Sitef request using Androidx
ActivityResultLauncher definition to perform the return of the m-SiTef
Change History#
| Date | Doc | APP | Description |
|---|---|---|---|
| 08/05/2019 | 1.00 | Initial release. | |
| 08/06/2019 | 1.01 | Inclusion of integration via URL. | |
| 08/09/2019 | 1.02 | Inclusion of TLS Protocol activation parameters. | |
| 08/22/2019 | 1.03 | Inclusion of the parameters “isDoubleValidation” and “caminhoCertificadoCliente”. | |
| 03/09/2019 | 1.04 | Inclusion of input parameters “cnpj_automacao” and “cnpj_facilitador”. | |
| 16/04/2020 | 1.05 | Field Modality change from 9 to 0. Option Display Receipt removed Standard Certificate, path option removed. | |
| 07/21/2020 | 1.06 | Inclusion of the cancellation modality. | |
| 08/20/2020 | 1.07 | Inclusion of the terminal field. | |
| 08/25/2020 | 1.08 | Removal of TLS mode with double validation. Remove of Input mode by URL. Change references “m-sitef client” to “m-sitef” Mentions about “m-Sitef Standalone” removal Table Formatting Codresp Value Table addition Change of File Name | |
| 10/19/2020 | 1.09 | Inclusion of the topic Pix. | |
| 11/20/2020 | 1.10 | Inclusion of the return field “TIPO_CAMPOS” | |
| 01/12/2020 | 1.11 | 3.98 | Inclusion of the “TimeoutColeta” field. |
| 03/05/2021 | 1.12 | 3.104 | Inclusion of the “Visual Accessibility” field and behavior description when visual accessibility is enabled. Inclusion of Gertec Accessibility Language Package as required to observation inclusion. |
| 03/08/2021 | 1.13 | Comment added to the sitef address as suggestion of TRAC #53436 Removal of repply by URL | |
| 05/19/2021 | 1.14 | 3.114 | Typepinpad field addition. |
| 05/20/2021 | 1.15 | Removal of the value ANDROID\ _Auto of the field type, as it does not apply to M-Sitef. | |
| 07/15/2021 | 1.16 | Inclusion of Administrative Menu Request and Example Parameters | |
| 01/10/2021 | 1.17 | Document change to the FISERV standard. Inclusion of new M-Sitef design. | |
| 02/09/2022 | 1.18 | Inclusion of the field dadosSubAdqui | |
| 21/02/2022 | 1.19 | Inclusion of the field tipocampos | |
| 08/29/2022 | 1.20 | 3,151 | Inclusion of Parameters habilitaColetaTaxaEmbarqueIATA and habilitaColetaValorEntradaIATA |
| 09/15/2022 | 1.21 | 3,167 | Chapter "Changing the CLSIT" |
| 01/04/2023 | 1.22 | Inclusion of the topic about integration using Androidx. |