VTOL EMVKIT CL 1.2.X (English version)
1. Introduction
1.1 About this document
This document explains how to integrate into the VTOL EMV Kit Library and, thus, be able to make payment authorizations with Credit/Debit cards to Transbank.
References:
- "Manual de comandos pinpad Host to Host TRANSBANK - Comercio bajo protocolo SPDH 4.0 v2.9.pdf"
- "Manual de Especificaciones Técnicas Conexión H2H TRANSBANK - SPDH 4.0 v1.4.pdf"
1.2 What is the EMV Kit Library?
VTOL has a EMV Kit library developed in Java, which provides the necessary functions to perform authorizations of various types of transactions, in addition to the control transactions which are common to any VTOL Server implementation.
To facilitate integration with the POS application, the library allows you to set devices to obtain the data needed to generate messages to VTOL.
The EMV Kit library is a piece of software that can be initiated as a service at the point of sale. It is responsible for processing credit/debit card payment transactions, capturing the card data and sending the authorization to the VTOL Server. Communication with the latter is done by means of a proprietary protocol, called the VTOL protocol, implemented on TCP/IP.
In addition, it addresses the interaction with the pinpad device provided by Transbank, freeing the point-of-sale application from this task.
In turn, the library is set centrally via the VTOL Server, which concentrates the complete configuration. Refer to the VTOL Server user manual for more information.
1.3 Library Architecture
General Architecture of the EMV Kit Library
As shown in the image, the Emv Kit library is responsible for communicating with the PINPAD, freeing the point-of-sale application from that responsibility, to simplify integration.
This library will run in a stand-alone –autonomous– way at the point of sale, and will be able be initiated as a service, transmitting a TCP/IP server communication capable of interpreting the VTOL protocol. The same protocol is used to communicate with the VTOL Server.
Integration between the point-of-sale application (POS) and the Emv Kit library will be done by means of the VTOL client library, which we will call client library or thin library.
The point-of-sale application should only incorporate this thin library that will allow you, by means of JAVA calls, to build messages to communicate with the Emv Kit library.
Architecture and Communication of the Emv Kit Library
The image shows examples of requirement and response frames transmitted by TCP IP between the thin library and the Emv Kit library. The types of operations are as follows and are set out in section 5.2 Types of Operation:
- Session Creation
- Card Data Reading
- Sending an Authorization
- OnUs Operations
- View Sales Transactions
- Getting POS Configuration
- Batch Closure
- Close Session
1.4 Scope
The Emv Kit library has the following scope:
1- Capture card information via PINPAD 2- PINPAD Vx805
2- VISA/POSNET support via RS232 or USB
3- Provide encrypted card data, which can only be decrypted by the authorizing HOST, as appropriate
4- Facilitate the masked PAN (only the last 4 digits are visible)
5- Capture the CVC using the PINPAD
6- Capture the expiration date by means of PINPAD, in case the input is manual
7- Capture the PIN by means of PINPAD
8- Support CHIP, BAND and MANUAL input mode
9- Provide VTOL Server configuration to point-of-sale application
10- Manage contingency between PINPAD, Box, and VTOL
11- Communication between point-of-sale application and VTOL Server
12- Solve PINPAD’s own business rules
13- Support operations such as sales and void sales
14- Manage messaging with the VTOL Server
It is the responsibility of the point-of-sale application:
1- Carrying out the necessary operation
2- Confirming the last 4 digits of the card
3- Performing the calculation of promotions
4- Confirming the amount
5- Printing vouchers and duplicates
1.5 Requirements
The minimum requirements required by the Emv Kit library for its proper operation are listed below:
1.5.1 Supported Platforms
- Windows 32/64 bits
- Linux 32/64 bits
1.5.2 Hardware Requirements
- RAM Memory: 64MB available
- Processor: 2 cores of 1.6GHZ or higher (subject to tests, as there are hardware architectures dependencies, for example, it could work with 1 core but more powerful)
- Hard Drive Storage Capacity: At least 150MB
1.5.3 Software Requirements
- Official Java Virtual Machine (JDK) Oracle 1.8.x or higher (32/64-bit according to OS)
- Connection to VTOL Server via TCP/IP network
2. Functional
2.1 General Explanation
The Emv Kit library is responsible for abstracting the point-of-sale application from operations such as PINPAD, communication and transaction processing with the VTOL Server, transactions information storage, maintaining PCI security, resolving contingencies, etc.
To do this, the library provides a series of actions that allow it to operate, namely:
- Start Session
- Sending authorization or authorizations
- Close Session
Generally speaking, the order of execution of each call is similar to the one mentioned above. First you start the session, where the Emv Kit library loads the configuration from VTOL, synchronizes the transactions’ status, verifies the operation of the PINPAD, etc. Afterwards, a call cycle is entered to perform the required transactions. What is done as many times as cards are used to pay for the transaction. Finally, closing the session occurs, where the Emv Kit library confirms the transactions against the VTOL server.
Supported transaction types are:
- Sales transaction with no interest credit card (NInstallments- 3CSI, 2CSI)
- Sales transaction with interest (applicable to CIC, CICR, Normal Sale)
- Installment value query
- Void transactions
- Debit transaction
- Closures
For more information on transactions refer to the document:
"“Manual de comandos pinpad Host to Host TRANSBANK - Comercio bajo protocolo SPDH 4.0 v2.9.pdf”"
Each operation is explained in more detail in the following sections.
2.1.1 Transaction Processing
The generic interaction mode of the sale application with the Emv Kit library can be seen below:
1- Start session with the Emv Kit library.
2- The point-of-sale application sends the transaction to the library for authorization.
3- Once these calculations have been completed, the point-of-sale application requests the transaction processing. At this point, the Emv Kit library validates and requests the SPDH frame via PINPAD. If everything goes well, it proceeds to the authorization with the VTOL Server and, in turn, against the Transbank authorizer.
4- When the answer comes from VTOL, the library stores the transaction and responds to the point-of-sale application so that it continues with its business logic.
5- In case another card payment is entered, we return to step 2 and so on.
6- Once the transaction is charged, the point of sale closes the session against the Emv Kit library, indicating whether it ended successfully or if it should be cancelled. For both cases, the library synchronizes with the VTOL Server and confirms closed transactions or reverses cancelled transactions.
2.1.2 Start Session with Pending Reversal
If the library is processing a reversal, it will not be available for processing a sale. In this case, an error message will indicate this scenario.
3. Installation
3.1 Installation Procedure
Installation of the Emv Kit Library or EMV Kit is done thanks to the use of an installer or graphic assistant.
Using this installation wizard, the agent component of the Napse Director solution is also installed so that the EMV Kit can be updated remotely.
To do this, the following steps must be taken:
- Start session in the operating system where the Emv Kit library will be installed with a user that has administrator permissions.
- Start the application installer by running the following command line statement:
java –jar INSTALADOR.jar
For example:
java –jar vtol-pos-client-lib-cl-installer-1.3.0.jar
Note: Check that you have set the JAVA_HOME variable correctly. If you do not have it, set it in the JVM installation folder. For this, check the installation folder, example: C:\Java\jdk1.8.0_25\. |
By running this statement, the file is decompressed.
3. The installer splash screen will be displayed. Press the “Next” (Siguiente) button.
4. When you move to the next screen, the terms and conditions of use of the software application will be displayed to be read and later accepted in order to continue with the installation.
Press the “OK” (Aceptar) button.
5. You must then accept the terms and conditions of use and complete the details (Emv Kit name and email address) of who accepts. Press the “Next” (Siguiente) button.
Note: If the terms and conditions of use are not accepted, the installation will not be completed. |
6. The following properties must be entered in the following screen:
- The directory where Java is located
- The directory where you want to install the Emv Kit Library or EMV Kit
- The company code, configured in Napse Director
- The store code, configured in Napse Director
- The code of the terminal of the store from which it will be operated, configured in Napse Director
- VTOL Server IP to be able to communicate
- VTOL Server port
- Default 3003 (with SSL)
h. The IP where EMV Kit communicates
- Default localhost
i. The port where EMV Kit is linked
- Default 3500
j. And finally, set if you want to update EMV Kit remotely thanks to Napse Director.
By enabling the checkbox component, you will be offered the option of completing the display properties of point 7. If the checkbox component is not enabled, the options of the display of point 8 will be offered.
Press the “Next” (Siguiente) button.
In case the directory where you want to install EMV Kit does not exist, you will have the option to create one.
Press the “Yes” (Sí) button to do this.
7. This screen will be provided when the “Remotely Upgradable” checkbox component of the previous point has been enabled.
The following information must be entered:
- IP to communicate with Napse Director
- The port to communicate with Napse Director
- 8490 by default
3. The port in which the Napse Director agent component listens
- 5000 by default
Press the “Next” (Siguiente) button.
8. Specify the port for the pinpad and select the pinpad driver using the dropdown. Press “Next” (Siguiente).
9. Press “Install” (Instalar) to run the installation.
Detailed installation information can be seen by pressing the “Show Details” (Enseñar detalles) button. Doing this will show two tabs:
- In the “Output” (Salida) tab you can observe the installation progress by viewing the tasks executed by the installer
- The “Errors” (Errores) tab shows the faults that occurred during installation
10. Completion of the installation is reported by a message that says “Done” (Terminado). Press “OK”. (Aceptar)
11. Press the “Exit” (Salir) button to exit the installer.
3.2 Installed Services
Finally, the Emv Kit library or EMV Kit functions as a service together with the Napse Director agent component:
Where:
- EmvKit: Emv Kit Library or EMV Kit Service
- EmvKitDirectorService: Service of the agent component of Napse Director of the corresponding Emv Kit Library or EMV Kit
3.3 Installed Directories
Inside the installation directory (specified in point 6) is the installed version of the Emv Kit Library with the following directory structure:
Folder / File | Description |
backup | Directory that will maintain the last five file backups of the installed versions of the EMV Kit solution during the installation task |
emvkit | It contains all the files required for the operation of the EMV Kit |
sdagent | It contains the Napse Director agent component files (configuration, binaries, and records) |
sdagentcmds | It contains the 23 files to start/stop/query the EMV Kit solution manager agent |
tmp | It maintains the files in the EMV Kit solution to be installed during the synchronization task |
util | It contains utilities for creating services on Linux |
licenseAccepted.sts | Text file that mentions the user name, the user email and the date the user accepted the terms and conditions of use |
nssm.exe | Application responsible for building EMVKit and EMVKitDirectorService services for Windows |
Within the “emvkit” folder, the following directory structure is obtained:
Folder / File | Description |
config | It contains the configuration files required for the Emv Kit library or EMV Kit |
lib | It contains all proprietary and third-party JAR files required for the operation of the Emv Kit library |
start.cmd | Application startup file as Windows process |
start.sh | Application startup file as a Linux process |
IMPORTANT: Installation using the graphical wizard will set the entire EMV Kit solution. If you need to set a file manually, you will need to stop the service and make the change based on the “Configuration” (Configuración) section. |
4. Configuration
The Emv Kit library has the following configuration files:
4.1 JAVA Configuration Options
For the Emv Kit library to work properly, the following parameters must be set (the start.cmd file already has default configuration):
Parameters | Description |
-DLIB_BIND_ADDRESS | IP address at which the library will receive and send messages to the point of sale. If this property is not mentioned, the default bind is 127.0.0.1 |
-DBASE_CONF_DIR | Absolute directory of library configuration |
-DLOG_DIR | Absolute directory of application logging. This variable is used in the logging configuration file (log4j.properties). There is the possibility of dispensing with this variable. To do this, you must specify the absolute value in the logging configuration |
4.2 Configuration Files
The Emv Kit library has the following configuration files:
File | Description |
data\config.dat | File created and managed by the library. It is used to maintain TBK configuration in VTOL |
auditTransaction.obj | File with audit of library session transactions |
business.properties | File containing configuration related to business rules |
devices.properties | Pinpad driver and controller configuration file. Internal use of the library. It must not be modified |
log4j.properties | Library logging configuration |
logging.properties | Library logging configuration |
serialPinPad.properties | Pinpad device configuration |
session.obj | A file that records status and transactional information from the last session that the POS established with the Emv Kit library |
synthesis.keystore | File that stores library keys and certificates |
vtolClient.properties | It contains connection properties to the VTOL Server |
4.3 Logging configuration
The Emv Kit library logs in accordance with the directives contained in the log4j.properties logging configuration file.
The most important configuration options are described below:
Property | Description |
log4j.appender.file.File | Logging output file name and path |
log4j.appender.file.MaxFileSize | Maximum size of the logging file before doing the “rolling” (change to another logging file) |
log4j.appender.file.MaxBackupIndex | Maximum number of logging files to be retained |
4.4 VTOL Link Configuration
The Emv Kit library communicates with the VTOL Server, and the link properties are located in the vtolClient.properties. configuration file.
Property | Description |
HOSTIP | IP or server name where the VTOL Server is located |
HOSTPORT | VTOL Server Communication Port |
4.5 PINPAD Configuration
The Emv Kit library connects to the Transbank PINPAD.
To achieve such connection, the COM communication port where the PINPAD is connected must be properly set up.
For example, if the port enabled to work with the PINPAD is COM 9, we must enter the following information in the serialPinPad.properties file:
| Property | Description | Default Value |
| portName | Port name | COM9 |
| dataBits | Data bits length | 8 |
stopBits | 1 | |
baudRate | Baud rate of serial port | 19200 |
parity | Parity | none |
timeout | Default time to wait for response from PINPad. This time is expressed in milliseconds. | 180000 |
pinEntryTimeout | Time in milliseconds to wait until card holder enters PIN. If card holder doesn’t enter PIN during these milliseconds, then a packet 72 should be sent to PINPad to cancel PIN entry. | 180000 |
bufferSize | Maximum size of the serial port reading buffer. | 2048 |
nativeImpleClass | Native driver class to communicate with PINPad. |
Example:
PPVX805TBK.portName=COM9 PPVX805TBK.dataBits=8 PPVX805TBK.stopBits=1 PPVX805TBK.baudRate=19200 PPVX805TBK.parity=none PPVX805TBK.timeout=180000 PPVX805TBK.pinEntryTimeout=180000 PPVX805TBK.bufferSize=2048 PPVX805TBK.nativeImpleClass=com.Synthesis.vtolClientLib.deviceAdapters.RxTx SimpleSerialNativeLibWrapperImpl #PPVX805TBK.nativeImpleClass=cl.com.Synthesis.vtol.clientTbk.test.pinpad.TransbankVX8xxPinpadEmulatorConnector |
4.6 Business Configuration
The Emv Kit library allows you to set certain properties for certain operations in the business.properties file.
Property | Description | Default Value |
ServiceApiBridge.responsePosTimeOut | Time to elapse for Emv Kit Library to respond TimeOut to POS | 60000 |
CloseSessionOperation.trxIdListRequired | Flag that triggers validation that the field closeTrxIdList(1009) is required at the time that the POS performs “Close Session” | true |
Example:
ServiceApiBridge.responsePosTimeOut=60000 CloseSessionOperation.trxIdListRequired=true |
5. Integration
As mentioned above, the Emv Kit library runs as a stand-alone application in POS, independent of the point-of-sale application, publishing a TCP/IP server communication port, capable of interpreting messages from the VTOL protocol (same communication protocol used by the VTOL Server).
Integration with the point-of-sale application will be done through the VTOL thin client library, which provides the entire communication mechanism with the Emv Kit library, allowing to send and receive messages from the VTOL protocol. The point-of-sale application will basically indicate which fields are to be sent, and then process the response.
5.1 Service Integration
In order to make calls to the Emv Kit library, it is necessary for the point-of-sale application to integrate the client library, also called “thin”:
This library is available in 2 versions:
- JAVA
- .NET
The use of each will depend on the programming language of the point-of-sale application or the integrator system.
For more information refer to the documentation of the thin library.
5.2 Types of Operation
The Emv Kit library recognizes the following types of operations:
A. Create Session
This is the first operation to be executed by the point-of-sale application when a payment transaction is initiated.
It allows you to start session between the point-of-sale application and the Emv Kit library.
Internally, the library verifies connectivity with the PINPAD and synchronizes with the VTOL Server.
The fields that the point-of-sale application should send to the Emv Kit Library, making use of the client library, are outlined below.
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 |
store |
Alphanumeric |
Compulsory | Identifier of the originator site of the transaction |
2 |
node |
Numerical |
Compulsory | Node identification, at the originator site, where the transaction was generated |
11 |
trxType |
Alphanumeric |
Compulsory | Transaction Type:
|
1025 | transactionalControl | Alphanumeric | Optional | Optional flag field. This active field indicates that a transaction-by-transaction control must be performed to decide what action to take on the last transaction processed in the library (confirm it or reverse it). Possible values: 0: Disabled control 1: Enabled control By default, the transaction control is disabled, although it is recommended to use it to avoid inconsistency states. |
Example
Request to Emv Kit library: {2:1;1:1;11:createSession} |
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
1010 | currentSessionId | Numerical | New session identifier |
1027 |
libResponseCode |
Numerical | Response code from the library. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
| 1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
Example
Response from Emv Kit library: {1:1;2:1;1010:1463407572364;1027:000;1028:Ok} |
B. Read Card
After the point-of-sale application has successfully open the session of the Emv Kit Library, the card is read to initiate the payment.
The requirements and responses for this operation are outlined below:
Sale
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 |
store |
Alphanumeric |
Compulsory | Identifier of the originator site of the transaction |
2 |
node |
Numerical |
Compulsory | Node identification, at the originator site, where the transaction was generated |
11 |
trxType |
Alphanumeric |
Compulsory | Transaction Type:
|
12 |
amount |
Amount |
Compulsory | Amount of the transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. E.g.: 1000 equals 10.00 |
13 |
currency |
Alphanumeric |
Compulsory | Currency Types:
|
24 | lastTrxId | Numerical | Optional | Used when transactional control is active. In this field the POS must submit the last successfully processed transaction (If the POS had any problems with the previous transaction you should not send your trxId in this field.) |
25 | dateTime | Numerical | Optional | Date and time the transaction was performed in YYYYMMDDHHMMSS format |
| 101 | cardType | Alphanumeric | Compulsory | Card type, allowed values:
|
| 104 | tipAmount | Amount | Optional | Tip or donation amount |
| 107 | cashbackAmount | Amount | Optional | Amount of change |
| 1111 | cashbackList | Alphanumeric | Optional | List of allowed, comma-separated changes |
Example
Request to Emv Kit library: {107:0;13:$;104:0;12:12750000;11:Sale;13:$;101:CR;1111:100000,500000,1000000, 2000000,;2:1;25:20160516110614;1:1} |
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
8 | bin | Numerical | It reports the first 6 digits of the card |
25 | dateTime | Numerical | [Optional: If it travels on the request] Date and time of transaction in YYYYMMDDHHMMSS format |
101 |
cardType |
Alphanumeric | Card type, allowed values:
|
1010 | currentSessionId | Numerical | Current session identifier |
1027 |
libResponseCode |
Numerical | Response code from the library. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
1102 | provider | Alphanumeric | Abbreviation of the card. Example VI = VISA, MC = MASTERCARD, etc. |
1103 |
cardContextId |
Alphanumeric | It identifies the context of the card. It is a reference value to the card that was read via the PINPAD. It must be sent in the next call “Send Authorization” (Enviar autorización) |
1110 |
requireLastFourDigits |
Numerical | [Optional if Trx was approved] It indicates whether the POS should send the last 4 digits of the card in the Sales Authorization message. Possible values:
|
Example
Response from Emv Kit library: {1:1;1102:CR;2:1;1103:20160516110619911;6:7787;8:450799;25:20160516110614;101 0:1463407572364;1110:1;1027:000;1028:Ok} |
Void Sales
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 |
store |
Alphanumeric |
Compulsory | Identifier of the originator site of the transaction |
2 |
node |
Numerical |
Compulsory | Node identification, at the originator site, where the transaction was generated |
11 |
trxType |
Alphanumeric |
Compulsory | Transaction Type:
|
12 | amount | Amount | Optional | Amount to be validated of the transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. E.g.: 1000 equals 10.00 |
13 |
currency |
Alphanumeric |
Compulsory | Currency Types:
|
24 |
lastTrxId |
Numerical |
Optional | Used when transactional control is active. In this field the POS must submit the last successfully processed transaction (If the POS had any problems with the previous transaction you should not send your trxId in this field.) |
25 |
dateTime |
Numerical |
Optional | Date and time of transaction in YYYYMMDDHHMMSS format |
100 |
uniqueNumber |
Numerical | Compulsory | Unique identifier of the Sales operation. Longitude 26 |
101 |
cardType |
Alphanumeric |
Compulsory | Card type, allowed values:
|
Example
Request to Emv Kit library: {25:20160516110634;101:CR;2:1;100:00000001000001160516110624;1:1;11:VoidSale;13:$} |
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 |
node |
Numerical | Node identification, at the originator site, where the transaction was generated |
8 | bin | Numerical | It reports the first 6 digits of the card |
25 |
dateTime |
Numerical | [Optional: If it travels on the request] Date and time of transaction in YYYYMMDDHHMMSS format |
101 |
cardType |
Alphanumeric | Card type, allowed values:
|
1010 | currentSessionId | Numerical | Current session identifier |
1027 |
libResponseCode |
Numerical | Response code from the library. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
1102 | provider | Alphanumeric | Abbreviation of the card. Example VI = VISA, MC = MASTERCARD, etc. |
1103 |
cardContextId |
Alphanumeric | It identifies the context of the card. It is a reference value to the card that was read via the PINPAD. It must be sent on the next call “Send Authorization” (Enviar autorización) |
1110 |
requireLastFourDigits |
Numerical | [Optional if Trx was approved] It indicates whether the POS should send the last 4 digits of the card in the Sales Authorization message. Possible values:
|
Example
Response from Emv Kit library: {1:1;1102:CR;2:1;1103:20160516110638744;8:450799;25:20160516110634;1010:14634 07572364;1110:1;1027:000;1028:Ok} |
C. Send Authorization
After reading the card and confirming the POS, it is necessary to send authorization operations, among which are the Sale and the Void Sale.
The following are the requirements and responses for these operations:
Sale
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 |
store |
Alphanumeric |
Compulsory | Identifier of the originator site of the transaction |
2 |
node |
Numerical |
Compulsory | Node identification, at the originator site, where the transaction was generated |
6 |
lastFourDigits |
Numerical |
Compulsory | Last 4 digits of the card returned in the original sale |
11 |
trxType |
Alphanumeric |
Compulsory | Transaction Type:
|
12 |
amount |
Amount |
Compulsory | Amount of the transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. E.g.: 1000 equals 10.00 |
14 | payments | Numerical | Optional | Number of installments |
25 |
dateTime |
Numerical |
Optional | Date and time of transaction in YYYYMMDDHHMMSS format |
29 |
serialNumber |
Alphanumeric |
Optional | Serial number identifying the terminal. If the POS sends this value, it will be used to send to the authorizer. |
30 |
businessNumber |
Alphanumeric |
Optional | Business code. If the POS sends this value, it will be used to send to the authorizer |
103 | paymentsAmount | Amount | Optional | Amount of the installments |
108 | ticket | Alphanumeric | Compulsory | Ticket number |
1101 | product | Numerical | Optional | Product Code |
1103 |
cardContextId |
Alphanumeric |
Compulsory | It identifies the context of the card. It is a reference value to the card that was read via the PINPAD. It is the value returned by the last “Read Card” (Leer Tarjeta) operation |
| 1118 | voucherParameters | Map | Optional | It sends the parameters and formats of the voucher. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, ke2|value2,..., keyN|valueN] See Voucher Parameters section |
Example
Request to Emv Kit library: {1103:20160516110619911;108:10;13:$;12:12050000;11:Sale;30:597040000902;6:7787; 29:S4Napse00002;2:1;25:20160516110622;1:1} |
- Response
| Number | Field Name | Data Type | Description |
| 1 | store | Alphanumeric | Identifier of the originator site of the transaction |
| 2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
| 24 | trxId | Numerical | Unique transaction identifier. In case the transaction response is received and processed successfully by the POS, this ID must be included in field 24 of the next Card Reading operation. |
| 25 | dateTime | Numerical | [Optional: If it travels on the request] Date and time of transaction in YYYYMMDDHHMMSS format |
| 27 | isoCode | Numerical | ISO-8583 Response Code issued by the authorization center. 3 digits maximum.
|
| 28 | responseMessage | Alphanumeric | ISO-8583 Response message related to Field Code 27 |
| 100 | uniqueNumber | Numerical | Unique identifier of the Sales operation. Longitude 26 |
| 111 | graceMonth | Numerical | It indicates whether it has grace month. Possible values:
|
| 1010 | currentSessionId | Numerical | Current session identifier |
| 1027 | libResponseCode | Numerical | Response code from the library. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
| 1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
| 1102 | provider | Alphanumeric | Abbreviation of the card. Example VI = VISA, MC = MASTERCARD, etc. |
1105 | awardedTrx | Numerical | [Optional if Trx was approved] It indicates whether the transaction was awarded. Possible values:
|
1106 | awaredTrxMsg | Alphanumeric | Optional if the Trx was approved and awarded.] Message indicating that the transaction was awarded. |
1107 | trxWithPIN | Numerical | [Optional if Trx was approved] It indicates whether the transaction was made with PIN. Possible values:
|
1108 | printInterestTax | Numerical | [Optional if Trx was approved] It indicates whether to print the interest rate. Possible values:
|
1109 | voucherType | Numerical | [Optional if the Trx was approved] It indicates the type of voucher. Possible values:
|
1120 | voucherHeader | Map | [Optional 1] It returns the voucher header data. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,…, keyN|valueN] See Voucher Header section |
1121 | voucherFooter | Map | [Optional 1] It returns the voucher footer data. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Footer section |
1122 | voucherBody | Map | [Optional 1] It returns the voucher body. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Body section |
1123 | formattedVoucher | Map | [Optional 2] It returns the complete and formatted voucher to be printed. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Format section |
1124 | printVoucher | Numerical | [Optional 3] Reserved for future use. It indicates whether the voucher printing was successful or not. Allowed values:
|
1129 | rePrintFormattedVoucher | Map | [Optional 2] It returns the complete voucher with the format for reprinting. The value received corresponds to a composite field map with a key (original) and its value in base64. [key1|value1] See Voucher Format section |
Optional fields:
[Optional 1]: When the authorization was approved and the library returns the Voucher data separated in header, body, and footer.
[Optional 2]: When the authorization was approved and the library returns the formatted Voucher in a single field.
[Optional 3]: When the authorization was approved and the library is in charge of printing the Voucher. Not implemented, reserved for future use.
Example
Response from Emv Kit library: {1:1;2:1;100:00000001000001160516110624;1103:20160516110619911;6:7787;111:0;1 010:1463407572364;1027:000;1122:[numeroDoc|10,numeroOperacion|001003278,fecha |16/05/16,empleado|0000,numeroUnico|00000001000001160516110624,tasaInteres|0. 00,tipoCuotas|0,vuelto|0,montoCuotaDiferido1|0,montoCuotaDiferido2|0,montoCuo taDiferido3|0,marcaTarjeta|CR,montoPremio|120.500,hora|11:06:26,propinaDonaci on|0,numeroTarjeta|7787,glosaTipoCuotas|SIN CUOTAS,terminal|S4Napse00002,codigoAutorizacion|552873 B,monto|120.500,montoCuota|0];1028:Ok;1120:[versionApp|Cod Comercio - Version APP,codigoEECC|597040000902,nombreEECC|Nombre Comercio,ciudadComercio|Ciudad Comercio,direccionComercio|Direccion Comercio,nombreComercio|Nombre Comercio];1121:[pie7|operación sujeta a impuesto?,pie6|las que ya incluyen intereses,pie5|en el numero y monto de cuotas?,pie4|Acepto el cargo en mi tarjeta pagado?,pie3|Acepto Pagar según contrato con?,pie2|Original Comercio - Copia Cliente,pie1|Gracias por su Compra];25:20160516110622;1109:3;1108:0;27:000;1105:0;28:APROBADO;1107:0} |
Void Sales
MESSAGING
- Requirement
| Number | Field Name | Data Type | Compulsory | Description |
1 | store | Alphanumeric | Compulsory | Identifier of the originator site of the transaction |
2 |
node |
Numerical |
Compulsory | Node identification, at the originator site, where the transaction was generated |
6 |
lastFourDigits |
Numerical |
Compulsory | Last 4 digits of the card returned in the original sale |
11 |
trxType |
Alphanumeric |
Compulsory | Transaction Type:
|
12 |
amount |
Amount |
Optional | Amount to be validated of the transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. E.g.: 1000 equals 10.00 |
25 |
dateTime |
Numerical |
Optional | Date and time of transaction in YYYYMMDDHHMMSS format |
29 |
serialNumber |
Alphanumeric |
Optional | Serial number identifying the terminal. If the POS sends this value, it will be used to send to the authorizer |
30 |
businessNumber |
Alphanumeric |
Optional | Business code. If the POS sends this value, it will be used to send to the authorizer |
100 |
uniqueNumber |
Numerical |
Compulsory | Unique identifier for the Original Sale operation. Longitude 26 |
108 | ticket | Alphanumeric | Optional | Ticket number |
1103 |
cardContextId |
Alphanumeric |
Compulsory | It identifies the context of the card. It is a reference value to the card that was read via the PINPAD. It is the value returned by the last “Read Card” (Leer Tarjeta) operation |
1118 |
voucherParameters |
Map |
Optional | It sends the parameters and formats of the voucher. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, ke2|value2,..., keyN|valueN] See Voucher Parameters section |
Example
Request to Emv Kit library: {6:7787;1103:20160516110638744;25:20160516110642;101:CR;2:1;100:000000010000011 60516110624;1:1;11:VoidSale;29:S4Napse00002;30:597040000902} |
- Response
| Number | Field Name | Data Type | Description |
| 1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
24 | trxId | Numerical | Unique transaction identifier. In case the transaction response is received and processed successfully by the POS, this ID must be included in field 24 of the next Card Read operation. |
25 | dateTime | Numerical | [Optional: If it travels on the request] Date and time of transaction in YYYYMMDDHHMMSS format |
27 | isoCode | Numerical | ISO-8583 Response Code issued by the authorization center. 3 digits maximum.
|
28 | responseMessage | Alphanumeric | ISO-8583 Response message related to Field Code 27 |
100 | uniqueNumber | Numerical | Unique ID of the Void operation. Longitude 26 |
111 | graceMonth | Numerical | Indicates whether it has a grace month. Possible values:
|
1010 | currentSessionId | Numerical | Current session ID |
1027 | libResponseCode | Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
1105 | awardedTrx | Numerical | [Optional if Trx was approved] It indicates whether the transaction was awarded. Possible values:
|
1106 | awaredTrxMsg | Alphanumeric | [Optional if Trx was approved and awarded]. Message indicating that the transaction was awarded. |
1107 | trxWithPIN | Numerical | [Optional if Trx was approved] It indicates whether the transaction was made with PIN. Possible values:
|
1108 | printInterestTax | Numerical | [Optional if Trx was approved] It indicates whether to print the interest rate. Possible values:
|
1109 | voucherType | Numerical | [Optional if the Trx was approved] It indicates the type of voucher. Possible values:
|
| 1120 | voucherHeader | Map | [Optional 1] It returns the voucher header. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Header section |
| 1121 | voucherFooter | Map | [Optional 1] Returns the voucher footer. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Footer section |
| 1122 | voucherBody | Map | [Optional 1] It returns the voucher body. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Body section |
| 1123 | formattedVoucher | Map | [Optional 2] It returns the complete and formatted voucher to be printed. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See Voucher Format section |
| 1124 | printVoucher | Numerical | [Optional 3] Reserved for future use. It indicates whether the voucher printing was successful or not. Allowed values:
|
| 1129 | rePrintFormattedVoucher | Map | [Optional 2] It returns the complete voucher with the format for reprinting. The received value corresponds to a composite map field with a key (original) and its value in base64. [key1|value1] See Voucher Format section |
Optional fields:
[Optional 1]: When the authorization was approved and the library returns the Voucher data separated in header, body and footer.
[Optional 2]: When the authorization was approved and the library returns the formatted Voucher in a single field.
[Optional 3]: When the authorization was approved and the library is in charge of printing the Voucher. Not implemented, reserved for future use.
Example
Response from Emv Kit library: {1:1;2:1;100:00000001000001160516110644;1103:20160516110638744;6:7787;111:0;1010:1463407572364;1027:000;1122:[numeroDoc|10,numeroOperacion|001003278,fecha|16/05/16,empleado|0000,numeroUnico|00000001000001160516110644,tasaInteres|0. 00,tipoCuotas|0,vuelto|0,montoCuotaDiferido1|0,montoCuotaDiferido2|0,montoCuo taDiferido3|0,marcaTarjeta|CR,montoPremio|120.500,hora|11:06:46,propinaDonaci on|0,numeroTarjeta|7787,glosaTipoCuotas|SIN CUOTAS,terminal|S4Napse00002,cantidadCuotas|0,codigoAutorizacion|552873 B,monto|120.500,montoCuota|0];1028:Ok;1120:[versionApp|Cod Comercio - Version APP,codigoEECC|597040000902,nombreEECC|Nombre Comercio,ciudadComercio|Ciudad Comercio,direccionComercio|Direccion Comercio,nombreComercio|Nombre Comercio];1121:[pie7|operación sujeta a impuesto?,pie6|las que ya incluyen intereses,pie5|en el numero y monto de cuotas?,pie4|Acepto el cargo en mi tarjeta pagado?,pie3|Acepto Pagar según contrato con?,pie2|Original Comercio - Copia Cliente,pie1|Gracias por su Compra];25:20160516110642;1109:3;1108:0;27:000;1105:0;28:APROBADO;1107:0} |
IMPORTANT: The point-of-sale application must have the capacity to register the different trxId it receives in the successive APPROVED authorizations, within the session, because it must send them at the moment of closing the session to confirm them with the VTOL Server. |
D. OnUs Operations
In OnUs transactions, Transbank does not operate as the authorizer, but the client itself has its own authorization system.
In this modality, it is not necessary to perform the “Read Card” operation of the library. Available OnUs operations are Cryptogram Sale and Validation. The following are the requirements and responses for these operations:
Sale
MESSAGING
- Requirement
| Number | Field Name | Data Type | Compulsory | Description |
| 1 | store | Alphanumeric | Compulsory | Identifier of the originator site of the transaction |
| 2 | node | Numerical | Compulsory | Node identification, at the originator site, where the transaction was generated |
| 11 | trxType | Alphanumeric | Compulsory | Transaction Type:
|
12 | amount | Amount | Compulsory | The amount of the transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. Example: 1000 equals 10.00 |
13 |
currency |
Alphanumeric |
Compulsory | Currency Types:
|
14 | payments | Numerical | Optional | Number of installments |
25 |
dateTime |
Numerical |
Optional | Date and time of transaction in YYYYMMDDHHMMSS format |
103 | paymentsAmount | Amount | Optional | Amount of the installments |
107 | cashbackAmount | Amount | Optional | Amount of the change |
1111 | cashbackList | Alphanumeric | Optional | List of allowed, comma-separated, changes |
1130 |
workingKeyPin |
Alphanumeric |
Compulsory | Working key to encrypt the PIN for the OnUs operation |
1131 |
commercialMessage |
Alphanumeric |
Compulsory | Commercial message reported by the POS or OnUs business |
Example
Request to Emv Kit library: {107:0;14:3;13:$;12:50000;103:933000;11:SaleOnUs;1111:100000,500000,1000000,200 0000,;1131:***TARJETA COMERCIAL***;1130:70512FD35034DDC897710CA3334E4CF3;2:2;25:20170824102251;1:1} |
- Response
| Number | Field Name | Data Type | Description |
| 1 | store | Alphanumeric | Identifier of the originator site of the transaction |
| 2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
| 6 | lastFourDigits | Numerical | Reports the last 4 digits of the card |
| 8 | bin | Numerical | Reports the first 6 digits of the card |
| 9 | track2 | Alphanumeric | Track2 of the card |
| 10 | inputMode | Alphanumeric | How the card was entered/read. Possible values:
|
| 25 | dateTime | Numerical | [Optional: If it travels on the request] Date and time of transaction in YYYYMMDDHHMMSS format |
56 | pinBlock | Alphanumeric | Pin block length 16 |
1010 | currentSessionId | Numerical | Current session ID |
1027 |
libResponseCode |
Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
1102 | provider | Alphanumeric | The abbreviation of the card. Example VI = VISA, MC = MASTERCARD, etc. |
1103 | cardContextId | Alphanumeric | Identifies the context of the card |
1112 | cardHolderName | Alphanumeric | Name of cardholder |
1135 | cryptogram | Alphanumeric | Cryptogram |
1136 | track1 | Alphanumeric | Track1 of the card |
1137 | completePinpadResponse | Alphanumeric | Frame of the Pin Pad response of the 0810 command |
1138 | cardName | Alphanumeric | Card brand name. Example: VISA, MASTERCARD, MAESTRO, AMEX, etc. |
Example
Response from Emv Kit library: {1:1;2:2;1027:000;1028:Ok;6:7777;8:789348;9:89797987;10:00;1102:VI;1103:20170 82411560639;1135:1232343223;1136:1321546;1010:1503585583959;1112:TARJETA COMERCIAL VISA;56:1232437534236576;25:20170824115605;1137:0810|00|20170828121857919|00| 1321546|89797987|7898|7777|TARJETA ABCVISA|AB|1232|1232|} |
Cryptogram Validation
MESSAGING
- Requirement
| Number | Field Name | Data Type | Compulsory | Description |
| 1 | store | Alphanumeric | Compulsory | Identifier of the originator site of the transaction |
| 2 | node | Numerical | Compulsory | Node identification, at the originator site, where the transaction was generated |
| 11 | trxType | Alphanumeric | Compulsory | Transaction Type:
|
25 | dateTime | Numerical | Optional | Date and time of transaction in YYYYMMDDHHMMSS format |
1103 | cardContextId | Alphanumeric | Compulsory | Identifies the context of the card |
1132 | glosaScreenResponse | Alphanumeric | Optional | Gloss screen response |
1133 | glosaResponse | Alphanumeric | Compulsory | Response gloss |
1135 | cryptogram | Alphanumeric | Compulsory | Cryptogram |
Example
Request to Emv Kit library: {1132:Glosa respuesta PANTALLA;1103:2017082411590639;25:20170824122329;1135:1232343223;2:2;1:1;1133:Glosa respuesta PINPAD;11:ValidateSaleOnUs} |
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
25 | dateTime | Numerical | [Optional: If it travels on the request] Date and time of transaction in YYYYMMDDHHMMSS format |
1010 | currentSessionId | Numerical | Current session ID |
1027 | libResponseCode | Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
1133 | glosaResponse | Alphanumeric | Response gloss |
Example
Response from Emv Kit library: {1:1;2:2;1010:1503585583959;1027:000;1028:Ok;25:20170824122329;1133:GlosaRespuesta} |
E. View Sales Transaction
Through this message you can obtain data related to an original sale.
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 | store | Alphanumeric | Compulsory | Identifier of the originator site of the transaction |
2 | node | Numerical | Compulsory | Node identification, at the originator site, where the transaction was generated |
11 | trxType | Alphanumeric | Compulsory | Transaction Type:
|
100 | uniqueNumber | Numerical | Compulsory | Unique identifier of the Sale operation. Longitude 26 |
Example
Request to Emv Kit library: {2:1;100:00000001000002290817114534;1:1;11:GetOriginalSale} |
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 |
node |
Numerical | Node identification, at the originator site, where the transaction was generated |
6 | lastFourDigits | Numerical | Reports the last 4 digits of the card |
8 | bin | Numerical | Reports the first 6 digits of the card |
12 |
amount |
Amount | The amount of the transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. Example: 1000 equals 10.00 |
13 |
currencyPosCode |
Alphanumeric | Currency Type:
|
14 | payments | Numerical | Number of installments. 2 digits maximum. |
38 |
authorizationNumber |
Numerical | Authorization code generated by the authorization center for the sale transaction |
101 | cardType | Alphanumeric | Card type, allowed values:
|
102 | paymentsType | Numerical | Type of installments: “0": no installments “1”: normal installments “3": 3 installments “4": business installments “5”: n-installments |
| 103 | paymentsAmount | Numerical | Amount of the installments |
| 104 | tipAmount | Numerical | Tip/Donation Amount |
| 106 | sequenceNumber | Numerical | Sales sequence number |
| 108 | ticket | Alphanumeric | Ticket number |
| 120 | originalDate | Numerical | Date and time of the original Sale transaction. YYYYMMDDHHMMSS format |
| 1010 | currentSessionId | Numerical | Current session ID |
| 1027 | libResponseCode | Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
| 1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
| 1128 | voidAmount | Amount | Void amount of the original sale transaction. 18 digits maximum. Sent without a comma. The last two digits represent the decimal places. Example: 1000 equals 10.00 |
Example
Response from Emv Kit library: {1:1;2:1;1027:000;1028:Ok;101:CR;12:50000;38:552873 B;102:0;103:00;104:0.0;8:450799;1128:00;106:1003278;108:10;13:$;14:0;1010:150 4195178743;120:20170829114536;6:7787} |
F. Get POS Configuration
This message allows the point-of-sale to obtain the existing Transbank configuration in the VTOL Server. It must be run after creating a successful session with the Emv Kit library.
The configuration is managed through the VTOL Web console.
The fields that the point-of-sale application should send to the Emv Kit Library, making use of the client library, are outlined below.
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 | store | Alphanumeric | Compulsory | Identifier of the originator site of the transaction |
2 | node | Numerical | Compulsory | Node identification, at the originator site, where the transaction was generated |
11 | trxType | Alphanumeric | Compulsory | Transaction Type:
|
Example
Request to Emv Kit library: {2:1;1:1;11:getConfiguration} |
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 |
node |
Numerical | Node identification, at the originator site, where the transaction was generated |
113 |
confParameters |
Map | POS configuration received from the VTOL server. The received value corresponds to a composite field map with a series of keys and values: [key1|value1, key2|value2,..., keyN|valueN] See POS Configuration Format section |
1010 | currentSessionId | Numerical | Current session ID |
1027 |
libResponseCode |
Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
Example
Response from Emv Kit library: {1010:1461101787171;1028:Ok;1027:000;113:[monMinPesosChilenos|500,maxCuotasN| 12,moneda|CL,anulacion|Y,venta|N,monMinDolares|100,version|3,pie7|operación sujeta a impuesto?,pie6|las que ya incluyen intereses,pie5|en el numero y monto de cuotas?,propina|N,pie4|Acepto el cargo en mi tarjeta pagado?,terminal|S4Napse00002,baudiosPinPad|9600,timeOut4Digitos|0,pie3|Acepto Pagar según contrato con?,pie2|Original Comercio - CopiaCliente,pie1|Gracias por su Compra,tipoDeCaja|Caja Host,empleado|N,panManual|N,pan|N,debito|Y,encab3|Ciudad Comercio,encab4|Cod Comercio - Version APP,timeOut|60,comercio|597040000902,boleta|Y,cashBack|N,montoVuelto4|20000,m ontoVuelto3|10000,encab1|Nombre Comercio,montoVuelto2|5000,encab2|Direccion Comercio,montoVuelto1|1000];2:1;1:1} |
G. Batch closure
This operation allows the point-of-sale to exchange total amounts with the Transbank Host. It must be done within an active session with the Emv Kit library.
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 | store | Alphanumeric | Compulsory | Identifier of the originator site of the transaction |
2 | node | Numerical | Compulsory | Node identification, at the originator site, where the transaction was generated |
11 | trxType | Alphanumeric | Compulsory | Transaction Type:
|
13 | currency | Alphanumeric | Compulsory | Currency Types:
|
29 | serialNumber | Alphanumeric | Optional | Serial number identifying the terminal. If the POS sends this value, it will be used to send to the authorizer. |
30 | businessNumber | Alphanumeric | Optional | Business code. If the POS sends this value, it will be used to send to the authorizer. |
Example
Request to Emv Kit library: {2:1;1:1;11:Close;13:$;29:S4Napse00002; 30:597040000902} |
- Response
| Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 | node | Numerical | Node identification, at the originator site, where the transaction was generated |
25 | dateTime | Numerical | Date and time of transaction in YYYYMMDDHHMMSS format |
27 | isoCode | Numerical | ISO-8583 Response Code issued by the authorization center. 2 digits maximum.
|
28 | responseMessage | Alphanumeric | ISO-8583 Response message related to Field Code 27 |
1010 | currentSessionId | Numerical | Current session ID |
1027 |
libResponseCode |
Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
1125 | saleTrxQuantity | Alphanumeric | Number of sales transactions |
1126 | saleTrxAmount | Numerical | Amount of sales transactions |
1127 | voidTrxQuantity | Numerical | Number of Void Transactions |
1128 | voidTrxAmount | Numerical | Amount of Void Transactions |
Example
Response from Emv Kit library: {1126:0;1125:0;1010:1461101849891;1028:Ok;1027:000;28:APROBADO;27:000;2:1;1:1;1128:0;1127:0;25:20160419223027} |
H. Close session
Closes session between the point-of-sale application and the Emv Kit library. Internally, the Emv Kit library synchronizes with the VTOL Server, confirming or cancelling transactions processed within the session.
IMPORTANT: It is important to close the session is closed in the Emv Kit library once the payment transaction is completed in the point-of-sale application, indicating whether the authorizations performed should be confirmed or reversed. |
MESSAGING
- Requirement
Number | Field Name | Data Type | Compulsory | Description |
1 |
store |
Alphanumeric |
Compulsory | Identifier of the originator site of the transaction |
2 |
node |
Numerical |
Compulsory | Node identification, at the originator site, where the transaction was generated |
11 |
trxType |
Alphanumeric |
Compulsory | Transaction Type:
|
1008 | closeSessionAction | Alphanumeric | Compulsory | Action to be performed on session closure:
|
1009 | closeTrxIdList | List | Compulsory. Only when field 1008 equals CLOSE | List of trxId (field 24) received in the responses to the various “Send Authorization” (Enviar autorización) calls |
250 |
actionCode |
Alphanumeric |
Compulsory when field 1008 equals FORCED_CLOSE | Identification of the reason why the session had a forced closure. 5-character code. Possible values:
|
251 |
actionNote |
Alphanumeric |
Optional | Reason reported by the point-of-sale when the session experienced a non-traditional closure. 50-character maximum |
Example
Request to Emv Kit library: {1008:CLOSE;2:1;1:1;11:closeSession} |
It is important to note that the closeSessionAction field can take one of the following values:
- CLOSE: The session ended successfully, i.e.; the point-of-sale application completed the point-of-sale transaction successfully
- CANCEL: Session did not end successfully, i.e.; the point-of-sale application did NOT successfully complete the point-of-sale transaction due to some sort of contingency
or FORCED_CLOSE: The session did not end successfully, i.e., the point-of-sale application did NOT successfully terminate the point-of-sale transaction and the session was forced to close.
For example, power outage, customer leaves, errors at the point-of-sale, etc.
- Response
Number | Field Name | Data Type | Description |
1 | store | Alphanumeric | Identifier of the originator site of the transaction |
2 |
node |
Numerical | Node identification, at the originator site, where the transaction was generated |
1010 | currentSessionId | Numerical | Identifier of the session that is closing |
1027 |
libResponseCode |
Numerical | Library response code. It indicates how the operation was processed in the Emv Kit library: Success = 000 Error <> 000 See Library Response Codes section |
1028 | libResponseMessage | Alphanumeric | Descriptive message of the library response code |
Example
Response from Emv Kit library: {1:1;2:1;1010:1463407572364;1027:000;1028:Ok} |
5.3 Authorization Approved
To determine that an authorization was approved, you need to:
1 - Check the field
1027 | libResponseCode |
If the value equals 000, it indicates that the library was able to send the request to the VTOL Server and process the response without problems. This is the first indicator that indicates that everything is running smoothly.
A different code indicates a processing error in the library, which must be handled.
2 - Check the isoCode field
27 | isoCode |
If the value equals 000, it indicates that the authorization has been approved.
6. Annexes
6.1 Emv Kit Library Response Codes
The response code of the Emv Kit library and its details can be found in these fields: Code = field 1027
Description = field 1028
| Code | Description | Meaning |
| UDF | UNDEFINED | It corresponds to the initial state of the status variable. The library should never return this value |
| 000 | Approved | Successful operation |
| 001 | Cancelled by user | The PINPAD CANCEL key was used |
| 002 | Entry error - last 4 digits | The PINPAD detected errors in the entry of the last 4 digits |
| 003 | Track2 read error | The PINPAD could not read Track II |
| 004 | Pinpad error - PIN entry | PIN entered incorrectly on the PINPAD |
| 005 | Chip error | The PINPAD could not read or save in the CHIP |
| 006 | Invalid Date Error | Invalid date entered in PINPAD |
| 007 | TimeOut error | The PINPAD suspended the operation by TIMEOUT |
| 008 | Error in received command sequence | The PINPAD rejected a command for being out of sequence |
| 009 | Error in received command format | The PINPAD rejected a command due to erroneous formatting |
| 011 | Error in received LRC command | The PINPAD rejected a command due to a wrong LRC |
| 086 | Read Error | Read Error |
| 087 | Pinpad without Master Key | The Pinpad does not have Master Key |
| 088 | Retrieved card does not allow OnUs treatment | Retrieved card does not allow OnUs treatment |
| 089 | Transaction Declined by Chip Card | The transaction was declined by the chip card |
| 090 | Card Not Allowed for Selected Mode | The card with said mode is not allowed |
| 091 | Number of Installments Error | Number of installments error |
| 092 | Does Not Match First Tapping Card | Card mismatch |
| 093 | Minimum Amount Error | Minimum amount error |
094 | Change amount Validation Error | Error when validating change |
095 | Context ID Error | Context ID error |
096 | Last 4 digits do not match | The last 4 digits of the card do not match |
097 | Transaction Does Not Allow Reverse | The reverse operation is not allowed |
098 | Message Format Error | Message format error |
099 | Cancelling the Command via the [CANCEL]/Timeout key | The command was canceled |
100 | The Pinpad is offline or unavailable | The Pinpad is unavailable |
101 | The session was already created. | Unable to create a new session with the Emv Kit library because an active session already exists. |
102 | The library is processing a requirement. | The Emv Kit library is currently processing a requirement. |
103 | The library is processing a response. | The Emv Kit library is currently processing a response to a requirement. |
104 | The library is processing a reverse. | The library is currently processing a reverse. |
600 | Amount field required | The Amount field, which is required for the operation, was not reported. |
601 | Currency Field required | The field, which is required for the operation, was not reported. |
602 | Card type field required | The Card type field, which is required for the operation, was not reported. |
603 | Change amount field required | The change amount field, which is required for the operation, was not reported. |
604 | Tip amount field required | The Amount field, which is required for the operation, was not reported. |
605 | Last 4 digits field required | The last 4 digits field of the card, which is required for the operation, was not reported. |
606 | Unique number field required | The unique number field, which is required for the operation, was not reported |
699 | Required data missing | A required field for the operation was not reported, the administrator should be consulted to identify it. |
700 | Unique Number Invalid | More than 26 digits were reported. |
701 | Session file does not exist | File containing session information does not exist |
702 | There are Trxs Pending with VTOL Server | There are pending transactions with VTOL that cannot be closed |
703 | Invalid Session Status | Session status is invalid |
704 | Invalid Transaction Type | Transaction type sent on call is invalid |
705 | Error sending message to VTOL Server | Error sending authorization to the VTOL Server |
706 | List of VTOL TrxIds not received (Session closure) | List of VTOL TrxIds not received at Session closure with CLOSE action |
707 | Invalid amount | Amount is invalid |
708 | Invalid Cash Back Amount | Cash back amount is invalid |
709 | Library sending confirmation to VTOL | Library sent confirmation to the VTOL Server |
710 | Unable to cancel session. There is a batch closure | Unable to cancel session because there is a batch closure |
711 | Error canceling session. There are sales without that are not void | Unable to cancel session because there are sales that are not void |
712 | Void Amount exceeds Sale | The amount to be voided exceeds the amount of the sale |
713 | Invalid Transaction | Transaction is invalid |
714 | Sale has already been voided | The sale has been voided previously |
715 | Unable to void Debit | Unable to void debit |
716 | There is no original sale | The transaction queried does not exist |
717 | Currency type does not apply | The currency used to void the sale is different |
801 | PAN: Unknown provider | Provider is unknown |
802 | PAN: Invalid digit | Invalid digit |
803 | Protocol Error | An error occurred in the protocol |
804 | Messages format error | Error occurred in message format |
805 | Card configuration failed | An error occurred in the configuration of the card |
806 | Error - RSA key invalid or null | RSA key is invalid or null |
807 | Null WK error or invalid format | Null WK error or invalid format |
901 | System Error (General) | Internal library error |
902 | System Error (I/O) | Input/output error or library communication error |
911 | System error (load) | Failed to load library |
912 | System Error (Non-existent context) | Non-existent library context error |
913 | System error (invalid context) | Invalid library context error |
914 | System error (loading working key) | Failed to load working key into library |
999 | There is an error in the session | There is an error in the session |
6.2 POS Configuration Format
This section details the information that travels in the confParameters response field of a configuration request message, which corresponds to the configuration generated for the POS in the VTOL Server.
As mentioned, the configuration travels in a composite field, with the following format:
[key1|value1, key2|value2,..., keyN|valueN]
The possible keys and the details of the value of each key are described below:
Key | Value Detail |
version | Application version. |
propina | Enables/disables the receipt of a tip for a transaction Y = Enables TIP entry. N = Does not allow TIP entry. By default, this field must have N value. |
pan | It refers to the credit card number. In this parameter, you can enable or disable the request for this piece of data when making the sale. |
cashBack | Enables/disables Cashback option (sale with change) for Debit transactions. Possible Values: Y = Enables the CASH-BACK option (sale with change) for Debit transactions. N = Does not allow sales with change on debit transactions. Note: By default, this field must have “N” value. |
montoVuelto1 | It allows you to define the amount associated with the option to return to the cardholder. Default value: 1000 |
montoVuelto2 | It allows you to define the amount associated with the option to return to the cardholder. Default value: 5000 |
montoVuelto3 | It allows you to define the amount associated with the option to return to the cardholder. Default value: 10000 |
montoVuelto4 | It allows you to define the amount associated with the option to return to the cardholder. Default value: 20000 |
encab1 | Business Name |
encab2 | Business Address |
encab3 | Business City |
encab4 | Business Code - APP Version |
pie1 | Thank you for your purchase |
pie2 | Business (original) - Customer (copy) |
pie3 | I agree to pay in accordance with the agreement with… |
pie4 | I accept the charge on my card paid on… |
pie5 | in the number and amount of the installments… |
pie6 | those that already include interest |
pie7 | Operation subject to tax… |
pie8 | Reserved |
pie9 | Reserved |
pie10 | Reserved |
moneda | This option specifies the type of currency that will be used to perform the card transaction. CL: Chilean Pesos US: US Dollars |
baudiosPinPad | Bauds specify the speed of the transfer of information between the PINPAD and the machine to which it is connected. (This value must match the value entered in the PPSC5000.ini file) |
tipoDeCaja | This option is configured for the application to start a face-to-face sale or a non-face-to-face sale, with the host cashier and agency options respectively. Possible values: Y: Yes N: No Default value N |
debito | Enables/disables the Debit Card sale transaction. This also enables/disables key load transactions. Possible Values: Y = Enables Debit Card sale transaction N = Does not allow Debit Card sale transactions. Note: By default, this field must have Y value |
monMinPesosChilenos | It specifies the minimum amount to make a card purchase. Amount entered in Chilean pesos. |
monMinDolares | It specifies the minimum amount in dollars to make a card purchase. |
empleado | Enables/disables the employee number request. Possible Values: Y = Enables the option to request the employee code. N = Does not allow to enter the employee code. Note: By default, it must have a Y value |
boleta | Enables/disables the ticket number request. |
Possible Values: Y = Enables the option to request ticket number N = Does not allow to enter ticket number. Note: By default, this field must have a value of Y | |
terminal | Identification of the point-of-sale assigned by Transbank for transactions in pesos currency. |
terminalDolar | Identification of the point-of-sale assigned by Transbank for transactions in dollars currency |
comercio | This option determines the Business to which VTOL (Branch) belongs for transactions in pesos currency. |
comercioDolar | This option determines the Business to which VTOL (Branch) belongs for transactions in dollars currency. |
timeOut | The maximum time the POS waits for a response to a message sent to Transbank. This time is given in seconds and, by default, it must have a value of 20 (twenty seconds). |
timeOut4Digitos | This is the time period that the application waits for the entry of the last four digits of the PAN. If it is not entered, the application displays a TimeOut message. |
maxCuotasN | This value reflects the maximum amount for installments that the application will show at the time of the card sale. |
panManual | In this parameter you choose whether or not to request the entry of the card number manually. |
venta | Enables or disables the Sale transaction. By default, this transaction must be enabled. Values: Y = SALE enabled N = Does not allow Sale |
anulacion | Enables or disables the Void transaction. By default, this transaction must be enabled. Values: Y = Void enabled N = Does not allow Void |
6.3 Voucher Parameters
This section details the information that travels in the voucherParameters requirement field of an authorization message.
As mentioned, the parameters travel in a composite field, with the following format:
[key1|value1, key2|value2,..., keyN|valueN]
The possible keys and the details of the values of each key are described below:
Key | Value Detail |
pageWidth | Voucher width in characters. The default value is ’40’. |
pageMaxLength | Voucher length. The default value is ’-1’. |
copyCount | Number of slips to be issued. The default value is ‘1’ and corresponds to the original voucher. 2 corresponds to the issuance of the original voucher and the copy and 3 corresponds to the issuance of the original voucher, the copy and the triplicate. |
outputType | Output format. The default, valid value is ’txt’. |
configurationClass | Additional configuration that allows you to choose the output voucher format Supported values: - ’default’, default value - ’v18’, corresponding to the format specified in the TBK version 1.8 manual - ‘v2’, corresponding to the unique Voucher format specified by Transbank |
reprintCopyCount | Number of slips to be reprinted. The default value is ‘1’ and corresponds to the reprint of the original voucher. 2 corresponds to the reprint of the original voucher and the copy. |
6.4 Voucher Header
This section details the information that travels in the voucherHeader response field of an authorization message.
As mentioned, the configuration travels in a composite field, with the following format:
[key1|value1, key2|value2,..., keyN|valueN]
The possible keys and the details of the values of each key are described below:
| Key | Value Detail |
| nombreComercio | Business name. Corresponds to the encab1 value of the configuration. |
| direccionComercio | Business address. Corresponds to the encab2 value of the configuration. |
ciudadComercio | City where the business is located. Corresponds to encab3 value of the configuration. |
nombreEECC | EECC Business name. |
codigoEECC | EECC Business code. |
versionApp | Application version. |
6.5 Voucher Footer
This section details the information that travels in the voucherFooter response field of an authorization message.
As mentioned, the configuration travels in a composite field, with the following format:
[key1|value1, key2|value2,..., keyN|valueN]
The possible keys and the details of the values of each key are described below:
Key | Value Detail |
nombrePromocion | Name of the promotion in the case of an awarded transaction. |
plazoCuota | Term of the installment. |
nombreCliente | Name of cardholder. |
glosaTrxAfectaAhorro | Gloss transaction affects savings. |
pie1 | Configurable gloss by business. |
pie2 | Configurable gloss by business. |
pie3 | Configurable gloss by business. |
pie4 | Configurable gloss by business. |
pie5 | Configurable gloss by business. |
pie6 | Configurable gloss by business. |
pie7 | Configurable gloss by business. |
pie8 | Configurable gloss by business. |
pie9 | Configurable gloss by business. |
pie10 | Configurable gloss by business. |
6.6 Voucher Body
This section details the information that travels in the voucherBody response field of an authorization message.
As mentioned, the configuration travels in a composite field, with the following format:
[key1|value1, key2|value2,..., keyN|valueN]
The possible keys and the details of the values of each key are described below:
Key | Value Detail |
fecha | Date of the transaction in DD/MM/YY format. |
hora | Time of the transaction in HH:MM:SS format. |
fechaContable | Accounting date for debit transaction in DD/MM/YY format. |
terminal | ID of the terminal where the transaction was performed. |
numeroTarjeta | Last 4 digits of the card. |
marcaTarjeta | Card brand. |
monto | Transaction amount without tips/donation/change. |
tipoCuotas | Possible values for types of installments are:
|
glosaTipoCuotas | Description of types of installments. |
montoCuota | Amount of each of the installments. |
montoCuotaDiferido1 | Amount of installment 1 if installment type is C2C or C3C. |
montoCuotaDiferido2 | Amount of installment 2 if installment type is C2C or C3C. |
montoCuotaDiferido3 | Amount of installment 3 if installment type is C3C. |
tasaInteres | The rate applied to the transaction. It is printed if flagImprimirTasa is true. |
empleado | Employee number. It is only sent if the terminal has the option to request an employee number. |
numeroOperacion | Corresponding to the transaction terminal. |
codigoAutorizacion | Authorization code assigned by Transbank. |
numeroUnico | Unique number assigned by the business. |
propinaDonacion | Tip amount, if enabled in the terminal. |
vuelto | The amount of the change. Only applies for debit card transactions. |
montoPremio | Amount of the award in the case of an awarded transaction. |
glosaValePremio | Award gloss in the case of an awarded transaction. |
cantidadCuotas | Number of installments. |
codigoPromocion | Promotion code. |
tipoTrxPremiada | Type of awarded transaction. |
textoValePremio | Text corresponding to the award. |
tipoPromocion | Type of promotion. |
numeroDoc | Document number. |
6.7 Voucher Format
This section details the information that travels in the formattedVoucher response field of an authorization message.
As mentioned, the format travels in a composite field, with the following format:
[key1|value1, key2|value2,..., keyN|valueN]
The possible keys and the details of the values of each key are described below:
Key | Value Detail |
original | Original voucher formatted in Base64. |
duplicate | Voucher copy formatted in Base64. |
triplicate | Triplicate voucher formatted in Base64. |
outputType | Output format indicated in the requirement. |
special | Special voucher formatted in Base64. Example: awarded transactions. |
6.8 Transactional Control
Transactional control allows the Emv Kit library to decide which action to take in a transaction-by-transaction basis. That is, whether to confirm or reverse it.
IMPORTANT: This type of control is recommended to avoid inconsistencies with transactions performed |
In order to activate this control, the POS must take into account all the points listed below
1- Send the active transactionalControl flag (value = 1) of the CreateSession operation.
2- Record each of the 24 – trxId fields returned by the Emv Kit library for Approved authorizations.
3- If another Card Read operation is sent within the same session, and the previous authorization was successfully processed in the POS, field 24 – lastTrxId must be included with the value returned by the Emv Kit library for said authorization.
4- In the CloseSession operation with the value of the closeSessionAction = CLOSE field, you must include the 1009 closeTrxIdList field, which contains a list of all trxId (field 24) of the authorizations that were successfully processed in the POS.