VTOL EMVKIT CL 1.2.X
1. Introducción
1.1 Acerca de este documento
El presente documento explica la manera de integrarse a la EMV KIT y de esta manera poder realizar autorizaciones de pagos con tarjetas de Crédito/Débito hacia Transbank.
Referencias:
- 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 Qué es la EMV KIT?
VTOL cuenta con una librería desarrollada en Java la cual provee las funciones necesarias para realizar autorizaciones de diversos tipos de transacciones, además de las transacciones de control propias y comunes a cualquier implementación de VTOL Server.
Para facilitar la integración con la aplicación POS, la librería permite configurar dispositivos para obtener los datos necesarios para generar los mensajes a VTOL.
La EMV KIT es una pieza de software que se inicia como servicio en el punto de venta. Se encargada de procesar las transacciones de pago con tarjeta de crédito/débito, capturando los datos del tarjeta habiente y enviando las autorización a VTOL Server. La comunicación con éste último es por medio de un protocolo propietario, denominado protocolo VTOL, implementado sobre TCP/IP.
Además, resuelve la interacción con el dispositivo pinpad provisto por Transbank, liberando de esta tarea al aplicativo punto de venta.
A su vez la librería es configurada de forma centralizada por medio de VTOL Server, quién concentra la configuración de completa. Para mayor información referirse al manual de usuario de VTOL Server.
1.3 Arquitectura de la Librería
Arquitectura general de la EMV KIT
Como se observa en la imagen, la EMV KIT se encarga de comunicarse con el PINPAD, desligando al aplicativo de punto de venta de dicha responsabilidad con el objetivo de simplificar la integración.
Esta librería se ejecutará de manera stand alone –autónoma– en el punto de venta, pudiendo iniciarse como servicio, transmitiendo una comunicación server TCP/IP capaz de interpretar el protocolo VTOL. El mismo protocolo es utilizado para comunicarse con VTOL Server.
La integración entre la aplicación de punto de venta y la EMV KIT será a través de la utilización de la librería cliente de VTOL, la que llamaremos librería cliente o librería liviana.
La aplicación de punto de venta solo debe incorporar esta librería liviana que le permitirá, mediante llamadas JAVA, construir los mensajes para comunicarse con la EMV KIT.
Arquitectura y Comunicación de la EMV KIT
En la imagen se observan ejemplos de tramas de requerimiento y de respuesta transmitidas por TCP IP entre la librería liviana y la EMV KIT. Los tipos de operaciones son los siguientes y se explayan en el apartado 4.2 Tipos de Operación:
- Creación de la sesión
- Lectura de los datos de la tarjeta
- Envío de una autorización
- Obtención de la configuración del POS
- Cierre de lotes
- Cierre de la sesión
1.4 Alcance
La EMV KIT tiene el siguiente alcance:
1- Capturar información de la tarjeta por medio del PINPAD
2- Soporte PINPAD Vx805 VISA/POSNET vía RS232 o USB
3- Facilitar los datos de tarjeta encriptados, los cuales solo podrán ser desencriptados por el HOST autorizador según corresponda
4- Facilitar el PAN enmascarado (solo visibles los últimos 4 dígitos)
5- Capturar el CVC por medio del PINPAD
6- Capturar la fecha de vencimiento por medio del PINPAD en caso de que el ingreso sea manual
7- Capturar el PIN por medio del PINPAD
8- Soportar modo de ingreso CHIP, BANDA y MANUAL
9- Suministrar la configuración de VTOL Server a la aplicación de punto de venta
10- Manejar contingencia entre PINPAD, caja y VTOL
11- Comunicación entre aplicativo punto de venta y VTOL Server
12- Resolver las reglas de negocio propias del PINPAD
13- Soporte de operaciones como venta y anulaciones de venta
14- Gestionar la mensajería con VTOL Server
Es responsabilidad de la aplicación de punto de ventas:
1- La ejecución de la operación necesaria
2- La confirmación de los últimos 4 dígitos de la tarjeta
3- Realizar el cálculo de las promociones
4- La confirmación del monto
5- Impresión del voucher y duplicado
1.5 Requisitos
A continuación, se listan los requisitos mínimos que requiere la EMV KIT para su correcto funcionamiento:
1.5.1 Plataformas Soportadas
- Windows 32/64 bits
- Linux 32/64 bits
1.5.2 Requerimientos de Hardware
- Memoria RAM: 64MB disponibles
- Procesador: 2 núcleos de 1.6GHZ o superior (sujeto a pruebas ya que hay dependencias de arquitecturas de hardware, por ejemplo, pudiera funcionar con 1 núcleo pero más potente)
- Capacidad de almacenamiento en disco rígido: Al menos 150MB
1.5.3 Requerimientos de Software
- Java Virtual Machine (JDK) oficial de Oracle 1.8.x o superior (32/64 bits acorde con el sistema operativo)
- Conexión a VTOL Server por red TCP/IP
2. Funcional
2.1 Explicación General
La EMV KIT tiene la responsabilidad de abstraer a la aplicación de punto de venta de operaciones tales como el operar con el PINPAD, la comunicación y el procesamiento de transacciones con VTOL Server, el almacenamiento de información de transacciones, mantener la seguridad PCI, resolver contingencias, etc.
Para ello la librería suministra una serie de acciones que permiten operar con la misma, a saber:
- Inicio de sesión
- Envió de autorización o autorizaciones
- Cierre de sesión
En líneas generales, el orden de ejecución de cada llamada es similar al anteriormente mencionado.
Primero se inicia sesión, donde la EMV KIT carga la configuración desde VTOL, sincroniza el estado de las transacciones, verifica el funcionamiento del PINPAD, etc. Posteriormente se entra en un ciclo de llamadas para realizar las transacciones requeridas. Lo que se realiza tantas veces como tarjetas se utilicen para pagar la transacción. Finalmente se procede al cierre de sesión donde la EMV KIT confirma las transacciones contra el servidor VTOL.
Los tipos de transacciones soportadas son:
- Transacción de venta con tarjeta de crédito sin Interés (NCuotas – 3CSI, 2CSI)
- Transacción de venta con interés (aplicable para CIC, CICR, Venta Normal)
- Consulta de valor cuota
- Anulación de transacciones
- Transacción de débito
- Cierres
Para una mayor información sobre las transacciones referirse al documento:
“Manual de comandos pinpad Host to Host TRANSBANK - Comercio bajo protocolo SPDH 4.0 v2.9.pdf”
En los siguientes apartados, se explica en mayor detalle cada operación.
2.1.1 Procesamiento de Transacciones
A continuación se puede observar el modo de interacción genérico de la aplicación de venta con la EMV KIT:
1- Iniciar sesión con la EMV KIT.
2- La aplicación punto de venta envía la transacción a la librería para que sea autorizada.
3- Finalizados estos cálculos, la aplicación de punto de venta solicita el procesamiento de la transacción. En este punto la EMV KIT valida y solicita la trama SPDH a través del PINPAD. Si todo marcha bien, procede a la autorización con VTOL Server y este a su vez contra el autorizador Transbank.
4- Cuando arriba la respuesta desde VTOL, la librería almacena la transacción y le responde a la aplicación de punto de venta para que continúe con su lógica de negocio.
5- En caso de que se ingrese otro pago con tarjeta, se vuelve al paso 2 y así sucesivamente.
6- Una vez que finaliza el cobro de la transacción, el punto de venta cierra la sesión contra la EMV KIT, indicando si la misma finalizó con éxito o se debe cancelar. Para ambos casos, la librería se sincroniza con VTOL Server confirmando las transacciones cerradas o reversando las canceladas.
2.1.2 Inicio de Sesión con Reverso Pendiente
En el caso que la librería esté procesando un reverso, no está disponible para procesar una venta. En este caso se responderá con un error indicando este escenario.
3. Instalación
3.1 Procedimiento de Instalación
La instalación de la EMV KIT o EMV Kit se realiza gracias al uso de un instalador o asistente gráfico.
Mediante este asistente de instalación, también se instala el componente agente de la solución Director para que la EMV Kit pueda actualizarse remotamente.
Para ello se deben seguir los siguientes pasos:
- Iniciar sesión en el sistema operativo donde se instalará la EMV KIT con un usuario con permisos de administrador.
- Iniciar el instalador de la aplicación ejecutando la siguiente sentencia en la línea de comandos:
java –jar INSTALADOR.jar
Por ejemplo:
java –jar vtol-pos-client-lib-cl-installer-1.3.0.jar
Nota: Verificar tener seteada correctamente la variable JAVA_HOME. En caso de no tenerla, setearla a la carpeta de instalación de la JVM. Para esto verificar la carpeta de instalación, ejemplo: C:\Java\jdk1.8.0_25\. |
Al ejecutar esta sentencia, se descomprime el archivo.
3. Se presentará la pantalla de bienvenida del instalador. Presionar el botón “Siguiente”.
4. Al pasar a la siguiente pantalla, se mostrarán los términos y condiciones de uso de la aplicación de software para ser leídos y posteriormente aceptados para poder continuar con la instalación.
Presionar el botón “Aceptar”.
5. A continuación, se deberán aceptar los términos y condiciones de uso y completar los datos (nombre completo y correo electrónico) de quién acepta. Presionar el botón “Siguiente”.
Nota: Si no se aceptan los términos y condiciones de uso, la instalación no se completará. |
6. En la siguiente pantalla se deben ingresar las siguientes propiedades:
a. El directorio donde se encuentra Java
b. El directorio donde se desea instalar la EMV KIT
c. El código de la compañía, configurado en Director
d. El código de la tienda, configurado en Director
e. El código de la terminal de la tienda desde donde se operará, configurado en Director
f. La IP de VTOL Server para poder comunicarse
g. El puerto de VTOL Server
- Por defecto 3003 (con SSL)
h. La IP donde se comunica EMV Kit
- Por defecto localhost
i. El puerto donde se vincula EMV Kit
- Por defecto 3500
j. Y, por último, establecer si se desea actualizar EMV Kit remotamente gracias a Director.
Al habilitar el componente checkbox, se ofrecerá completar las propiedades de la pantalla del punto 7. Si no se habilita el componente checkbox, se ofrecerá la pantalla del punto 8.
Presionar el botón “Siguiente”.
En caso de que el directorio donde se desea instalar EMV Kit no exista, se ofrecerá crearlo. Presionar el botón “Sí” para ello.
7. Esta pantalla se brindará cuando se haya habilitado el componente checkbox “Actualizable Remotamente” del punto anterior.
Se deberá ingresar la siguiente información:
- La IP para comunicarse con Director
- El puerto para comunicarse con Director
- Por defecto 8490
- El puerto donde escucha el componente agente de Director
- Por defecto 5000
Oprimir el botón “Siguiente”.
8. Indicar el puerto para el pinpad y seleccionar mediante el desplegable el driver del pinpad.
Presionar “Siguiente”.
9. Presionar “Instalar” para que se ejecute la instalación.
Se podrá observar información detallada de la instalación presionando el botón “Enseñar detalles”. Al hacer esto se mostrarán dos solapas:
- En la solapa “Salida” podrá observar el progreso de la instalación visualizando las tareas ejecutadas por el instalador
- En la solapa “Errores” se presentan las fallas que tuvieron lugar durante la instalación
10. La finalización de la instalación se informa mediante un mensaje de “Terminado”.
Oprimir “Aceptar”.
11. Presionar el botón “Salir” para salir del instalador.
3.2 Servicios Instalados
Finalmente, La EMV KIT queda funcionando como un servicio junto con el componente agente de Director:
Donde:
- EmvKit: Servicio de la EMV KIT
- EmvKitDirectorService: Servicio del componente agente de Director correspondiente a la EMV KIT
3.3 Directorios Instalados
Dentro del directorio de la instalación (especificado en el punto 6) se encuentra la versión instalada de la EMV KIT con la siguiente estructura de directorios:
Carpeta / Archivo | Descripción |
backup | Directorio que persistirá los últimos cinco backups de archivos de las versiones instaladas de la solución EMV Kit durante la tarea de instalación |
emvkit | Contiene todos los archivos requeridos para el funcionamiento del EMV Kit |
sdagent | Contiene los archivos del componente agente de Director (configuración, binarios y registros) |
sdagentcmds | Contiene losarchivos para iniciar/detener/consultar el agente de Director de la solución EMV Kit |
tmp | Persiste los archivos de la versión a instalar de la solución EMV Kit durante la tarea de sincronización |
util | Contiene las utilidades para la creación de los servicios en Linux |
licenseAccepted.sts | Archivo de texto que menciona el nombre de usuario, el mail del usuario y la fecha que aceptó los términos y condiciones de uso |
nssm.exe | Aplicación encargada de construir los servicios EmvKit y EmvKitDirectorService para Windows |
Dentro de la carpeta “emvkit”, se obtiene la siguiente estructura de directorios:
Carpeta / Archivo | Descripción |
config | Contiene los archivos de configuración requeridos para la EMV KIT |
lib | Contiene todos los archivos JAR, propietarios y de terceros, requeridos para el funcionamiento de la EMV KIT |
start.cmd | Archivo de inicio de la aplicación como proceso de Windows |
start.sh | Archivo de inicio de la aplicación como proceso de Linux |
IMPORTANTE: La instalación mediante el asistente gráfico configurará la solución EMV Kit en su totalidad. En caso de que se precise configurar un archivo de forma manual, se deberá detener el servicio y efectuar el cambio en base a lo explicado en el apartado “Configuración”, |
4. Configuración
La EMV KIT cuenta con los siguientes archivos de configuración:
4.1 Opciones de configuración JAVA
Para que la EMV KIT funcione correctamente se deben configurar los siguientes parámetros (el archivo start.cmd ya trae una configuración por defecto):
Parámetros | Descripción |
-DLIB_BIND_ADDRESS | Dirección IP en la cual la librería recibirá y enviará los mensajes al punto de venta. Si no se menciona esta propiedad, el bind por defecto es 127.0.0.1 |
-DBASE_CONF_DIR | Directorio absoluto de la configuración de la librería |
-DLOG_DIR | Directorio absoluto de logeo de la aplicación. Esta variable es utilizada en el archivo de configuración de logeo (log4j.properties). Existe la posibilidad de prescindir de ésta variable. Para ello se debe especificar el valor absoluto en el archivo de configuración de logeo |
4.2 Archivos de configuración
La EMV KIT cuenta con los siguientes archivos de configuración:
Archivo | Descripción |
data\config.dat | Archivo creado y gestionado por la librería. Se utiliza para persistir la configuración de TBK en VTOL |
auditTransaction.obj | Archivo con auditoría de las transacciones de la sesión de la librería |
business.properties | Archivo que contiene configuración relativa a reglas de negocio |
devices.properties | Archivo de configuración de controllers y drivers del pinpad. Uso interno de la librería. No se debe modificar |
log4j.properties | Configuración de logeo de la librería |
logging.properties | Configuración de logeo de la librería |
serialPinPad.properties | Configuración del dispositivo pinpad |
session.obj | Archivo que registra información de estado y transaccional de la última sesión que el POS estableció con la EMV KIT |
synthesis.keystore | Archivo que almacena claves y certificados de la librería |
vtolClient.properties | Contiene las propiedades de conexión con VTOL Server |
4.3 Configuración de logeo
La EMV KIT logea según las directivas que se encuentran dentro del archivo de configuración de logeo log4j.properties.
A continuación se describen las opciones de configuración más importantes:
Propiedad | Descripción |
log4j.appender.file.File | Ruta y nombre del archivo de salida de logeo |
log4j.appender.file.MaxFileSize | Tamaño máximo del archivo de logeo antes de hacer el “rolling” (cambio a otro archivo de logeo) |
log4j.appender.file.MaxBackupIndex | Máxima cantidad de archivos de logs que se conservarán |
4.4 Configuración de enlace con VTOL
La EMV KIT se comunica con VTOL Server y las propiedades de enlace se encuentran en el archivo de configuración vtolClient.properties.
Propiedad | Descripción |
HOSTIP | IP o nombre del servidor donde se encuentra ubicado VTOL Server |
HOSTPORT | Puerto de comunicación con VTOL Server |
4.5 Configuración de PINPAD
La EMV KIT se conecta al PINPAD de Transbank.
Para lograr dicha conexión se debe configurar adecuadamente el puerto de comunicación COM donde está conectado el PINPAD.
Por ejemplo, si el puerto habilitado para trabajar con el PINPAD es el COM 9, debemos ingresar en el archivo serialPinPad.properties la siguiente información:
Propiedad | Descripción | Valor por defecto |
portName | Nombre del puerto | COM9 |
dataBits | Data bits length | 8 |
stopBits | 1 | |
baudRate | Baud rate of serial port | 19200 |
parity | Paridad | 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 don't enter PIN during this milliseconds, then a packet 72 should be sent to PINPad to cancel PIN entry. | 180000 |
bufferSize | Tamaño máximo del buffer de lectura del puerto serie. | 2048 |
nativeImpleClass | Clase de driver nativo para comunicarse con el PINPad. |
Ejemplo:
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.RxTxSimpleSerialNativeLibWrapperImpl
#PPVX805TBK.nativeImpleClass=cl.com.synthesis.vtol.clientTbk.test.pinpad.TransbankVX8xxPinpadEmulatorConnector
4.6 Configuración de business
La EMV KIT permite configurar ciertas propiedades en determinadas operaciones en el archivo business.properties.
Propiedad | Descripción | Valor por defecto |
ServiceApiBridge.responsePosTimeOut | Tiempo que debe transcurrir hasta que la EMV KIT responda TimeOut al POS | 60000 |
CloseSessionOperation.trxIdListRequired | Flag que activa la validación de que el campo closeTrxIdList(1009) sea requerido en el momento de que el POS realice Close Session | true |
Ejemplo:
ServiceApiBridge.responsePosTimeOut=60000
CloseSessionOperation.trxIdListRequired=true
5. Integración
Como se mencionó anteriormente, la EMV KIT corre como una aplicación stand alone en el POS, independiente de la aplicación de punto de venta, publicando un puerto de comunicación server TCP/IP, capaz de interpretar mensajes del protocolo VTOL (mismo protocolo de comunicación utilizado por VTOL Server).
La integración con la aplicación de punto de venta se realizará a través de la librería cliente liviana de VTOL la cual brinda todo el mecanismo de comunicación con la EMV KIT, permitiendo enviar y recibir mensajes del protocolo VTOL. La aplicación punto de venta básicamente deberá indicar cuáles son los campos a enviar y, luego, procesar la respuesta.
5.1 Integración del Servicio
Para poder realizar las llamadas hacia la EMV KIT, es necesario que la aplicación punto de venta integre la librería cliente, también llamada “liviana”:
La misma está disponible en 2 versiones:
- JAVA
- .NET
El uso de cada una dependerá del lenguaje de programación de la aplicación de punto de venta o del sistema integrador.
Para mayor información referirse a la documentación de la librería liviana.
5.2 Tipos de Operación
La EMV KIT reconoce los siguientes tipos de operaciones:
A. Crear Sesión
Es la primera operación a ejecutar por parte de la aplicación punto de venta cuando se inicia una transacción de pago.
Permite iniciar sesión entre la aplicación de punto de venta y la EMV KIT.
Internamente la librería verifica la conectividad con el PINPAD y se sincroniza con VTOL Server.
A continuación se detallan los campos que la aplicación punto de venta debe enviar a la EMV KIT, haciendo uso de la librería cliente.
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
1025 | transactionalControl | Alfanumérico | Opcional | Campo opcional del tipo flag. Este campo activo indica que se deben realizar un control transacción a transacción, para decidir qué acción tomar sobre la última transacción procesada en la librería (confirmarla o reversarla). Valores posibles: 0: Control desactivado 1: Control activado Por defecto el control transacción esta desactivado, aunque se recomienda su utilización para evitar estados de inconsistencia. |
Ejemplo
Request to Full library: {2:1;1:1;11:createSession} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
1010 | currentSessionId | Numérico | Identificador de la nueva sesión |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo
Response from Full library: {1:1;2:1;1010:1463407572364;1027:000;1028:Ok} |
B. Leer Tarjeta
Luego de que la aplicación de punto de venta haya abierto la sesión exitosamente de la EMV KIT, se lee la tarjeta para iniciar el pago.
A continuación se detallan los requerimientos y las respuestas para esta operación:
Venta
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | Monto de la transacción. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
13 | currency | Alfanumérico | Obligatorio | Tipos de Moneda:
|
24 | lastTrxId | Numérico | Opcional | Utilizado cuando está activo el control transaccional. En este campo el POS debe enviar la última transacción procesada correctamente (Si el POS tuvo algún problema con la transacción previa no debería enviar su trxId en este campo). |
25 | dateTime | Numérico | Opcional | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
101 | cardType | Alfanumérico | Obligatorio | Tipo de tarjeta, valores permitidos:
|
104 | tipAmount | Importe | Opcional | Monto propina o donación |
107 | cashbackAmount | Importe | Opcional | Monto vuelto |
1111 | cashbackList | Alfanumérico | Opcional | Lista de vueltos permitidos separados por coma |
Ejemplo
Request to Full library: {107:0;13:$;104:0;12:12750000;11:Sale;13:$;101:CR;1111:100000,500000,1000000,2000000,;2:1;25:20160516110614;1:1} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
8 | bin | Numérico | Informa los primeros 6 dígitos de la tarjeta |
25 | dateTime | Numérico | [Opcional: Si viaja en el requerimiento] Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
101 | cardType | Alfanumérico | Tipo de tarjeta, valores permitidos:
|
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1102 | provider | Alfanumérico | Abreviación de la tarjeta. Ejemplo VI = VISA, MC = MASTERCARD, etc. |
1103 | cardContextId | Alfanumérico | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. Debe ser enviado en la siguiente llamada “Enviar autorización” |
1110 | requireLastFourDigits | Numérico | [Opcional si la Trx fue aprobada] Indica si el POS debe enviar los últimos 4 dígitos de la tarjeta en el mensaje de Autorización de Venta. Valores posibles:
|
Ejemplo
Response from Full library: {1:1;1102:CR;2:1;1103:20160516110619911;6:7787;8:450799;25:20160516110614;1010:1463407572364;1110:1;1027:000;1028:Ok} |
Anulación de Venta
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Opcional | Monto a validar de la transacción. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
13 | currency | Alfanumérico | Obligatorio | Tipos de Moneda:
|
24 | lastTrxId | Numérico | Opcional | Utilizado cuando está activo el control transaccional. En este campo el POS debe enviar la última transacción procesada correctamente (Si el POS tuvo algún problema con la transacción previa no debería enviar su trxId en este campo). |
25 | dateTime | Numérico | Opcional | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
100 | uniqueNumber | Numérico | Obligatorio | Identificador único de operación de Venta. Longitud 26 |
101 | cardType | Alfanumérico | Obligatorio | Tipo de tarjeta, valores permitidos:
|
Ejemplo
Request to Full library: {25:20160516110634;101:CR;2:1;100:00000001000001160516110624;1:1;11:VoidSale;13:$} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
8 | bin | Numérico | Informa los primeros 6 dígitos de la tarjeta |
25 | dateTime | Numérico | [Opcional: Si viaja en el requerimiento] Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
101 | cardType | Alfanumérico | Tipo de tarjeta, valores permitidos:
|
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1102 | provider | Alfanumérico | Abreviación de la tarjeta. Ejemplo VI = VISA, MC = MASTERCARD, etc. |
1103 | cardContextId | Alfanumérico | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. Debe ser enviado en la siguiente llamada “Enviar autorización” |
1110 | requireLastFourDigits | Numérico | [Opcional si la Trx fue aprobada] Indica si el POS debe enviar los últimos 4 dígitos de la tarjeta en el mensaje de Autorización de Venta. Valores posibles:
|
Ejemplo
Response from Full library: {1:1;1102:CR;2:1;1103:20160516110638744;8:450799;25:20160516110634;1010:1463407572364;1110:1;1027:000;1028:Ok} |
C. Enviar Autorización
Tras la lectura de la tarjeta y la confirmación del POS, se procede enviar operaciones de autorización, entre las cuales se encuentran la Venta y la Anulación de la venta.
A continuación se describen los requerimientos y respuestas para estas operaciones:
Venta
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
6 | lastFourDigits | Numérico | Obligatorio | Últimos 4 dígitos de la tarjeta retornados en la venta original |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | Monto de la transacción. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
14 | payments | Numérico | Opcional | Cantidad de cuotas |
25 | dateTime | Numérico | Opcional | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
29 | serialNumber | Alfanumérico | Opcional | Número de serie que identifica la terminal. Si el POS envía este valor, será utilizado para enviar al autorizador. |
30 | businessNumber | Alfanumérico | Opcional | Código de comercio. Si el POS envía este valor, será utilizado para enviar al autorizador |
103 | paymentsAmount | Importe | Opcional | Monto de las cuotas |
108 | ticket | Alfanumérico | Obligatorio | Número de ticket |
1101 | product | Numérico | Opcional | Código de producto |
1103 | cardContextId | Alfanumérico | Obligatorio | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. Es el valor devuelto por la última operación “Leer Tarjeta” |
1118 | voucherParameters | Mapa | Opcional | Envía los parámetros y formatos del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1,clave2|valor2,…,claveN|valorN] Ver sección Parámetros del Voucher |
Ejemplo
Request to Full library: {1103:20160516110619911;108:10;13:$;12:12050000;11:Sale;30:597040000902;6:7787;29:S4SYNTHESIS00002;2:1;25:20160516110622;1:1} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
24 | trxId | Numérico | Identificador único de transacción. En caso de que la respuesta de la transacción sea recibida y procesada correctamente por el POS, este ID debe incluirse en el campo 24 de la próxima operación de Lectura de Tarjeta. |
25 | dateTime | Numérico | [Opcional: Si viaja en el requerimiento] Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 3 dígitos como máximo.
|
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
100 | uniqueNumber | Numérico | Identificador único de operación de Venta. Longitud 26 |
111 | graceMonth | Numérico | Indica si tiene mes de gracia. Valores posibles:
|
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1102 | provider | Alfanumérico | Abreviación de la tarjeta. Ejemplo VI = VISA, MC = MASTERCARD, etc. |
1105 | awardedTrx | Numérico | [Opcional si la Trx fue aprobada] Indica si la transacción fue premiada. Valores posibles:
|
1106 | awaredTrxMsg | Alfanumérico | Opcional si la Trx fue aprobada y premiada]. Mensaje indicando que la transacción fue premiada. |
1107 | trxWithPIN | Numérico | [Opcional si la Trx fue aprobada] Indica si la transacción con PIN. Valores posibles:
|
1108 | printInterestTax | Numérico | [Opcional si la Trx fue aprobada] Indica si debe imprimir la tasa de interés. Valores posibles:
|
1109 | voucherType | Numérico | [Opcional si la Trx fue aprobada] Indica el tipo de voucher. Valores posibles:
|
1120 | voucherHeader | Mapa | [Opcional 1] Retorna los datos del encabezado del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Encabezado del Voucher |
1121 | voucherFooter | Mapa | [Opcional 1] Retorna los datos del pie del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Pie del Voucher |
1122 | voucherBody | Mapa | [Opcional 1] Retorna el cuerpo del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Cuerpo del Voucher |
1123 | formattedVoucher | Mapa | [Opcional 2] Retorna el voucher completo y formateado para ser impreso. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Formato del Voucher |
1124 | printVoucher | Numérico | [Opcional 3] Reservado para uso futuro. Indica si la impresión del voucher tuvo éxito o no. Valores permitidos:
|
1129 | rePrintFormattedVoucher | Mapa | [Opcional 2] Retorna el voucher completo con el formato para la reimpresión. El valor recibido corresponde a un campo compuesto mapa con una clave (original) y su valor en base64. [clave1|valor1] Ver sección Formato del Voucher |
Campos opcionales:
[Opcional 1]: Cuando la autorización fue aprobada y la librería retorna los datos del Voucher separados en encabezado, Cuerpo y pie.
[Opcional 2]: Cuando la autorización fue aprobada y la librería retorna en un solo campo el Voucher formateado.
[Opcional 3]: Cuando la autorización fue aprobada y la librería se encarga de imprimir el Voucher. No implementado, reservado para uso futuro.
Ejemplo
Response from Full library: {1:1;2:1;100:00000001000001160516110624;1103:20160516110619911;6:7787;111:0;1010: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,montoCuotaDiferido3|0,marcaTarjeta|CR,montoPremio|120.500,hora|11:06:26,propinaDonacion|0,numeroTarjeta|7787,glosaTipoCuotas|SIN CUOTAS,terminal|S4SYNTHESIS00002,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} |
Anulación de Venta
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
6 | lastFourDigits | Numérico | Obligatorio | Últimos 4 dígitos de la tarjeta retornados en la venta original |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Opcional | Monto a validar de la transacción. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
25 | dateTime | Numérico | Opcional | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
29 | serialNumber | Alfanumérico | Opcional | Número de serie que identifica la terminal. Si el POS envía este valor, será utilizado para enviar al autorizador |
30 | businessNumber | Alfanumérico | Opcional | Código de comercio. Si el POS envía este valor, será utilizado para enviar al autorizador |
100 | uniqueNumber | Numérico | Obligatorio | Identificador único de operación de Venta Original. Longitud 26 |
108 | ticket | Alfanumérico | Opcional | Número de ticket |
1103 | cardContextId | Alfanumérico | Obligatorio | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. Es el valor devuelto por la última operación “Leer Tarjeta” |
1118 | voucherParameters | Mapa | Opcional | Envía los parámetros y formatos del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1,clave2|valor2,…,claveN|valorN] Ver sección Parámetros del Voucher |
Ejemplo
Request to Full library: {6:7787;1103:20160516110638744;25:20160516110642;101:CR;2:1;100:00000001000001160516110624;1:1;11:VoidSale;29:S4SYNTHESIS00002;30:597040000902} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
24 | trxId | Numérico | Identificador único de transacción. En caso de que la respuesta de la transacción sea recibida y procesada correctamente por el POS, este ID debe incluirse en el campo 24 de la próxima operación de Lectura de Tarjeta. |
25 | dateTime | Numérico | [Opcional: Si viaja en el requerimiento] Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 3 dígitos como máximo.
|
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
100 | uniqueNumber | Numérico | Identificador único de operación de Anulación. Longitud 26 |
111 | graceMonth | Numérico | Indica si tiene mes de gracia. Valores posibles:
|
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1105 | awardedTrx | Numérico | [Opcional si la Trx fue aprobada] Indica si la transacción fue premiada. Valores posibles:
|
1106 | awaredTrxMsg | Alfanumérico | [Opcional si la Trx fue aprobada y premiada]. Mensaje indicando que la transacción fue premiada. |
1107 | trxWithPIN | Numérico | [Opcional si la Trx fue aprobada] Indica si la transacción con PIN. Valores posibles:
|
1108 | printInterestTax | Numérico | [Opcional si la Trx fue aprobada] Indica si debe imprimir la tasa de interés. Valores posibles:
|
1109 | voucherType | Numérico | [Opcional si la Trx fue aprobada] Indica el tipo de voucher. Valores posibles:
|
1120 | voucherHeader | Mapa | [Opcional 1] Retorna el encabezado del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Encabezado del Voucher |
1121 | voucherFooter | Mapa | [Opcional 1] Retorna el pie del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Pie del Voucher |
1122 | voucherBody | Mapa | [Opcional 1] Retorna el cuerpo del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Cuerpo del Voucher |
1123 | formattedVoucher | Mapa | [Opcional 2] Retorna el voucher completo y formateado para ser impreso. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Formato del Voucher |
1124 | printVoucher | Numérico | [Opcional 3] Reservado para uso futuro. Indica si la impresión del voucher tuvo éxito o no. Valores permitidos:
|
1129 | rePrintFormattedVoucher | Mapa | [Opcional 2] Retorna el voucher completo con el formato para la reimpresión. El valor recibido corresponde a un campo compuesto mapa con una clave (original) y su valor en base64. [clave1|valor1] Ver sección Formato del Voucher |
Campos opcionales:
[Opcional 1]: Cuando la autorización fue aprobada y la librería retorna los datos del Voucher separados en encabezado, Cuerpo y pie.
[Opcional 2]: Cuando la autorización fue aprobada y la librería retorna en un solo campo el Voucher formateado.
[Opcional 3]: Cuando la autorización fue aprobada y la librería se encarga de imprimir el Voucher. No implementado, reservado para uso futuro.
Ejemplo
Response from Full 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,montoCuotaDiferido3|0,marcaTarjeta|CR,montoPremio|120.500,hora|11:06:46,propinaDonacion|0,numeroTarjeta|7787,glosaTipoCuotas|SIN CUOTAS,terminal|S4SYNTHESIS00002,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} |
IMPORTANTE: La aplicación punto de venta debe tener la capacidad de registrar los distintos trxId que recibe en las sucesivas autorizaciones APROBADAS, dentro de la sesión debido a que debe enviarlas al momento de cerrar la sesión para confirmarlas con VTOL Server. |
D. Operaciones OnUs
En las transacciones OnUs, Transbank no opera como el autorizador sino que el mismo cliente posee su sistema de autorización.
En esta modalidad, no es necesario previamente efectuar la operatoria de la librería de “Leer Tarjeta”.
Las operaciones OnUs disponibles son la Venta y la Validación de Criptograma. A continuación se describen los requerimientos y respuestas para estas operaciones:
Venta
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | Monto de la transacción. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
13 | currency | Alfanumérico | Obligatorio | Tipos de Moneda:
|
14 | payments | Numérico | Opcional | Cantidad de cuotas |
25 | dateTime | Numérico | Opcional | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
103 | paymentsAmount | Importe | Opcional | Monto de las cuotas |
107 | cashbackAmount | Importe | Opcional | Monto vuelto |
1111 | cashbackList | Alfanumérico | Opcional | Lista de vueltos permitidos separados por coma |
1130 | workingKeyPin | Alfanumérico | Obligatorio | Working key para encriptar el PIN para la operacion OnUs |
1131 | commercialMessage | Alfanumérico | Obligatorio | Mensaje comercial informado por el POS o comercio OnUs |
Ejemplo
Request to Full library: {107:0;14:3;13:$;12:50000;103:933000;11:SaleOnUs;1111:100000,500000,1000000,2000000,;1131:***TARJETA COMERCIAL***;1130:70512FD35034DDC897710CA3334E4CF3;2:2;25:20170824102251;1:1} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción | |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción | |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción | |
6 | lastFourDigits | Numérico | Informa los últimos 4 dígitos de la tarjeta | |
8 | bin | Numérico | Informa los primeros 6 dígitos de la tarjeta | |
9 | track2 | Alfanumérico | Track2 de la tarjeta | |
10 | inputMode | Alfanumérico | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
| |
25 | dateTime | Numérico | [Opcional: Si viaja en el requerimiento] Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS | |
56 | pinBlock | Alfanumérico | Pin block de largo 16 | |
1010 | currentSessionId | Numérico | Identificador de la sesión actual | |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería | |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería | |
1102 | provider | Alfanumérico | Abreviación de la tarjeta. Ejemplo VI = VISA, MC = MASTERCARD, etc. | |
1103 | cardContextId | Alfanumérico | Identifica el contexto de la tarjeta | |
1112 | cardHolderName | Alfanumérico | Nombre del titular de la tarjeta | |
1135 | cryptogram | Alfanumérico | Criptograma | |
1136 | track1 | Alfanumérico | Track1 de la tarjeta | |
1137 | completePinpadResponse | Alfanumérico | Trama de la respuesta del Pin Pad del comando 0810 | |
1138 | cardName | Alfanumérico | Nombre de marca de tarjeta. Ejemplo: VISA, MASTERCARD, MAESTRO, AMEX, etc. | |
Ejemplo
Response from Full library: {1:1;2:2;1027:000;1028:Ok;6:7777;8:789348;9:89797987;10:00;1102:VI;1103:2017082411560639;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|} |
Validación de Criptograma
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
25 | dateTime | Numérico | Opcional | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
1103 | cardContextId | Alfanumérico | Obligatorio | Identifica el contexto de la tarjeta |
1132 | glosaScreenResponse | Alfanumérico | Opcional | Glosa respuesta pantalla |
1133 | glosaResponse | Alfanumérico | Obligatorio | Glosa de respuesta |
1135 | cryptogram | Alfanumérico | Obligatorio | Criptograma |
Ejemplo
Request to Full library: {1132:Glosa respuesta PANTALLA;1103:2017082411590639;25:20170824122329;1135:1232343223;2:2;1:1;1133:Glosa respuesta PINPAD;11:ValidateSaleOnUs} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
25 | dateTime | Numérico | [Opcional: Si viaja en el requerimiento] Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1133 | glosaResponse | Alfanumérico | Glosa de respuesta |
Ejemplo
Response from Full library: {1:1;2:2;1010:1503585583959;1027:000;1028:Ok;25:20170824122329;1133:Glosa Respuesta} |
E. Consultar Transacción de Venta
A través de este mensaje se pueden obtener los datos relacionados a una venta original.
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
100 | uniqueNumber | Numérico | Obligatorio | Identificador único de operación de Venta. Longitud 26 |
Ejemplo
Request to Full library: {2:1;100:00000001000002290817114534;1:1;11:GetOriginalSale} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
6 | lastFourDigits | Numérico | Informa los últimos 4 dígitos de la tarjeta |
8 | bin | Numérico | Informa los primeros 6 dígitos de la tarjeta |
12 | amount | Importe | Monto de la transacción. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
13 | currencyPosCode | Alfanumérico | Tipo de Moneda:
|
14 | payments | Numérico | Numero de cuotas. 2 dígitos como máximo. |
38 | authorizationNumber | Numérico | Código de autorización generado por el centro autorizador para la transacción de venta |
101 | cardType | Alfanumérico | Tipo de tarjeta, valores permitidos:
|
102 | paymentsType | Numérico | Tipo Cuotas "0" : sin cuotas "1" : cuotas normales "3" : 3 cuotas contado "4" : cuotas comercio “5” : n-cuotas |
103 | paymentsAmount | Numérico | Monto de las cuotas |
104 | tipAmount | Numérico | Monto propina / donación |
106 | sequenceNumber | Numérico | Numero de secuencia del venta |
108 | ticket | Alfanumérico | Número de ticket |
120 | originalDate | Numérico | Fecha y hora de realización de la transacción de Venta original. Formato YYYYMMDDHHMMSS |
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1128 | voidAmount | Importe | Monto anulado de la transacción venta original. 18 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
Ejemplo
Response from Full 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:1504195178743;120:20170829114536;6:7787} |
F. Obtener Configuración POS
Este mensaje le permite al punto de venta obtener la configuración de Transbank existente en VTOL Server. Se debe ejecutar luego de crear una sesión exitosa con la EMV KIT.
La configuración es administrada a través de la consola Web de VTOL.
A continuación se detallan los campos que la aplicación punto de venta debe enviar a la EMV KIT, haciendo uso de la librería cliente.
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
Ejemplo
Request to Full library: {2:1;1:1;11:getConfiguration} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
113 | confParameters | Mapa | Configuración de POS recibida desde VTOL server. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valores: [clave1|valor1, clave2|valor2,…, claveN|valorN] Ver sección Formato Configuración POS |
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo
Response from Full 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|S4SYNTHESIS00002,baudiosPinPad|9600,timeOut4Digitos|0,pie3|Acepto Pagar según contrato con?,pie2|Original Comercio - Copia Cliente,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,montoVuelto3|10000,encab1|Nombre Comercio,montoVuelto2|5000,encab2|Direccion Comercio,montoVuelto1|1000];2:1;1:1} |
G. Cierre de Lotes
Esta operación permite al punto de venta intercambiar totales con el Host de Transbank.
Debe realizarse dentro de una sesión activa con la EMV KIT.
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
13 | currency | Alfanumérico | Obligatorio | Tipos de Moneda:
|
29 | serialNumber | Alfanumérico | Opcional | Número de serie que identifica la terminal. Si el POS envía este valor, será utilizado para enviar al autorizador. |
30 | businessNumber | Alfanumérico | Opcional | Código de comercio. Si el POS envía este valor, será utilizado para enviar al autorizador. |
Ejemplo
Request to Full library: {2:1;1:1;11:Close;13:$;29:S4SYNTHESIS00002; 30:597040000902} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo.
|
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
1010 | currentSessionId | Numérico | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
1125 | saleTrxQuantity | Alfanumérico | Cantidad transacciones de venta |
1126 | saleTrxAmount | Numérico | Monto transacciones de venta |
1127 | voidTrxQuantity | Numérico | Cantidad transacciones de anulación |
1128 | voidTrxAmount | Numérico | Monto transacciones de anulación |
Ejemplo
Response from Full 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. Cerrar Sesión
Permite cerrar la sesión entre la aplicación de punto de venta y la EMV KIT.
Internamente la EMV KIT se sincroniza con VTOL Server, confirmando o cancelando las transacciones procesadas dentro de la sesión.
IMPORTANTE: Es importante que una vez finalizada la transacción de pago en la aplicación de punto de venta se realice el cierre de la sesión con la EMV KIT, indicando si se debe confirmar o reversar las autorizaciones realizadas. |
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
1008 | closeSessionAction | Alfanumérico | Obligatorio | Acción que se debe realizar sobre el cierre de sesión:
|
1009 | closeTrxIdList | Lista | Obligatorio. Solo cuando el campo 1008 es igual a CLOSE | Lista de los trxId (campo 24) recibidos en la respuestas a las distintas llamadas “Enviar autorización” |
250 | actionCode | Alfanumérico | Obligatorio cuando el campo 1008 es igual a FORCED_CLOSE | Identificación del motivo por el cual la sesión tuvo un cierre forzado. Código de 5 caracteres. Valores posibles:
|
251 | actionNote | Alfanumérico | Opcional | Motivo informado por el punto de venta cuando la sesión tuvo un cierre no tradicional. Máximo de 50 caracteres |
Ejemplo
Request to Full library: {1008:CLOSE;2:1;1:1;11:closeSession} |
Es importante tener en cuenta que el campo closeSessionAction puede tomar uno de los siguientes valores:
- CLOSE: la sesión terminó correctamente, es decir, la aplicación de punto de venta finalizó la transacción de punto de venta correctamente
- CANCEL: la sesión no terminó correctamente, es decir, la aplicación de punto de venta NO finalizó correctamente la transacción de punto de venta debido a algún tipo de contingencia
- FORCED_CLOSE: la sesión no terminó correctamente, es decir, la aplicación de punto de venta NO finalizó correctamente la transacción de punto de venta y se forzó el cierre de la sesión. Por ejemplo, corte de luz, el cliente se marcha, errores en el punto de venta, etc
- Respuesta
Número | Nombre del campo | Tipo de dato | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
1010 | currentSessionId | Numérico | Identificador de la sesión que se cierra |
1027 | libResponseCode | Numérico | Código de respuesta de la librería. Indica cómo fue procesada la operación en la EMV KIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo
Response from Full library: {1:1;2:1;1010:1463407572364;1027:000;1028:Ok} |
5.3 Autorización Aprobada
Para determinar que una autorización fue aprobada es necesario:
- 1° verificar el campo
1027 | libResponseCode |
Si el valor es igual a 000, indica que la librería pudo enviar la solicitud a VTOL Server y procesar la respuesta sin problemas. Es el primer indicador de que todo va bien.
Un código distinto indica un error de procesamiento en la librería, que debe ser manejado.
- 2° verificar el campo isoCode
27 | isoCode |
En caso de que el valor sea igual 000 indica que la autorización ha sido Aprobada.
6. Anexos
6.1 Códigos de Respuesta de EMV KIT
El código de respuesta de la EMV KIT y su detalle se encuentran en los campos:
Código = campo 1027
Descripción = campo 1028
Código | Descripción | Significado |
UDF | INDEFINIDO | Corresponde al estado inicial de la variable de estado. La librería no debe devolver nunca este valor |
000 | Aprobado | Operación satisfactoria |
001 | Cancelado por el usuario | Se usó la tecla CANCEL del PINPAD |
002 | Error ingreso 4 últimos dígitos | El PINPAD detectó errores en el ingreso de los últimos 4 dígitos |
003 | Error de lectura Track2 | El PINPAD no pudo leer el Track II |
004 | Error Pinpad-ingreso PIN | No se ingresó correctamente el PIN en el PINPAD |
005 | Error Chip | El PINPAD no pudo leer o grabar en el CHIP |
006 | Error Fecha inválida | Se ingresó un fecha inválida en el PINPAD |
007 | Error TimeOut | El PINPAD suspendió la operación por TIMEOUT |
008 | Error en secuencia de comando recibido | El PINPAD rechazó un comando por estar fuera de secuencia |
009 | Error en formato de comando recibido | El PINPAD rechazó un comando por formato erróneo |
011 | Error de LRC de comando recibido | El PINPAD rechazó un comando por LRC erróneo |
086 | Error de Lectura | Error de lectura |
087 | Pinpad sin Master Key | El Pinpad no tiene Master Key |
088 | Tarjeta capturada no permite tratamiento OnUs | Tarjeta capturada no permite tratamiento OnUs |
089 | Transacción Declinada por la Tarjeta Chip | La transacción fue declinada por la tarjeta con chip |
090 | Tarjeta No Permitida para el Modo Seleccionado | No se permite la tarjeta con dicho modo |
091 | Error Cantidad de Cuotas | Error cantidad de cuotas |
092 | No Coincide con Tarjeta de Primer Tapeo | No coincide la tarjeta |
093 | Error de Monto Mínimo | Error de monto mínimo |
094 | Error de Validación Monto Vuelto | Error al validar el vuelto |
095 | Error ID de Contexto | Error ID de contexto |
096 | No Coinciden los 4 Ultimos Digitos | Los últimos 4 dígitos de la tarjeta no coinciden |
097 | La Transacción No Permite Reversa | La operación de reserva no se permite |
098 | Error de Formato del Mensaje | Error de formato en el mensaje |
099 | Cancelación del Comando a Través de la tecla [CANEL] / Timeout | Se canceló el comando |
100 | Pinpad no se encuentra conectado o no está disponible | El pinpad no está disponible |
101 | La sesion ya se encuentra creada. | No se puede crear una nueva sesión con la EMV KIT, debido a que ya existe una sesión activa. |
102 | La libreria esta procesando un requerimiento. | La EMV KIT se encuentra procesando un requerimiento. |
103 | La libreria esta procesando una respuesta. | La EMV KIT se encuentra procesando una respuesta a un requerimiento. |
104 | La libreria esta procesando un reverso. | La librería se encuentra procesando un reverso. |
600 | Campo monto es requerido | No se informó el campo monto, el cual es requerido para la operación. |
601 | Campo moneda requerido | No se informó el campo, el cual es requerido para la operación. |
602 | Campo tipo tarjeta requerido | No se informó el campo tipo de tarjeta, el cual es requerido para la operación. |
603 | Campo monto vuelto requerido | No se informó el campo monto de vuelto, el cual es requerido para la operación. |
604 | Campo monto propina requerido | No se informó el campo monto, el cual es requerido para la operación. |
605 | Campo últimos 4 dígitos requerido | No se informó el campo últimos 4 dígitos de la tarjeta, el cual es requerido para la operación. |
606 | Campo numero unico requerido | No se informó el campo número único, el cual es requerido para la operación |
699 | Faltan datos requeridos | No se informó un campo requerido para la operación, se debe consultar al administrador para identificarlo. |
700 | Numero Unico Invalido | Se informaron más de 26 dígitos. |
701 | Archivo de Sesión no existe | No existe el archivo que contiene la información de sesión |
702 | Existen Trxs Pendientes con VTOL Server | Existen Transacciones pendientes con VTOL que no se pueden cerrar |
703 | Estado de Sesión no es válido | El estado de la sesión es inválido |
704 | Tipo de Transacción es invalido | El tipo de transacción enviado en la llamada no es válido |
705 | Error enviando mensaje a VTOL Server | Error enviando autorización a VTOL Server |
706 | Lista de VTOL TrxIds no recibida (Cierre de Sesión) | Lista de VTOL TrxIds no recibida en el Cierre de Sesión con acción CLOSE |
707 | Monto inválido | El monto es inválido |
708 | Monto Cash Back inválido | El monto de cash back es inválido |
709 | Libreria enviando confirmación a VTOL | La librería envió la confirmación a VTOL Server |
710 | Imposible cancelar sesion. Existe un cierre de lote | No es posible cancelar la sesión porque hay un cierre de lote |
711 | Error cancelando sesion. Existen ventas sin anular | No es posible cancelar la sesión porque hay ventas sin anular |
712 | Monto anulado supera Venta | El monto a anular supera al monto de la venta |
713 | Transacción Inválida | La transacción no es válida |
714 | Venta ya fue anulada | La venta ya fue anulada previamente |
715 | Imposible anular Debito | No es posible anular débito |
716 | No existe venta original | La transacción consultada no existe |
717 | Tipo de moneda no corresponde | La moneda con la que se quiso anular la venta es distinta |
801 | PAN: proveedor desconocido | El proveedor es desconocido |
802 | PAN: dígito inválido | El dígito no es válido |
803 | Error en protocolo | Surgió un error en el protocolo |
804 | Error formato de mensajes | Surgió un error en el formato del mensaje |
805 | Error en configuracion de tarjetas | Surgió un error en la configuración de la tarjeta |
806 | Error llave RSA invalida o nula | La llave RSA es inválida o nula |
807 | Error WK nula o formato invalido | Error WK nula o formato invalido |
901 | Error del sistema (general) | Error interno de la librería |
902 | Error del sistema (I/O) | Error de entrada/salida o comunicación de la librería |
911 | Error del sistema (carga) | Error al cargar la librería |
912 | Error del sistema (contexto inexistente) | Error de contexto inexistente de la librería |
913 | Error del sistema (contexto inválido) | Error de contexto inválido de la librería |
914 | Error del sistema (carga working key) | Error al cargar la working key en la librería |
999 | Existe un error en la sesión | Existe un error en la sesion |
6.2 Formato Configuración POS
En esta sección se detalla la información que viaja en el campo de respuesta confParameters de un mensaje de solicitud de configuración, que se corresponde con la configuración generada para el POS en VTOL Server.
Como se mencionó la configuración viaja en un campo compuesto, con el siguiente formato:
[clave1|valor1, clave2|valor2,…, claveN|valorN]
A continuación se describen las posibles claves y el detalle del valor de cada una de ellas:
Clave | Detalle del Valor |
version | Versión de la aplicación. |
propina | Habilita / deshabilita el ingreso de una propina por transacción Valores Posibles: Y = Habilita el ingreso de PROPINA. N = No permite el ingreso de PROPINA. Por defecto este campo debe tener el valor N. |
pan | Hace referencia al número de la tarjeta de crédito. En este parámetro se puede activar o desactivar la solicitud de este dato al realizar la venta. |
cashBack | Habilita / deshabilita opción Cashback (Venta con vuelto) para las transacciones de Débito. Valores Posibles: Y = Habilita la opción de CASH-BACK (venta con vuelto) para las transacciones de Débito. N = No permite realizar ventas con vuelto en transacciones débito. Nota: Por defecto este campo debe tener el valor “N” |
montoVuelto1 | Permite definir el monto asociado a la opción de vuelto a la tarjeta habiente. Valor por defecto: 1000 |
montoVuelto2 | Permite definir el monto asociado a la opción de vuelto a la tarjeta habiente. Valor por defecto: 5000 |
montoVuelto3 | Permite definir el monto asociado a la opción de vuelto a la tarjeta habiente. Valor por defecto: 10000 |
montoVuelto4 | Permite definir el monto asociado a la opción de vuelto a la tarjeta habiente. Valor por defecto: 20000 |
encab1 | Nombre Comercio |
encab2 | Dirección Comercio |
encab3 | Ciudad Comercio |
encab4 | Código de Comercio - Versión APP |
pie1 | Gracias por su Compra |
pie2 | Original Comercio - Copia Cliente |
pie3 | Acepto Pagar según contrato con… |
pie4 | Acepto el cargo en mi tarjeta pagado… |
pie5 | en el número y monto de cuotas… |
pie6 | las que ya incluyen intereses |
pie7 | Operación sujeta a impuesto… |
pie8 | Reservado |
pie9 | Reservado |
pie10 | Reservado |
moneda | Esta opción especifica el tipo de moneda que se usará para realizar la transacción con tarjeta. CL: Pesos chilenos US: Dólares estadounidenses Valor por defecto "CL" |
baudiosPinPad | Los Baudios especifican la velocidad del traspaso de la información entre el PINPAD y la maquina a la cual está conectado. (Este valor debe coincidir con el valor ingresado en el archivo PPSC5000.ini) |
tipoDeCaja | Esta opción se configura para que la aplicación inicie una venta presencial o una no presencial, con las opciones caja host y Agencia respectivamente. Valores posibles: Y: Si N: No Valor por defecto N |
debito | Habilita/deshabilita la transacción de Venta con tarjeta de Débito. Esto también habilita/deshabilita las transacciones de carga de llaves. Valores Posibles: Y = Habilita la transacción de venta con tarjeta Débito N = No permite hacer transacciones de venta con tarjeta de Débito. Nota: Por defecto este campo debe tener el valor Y |
monMinPesosChilenos | Especifica el monto mínimo para realizar una compra con tarjeta. Monto ingresado en pesos Chilenos. |
monMinDolares | Especifica el monto mínimo en dólares para realizar la compra con tarjeta. |
empleado | Habilita/deshabilita la solicitud de número de empleado. Valores Posibles: Y = Habilita la opción de solicitar el código de empleado. N = No permite ingresar el código de empleado. Nota: Por defecto, debe tener valor Y |
boleta | Habilita / deshabilita la solicitud de número de boleta. Valores Posibles: Y = Habilita la opción de solicitar el número de boleta N = No permite ingresar el número de boleta. Nota: Por default este campo debe tener el valor Y |
terminal | Identificación del punto de venta asignada por Transbank para operaciones en la moneda pesos. |
terminalDolar | Identificación del punto de venta asignado por Transbank para operaciones en la moneda dólares |
comercio | Esta opción determina el Comercio al cual pertenece VTOL (Sucursal) para operaciones en la moneda pesos. |
comercioDolar | Esta opción determina el Comercio al cual pertenece VTOL (Sucursal para operaciones en la moneda dólares. |
timeOut | Tiempo máximo que espera el POS por la respuesta a un mensaje enviado a Transbank. Este tiempo viene dado en segundos y por default debe tener el valor 20 (veinte segundos). |
timeOut4Digitos | Es la unidad de tiempo que la aplicación espera para el ingreso de los últimos cuatro dígitos del PAN, si este no se ingresa la aplicación arroja un mensaje de TimeOut. |
maxCuotasN | Este valor refleja el monto máximo de la cuota que la aplicación mostrará al momento de realizar la venta con tarjeta. |
panManual | En este parámetro se escoge la opción de solicitar o no el ingreso del número de la tarjeta manualmente. |
venta | Permite habilitar o deshabilitar la transacción de Venta. Por defecto esta transacción debe estar habilitada. Valores: Y = VENTA habilitado N = No permite Venta |
anulacion | Permite habilitar o deshabilitar la transacción de Anulación. Por defecto esta transacción debe estar habilitada. Valores: Y = Anulación habilitado N = No permite Anulación |
6.3 Parámetros del Voucher
Esta sección detalla la información que viaja en el campo de requerimiento voucherParameters de un mensaje de autorización.
Como se mencionó los parámetros viajan en un campo compuesto, con el siguiente formato:
[clave1|valor1, clave2|valor2,…, claveN|valorN]
A continuación se describen las posibles claves y el detalle del valor de cada una de ellas:
Clave | Detalle del Valor |
pageWidth | Ancho del voucher en caracteres. El valor por defecto es ‘40’. |
pageMaxLength | Largo del voucher. El valor por defecto es ‘-1’. |
copyCount | Cantidad de comprobantes a emitirse. El valor por defecto es ‘1’ y corresponde al voucher original. 2 corresponde a la emisión del voucher original y la copia y 3 corresponde a la emisión del voucher original, la copia y el triplicado. |
outputType | Formato de salida. El valor por defecto y válido es ‘txt’. |
configurationClass | Configuración adicional, permite elegir el formato de voucher de salida Valores soportados: - ‘default’, valor por defecto - ‘v18’, correspondiente al formato especificado en el manual de TBK versión 1.8 - ‘v2’, correspondiente al formato de Voucher único especificado por Transbank |
reprintCopyCount | Cantidad de comprobantes a reimprimirse. El valor por defecto es ‘1’ y corresponde a la reimpresión del voucher original. 2 corresponde a la reimpresión del voucher original y la copia. |
6.4 Encabezado del Voucher
Esta sección detalla la información que viaja en el campo de respuesta voucherHeader de un mensaje de autorización.
Como se mencionó la configuración viaja en un campo compuesto, con el siguiente formato:
[clave1|valor1, clave2|valor2,…, claveN|valorN]
A continuación se describen las posibles claves y el detalle del valor de cada una de ellas:
Clave | Detalle del Valor |
nombreComercio | Nombre de comercio. Corresponde al valor encab1 de la configuración. |
direccionComercio | Dirección del comercio. Corresponde a valor encab2 de la configuración. |
ciudadComercio | Ciudad del comercio. Corresponde a encab3 de la configuración. |
nombreEECC | Nombre de comercio EECC. |
codigoEECC | Código de comercio EECC. |
versionApp | Versión de la aplicación. |
6.5 Pie del Voucher
Esta sección detalla la información que viaja en el campo de respuesta voucherFooter de un mensaje de autorización.
Como se mencionó la configuración viaja en un campo compuesto, con el siguiente formato:
[clave1|valor1, clave2|valor2,…, claveN|valorN]
A continuación, se describen las posibles claves y el detalle del valor de cada una de ellas:
Clave | Detalle del Valor |
nombrePromocion | Nombre de la promoción en el caso de tratarse de una transacción premiada. |
plazoCuota | Plazo de la cuota. |
nombreCliente | Nombre del tarjetahabiente. |
glosaTrxAfectaAhorro | Glosa transacción afecta ahorro. |
pie1 | Glosa configurable por comercio. |
pie2 | Glosa configurable por comercio. |
pie3 | Glosa configurable por comercio. |
pie4 | Glosa configurable por comercio. |
pie5 | Glosa configurable por comercio. |
pie6 | Glosa configurable por comercio. |
pie7 | Glosa configurable por comercio. |
pie8 | Glosa configurable por comercio. |
pie9 | Glosa configurable por comercio. |
pie10 | Glosa configurable por comercio. |
6.6 Cuerpo del Voucher
Esta sección detalla la información que viaja en el campo de respuesta voucherBody de un mensaje de autorización.
Como se mencionó la configuración viaja en un campo compuesto, con el siguiente formato:
[clave1|valor1, clave2|valor2,…, claveN|valorN]
A continuación, se describen las posibles claves y el detalle del valor de cada una de ellas:
Clave | Detalle del Valor |
fecha | Fecha de la transacción con formato DD/MM/AA. |
hora | Hora de la transacción con formato HH:MM:SS. |
fechaContable | Fecha contable para transacción de débito con formato DD/MM/AA. |
terminal | ID de la terminal donde se realizó la transacción. |
numeroTarjeta | Últimos 4 dígitos de la tarjeta. |
marcaTarjeta | Marca de la tarjeta. |
monto | Monto de la transacción sin propina/donación/vuelto. |
tipoCuotas | Los valores posibles para los tipos de cuotas son:
|
glosaTipoCuotas | Descripción de los tipos de cuotas. |
montoCuota | Monto de cada una de las cuotas. |
montoCuotaDiferido1 | Monto de la cuota 1 en caso de que tipo de cuota sea C2C o C3C. |
montoCuotaDiferido2 | Monto de la cuota 2 en caso de que tipo de cuota sea C2C o C3C. |
montoCuotaDiferido3 | Monto de la cuota 3 en caso de que tipo de cuota sea C3C. |
tasaInteres | Tasa aplicada a la transacción. Se imprime si flagImprimirTasa es true. |
empleado | Número de empleado. Sólo se envía si la terminal tiene habilitada la opción de solicitar número de empleado. |
numeroOperacion | Correlativo de transacción del terminal. |
codigoAutorizacion | Código de autorización asignado por Transbank. |
numeroUnico | Número único asignado por el comercio. |
propinaDonacion | Monto de la propina, si está habilitada en la terminal. |
vuelto | Monto del vuelto. Sólo aplica para transacciones con tarjeta de débito. |
montoPremio | Monto del premio en el caso de tratarse de una transacción premiada. |
glosaValePremio | Glosa del premio en el caso de tratarse de una transacción premiada. |
cantidadCuotas | Cantidad de cuotas. |
codigoPromocion | Código de la promoción. |
tipoTrxPremiada | Tipo de la transacción con premio. |
textoValePremio | Texto correspondiente al premio. |
tipoPromocion | Tipo de promoción. |
numeroDoc | Número de documento. |
6.7 Formato del Voucher
Esta sección detalla la información que viaja en el campo de respuesta formattedVoucher de un mensaje de autorización.
Como se mencionó el formato viaja en un campo compuesto, con el siguiente formato:
[clave1|valor1, clave2|valor2,…, claveN|valorN]
A continuación, se describen las posibles claves y el detalle del valor de cada una de ellas:
Clave | Detalle del Valor |
original | Voucher original formateado en Base64. |
duplicate | Voucher copia formateado en Base64. |
triplicate | Voucher triplicado formateado en Base64. |
outputType | Formato de salida indicado en el requerimiento. |
special | Voucher especial formateado en Base64. Ejemplo: transacciones premiadas. |
6.8 Control Transaccional
El control transaccional permite que la EMV KIT pueda decidir qué acción tomar transacción a transacción. Es decir, si debe confirmarla o reversarla.
IMPORTANTE: Este tipo de control es recomendado para evitar inconsistencias con las transacciones realizadas |
Para poder activar este control el POS debe tener en cuenta todos los puntos que se detallan a continuación
1- Enviar activo el flag transactionalControl (valor = 1) de la operación CreateSession.
2- Registrar cada uno de los campos 24 – trxId retornados por la EMV KIT para las autorizaciones Aprobadas.
3- Si se envía otra operación de Lectura de Tarjeta en la misma sesión, y la autorización previa fue procesada con éxito en el POS, se debe incluir el campo 24 – lastTrxId con el valor devuelto por la EMV KIT para dicha autorización.
4- En la operación CloseSession con valor del campo closeSessionAction = CLOSE, se debe incluir el campo 1009 closeTrxIdList, el cual contiene una lista de todos los trxId (campo 24) de las autorizaciones procesadas con éxito en el POS.