VTOL EMVKIT UY GEOITD 1.0.X
1. Introducción
1.1 Acerca de este documento
El presente documento explica la manera de integrarse a la Librería EMV Kit Argentina.
1.2 Qué es EMVKIT?
EMVKIT es una utilidad que simplifica la integración y la comunicación con el medio de pago de tarjetas abstrayendo a la aplicación de punto de venta de procesos como:
- el manejo del PINPAD (inicialmente el modelo Verifone VX820)
- el reconocimiento de tarjetas (crédito/débito y otras, como supervisor, tarjeta regalo, etc)
- la comunicación e integración con Gateway de transacciones GeoItd
- detectar y resolver problemas de contingencia
- etc
1.3 Alcance
EMVKIT tiene el siguiente alcance:
- Capturar el Track I y el Track II de la tarjeta por medio del PINPAD
- Capturar información del CHIP por medio del PINPAD
- Soporte PINPAD VX820 VISA/POSNET vía RS232 o USB
- Identificar la tarjeta o proveedor
- Facilitar el PAN enmascarado según normas PCI (solo visibles los primeros 6 y últimos 4 dígitos)
- Capturar el CVC por medio del PINPAD
- Capturar la fecha de vencimiento por medio del PINPAD en caso de que el ingreso sea manual
- Capturar el PIN por medio del PINPAD
- Capturar el tipo de cuenta por medio del PINPAD
- Evaluar bines de excepción
- Proveer código de banco emisor cuando la tarjeta sea 'Mastercard'
- Soportar modo de ingreso CHIP, BANDA y MANUAL
- Manejar contingencia entre PINPAD, caja y GeoItd
- Comunicación entre aplicativo punto de venta y GeoItd
- Resolver las reglas de negocio propias de cada PINPAD (Fiserv)
- Soporte de operaciones de venta como devoluciones, anulación de venta
- Gestionar la mensajería con GeoItd
Es responsabilidad de la aplicación de Punto de Venta:
- La identificación del banco por medio de opciones en pantalla (siempre y cuando no sea una tarjeta Mastercard, que posee la identificación en el track, ya que será devuelto por la librería en el caso de que existan promociones bancarias)
- La validación de los últimos N dígitos de la tarjeta
- La confirmación del monto
- El cálculo de promociones, la validación de plan de pago, la determinación de cuotas y la aplicación de la selección de tarjeta en la instancia que la librería detecte más de una coincidencia (en algunos casos, debido a normas PCI, la determinación de la tarjeta se hace por contacto visual ya que se comparte el BIN)
- Impresión del voucher y duplicado
1.4 Requisitos
A continuación, se listan los requisitos mínimos que requiere EMVKIT para su correcto funcionamiento:
1.4.1 Plataformas Soportadas
- Windows 32/64 bits
- Linux CentOS 7
1.4.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.4.3 Requerimientos de Software
- Java Virtual Machine (JDK) 1.8.x (32/64 bits acorde con el sistema operativo)
- Conexión a GeoItd por red TCP/IP
2. Funcional
2.1 Explicación General
EMVKIT 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 GeoItd, 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
- Obtención de datos de tarjeta
- Procesamiento de tarjeta
- 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 EMVKIT carga la configuración desde GeoItd, sincroniza el estado de las transacciones, verifica el funcionamiento del PINPAD, etc. Posteriormente se entra en un ciclo de llamadas para obtener información de la tarjeta y luego procesarla (autorizarla). Esto se realiza tantas veces como tarjetas se utilicen para pagar la transacción. Finalmente se procede al cierre de sesión donde EMVKIT confirma las transacciones contra el servidor GeoItd.
En el apartado 1.9 Tipos de Operación se explica en mayor detalle cada operación en particular y en el anexo 1.15 Circuito Operativo de EMVKIT se detalla el flujo de 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 EMVKIT:
- Iniciar sesión.
- Obtener información de la tarjeta, sin importar el modo de ingreso.
- Con esta información la aplicación de punto de venta procede al cálculo de promociones, intereses, opciones de pago, etc., según corresponda.
- Finalizados estos cálculos, la aplicación de punto de venta solicita el procesamiento de la transacción. En este punto EMVKIT valida y solicita otros datos a través del PINPAD. Si todo marcha bien, procede a la autorización con GeoItd y este a su vez contra los centros autorizadores.
- Cuando arriba la respuesta desde GeoItd, 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.
- En caso de que se ingrese otro pago con tarjeta, se vuelve al paso 2 y así sucesivamente.
- Una vez que finaliza el cobro de la transacción, el punto de venta cierra la sesión contra EMVKIT, indicando si la misma finalizó con éxito o se debe cancelar. Para ambos casos, la librería se sincroniza con GeoItd confirmando las transacciones cerradas o reversando las canceladas.
3. Instalación
3.1 Procedimiento de Instalación
La instalación de EMVKIT 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 EMV Kit pueda actualizarse remotamente.
Para ello se deben seguir los siguientes pasos:
- Iniciar sesión en el sistema operativo donde se instalará EMVKIT 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-uy-installer-1.0.0-SNAPSHOT-2022-08-19-14-03.jar
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".
6. En la siguiente pantalla se deben ingresar las siguientes propiedades:
- El directorio donde se encuentra Java
- El directorio donde se desea instalar EMVKIT o EMV Kit
- Versión de VTOL: Se deberá seleccionar entre VTOL 3.X ó VTOL 7.X Rest
- “Instalación GeoItd”, al tildar el checkbox, solicitará en el próximo step o pantalla N°7 los datos vinculados a GeoItd.
- Checkbox "Actualizable Remotamente", su función permite actualizar EMV Kit remotamente gracias a Director. Si no se habilita el componente checkbox, se ofrecerá la pantalla del punto (N°7).
- Checkbox "Código de compañia por configuracion": Al tildarlo se deberá completar consecuentemente el dato del código de compañía VTOL en la pantalla N° 9.
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.a. Esta pantalla se brindará cuando se haya habilitado el componente checkbox "Instalación GeoItd" del punto anterior.
Se deberá ingresar la siguiente información, para realizar la configuración de VTOL 3.
- ID POS GeoItd
- Numero de terminal asignado al pinpad/POS. Para obtener el número de la misma se debe presionar el botón verde del pinpad, y luego dirigirse a la opción ADMINISTRACION/MANTENIMIENTO, allí se mostrará el número de terminal.
- Id sistema GeoItd
- Id entregado por GeoItd a cada comercio.
- URL Base servicio REST GeoItd.
- URL para comunicarse con el servicio de GeoItd.
Oprimir el botón "Siguiente".
Importante:
Esta pantalla aparece solo si se seleccionó la versión VTOL 3.X de la lista
7.b. Esta pantalla se brindará cuando se haya habilitado el componente checkbox "Instalación GeoItd" del punto anterior.
Se deberá ingresar la siguiente información, para realizar la configuración de VTOL 7.
- ID POS GeoItd
- Numero de terminal asignado al pinpad/POS. Para obtener el número de la misma se debe presionar el botón verde del pinpad, y luego dirigirse a la opción ADMINISTRACION/MANTENIMIENTO, allí se mostrará el número de terminal.
- Id sistema GeoItd
- Id entregado por GeoItd a cada comercio.
- URL Base de conexión a VTOL7
- URL Base de conexión a VTOL 7.
Oprimir el botón "Siguiente".
Importante:
Esta pantalla aparece solo si se seleccionó la versión VTOL 7.x Rest de la lista.
8. Esta pantalla se brindará cuando se haya habilitado el componente checkbox "Instalación GeoItd" 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
- Código de Compañía
- Código de Tienda
- Código de Terminal
9. En esta pantalla se deberá incorporar el dato del código de Compañía VTOL (alfanumérico):
10. 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
11. La finalización de la instalación se informa mediante un mensaje de "Terminado".
Oprimir "Aceptar".
12. Presionar el botón "Salir" para salir del instalador.
3.2 Servicios Instalados
Finalmente, EMVKIT o EMV Kit queda funcionando como un servicio junto con el componente agente de Director:
Donde:
- EmvKit: Servicio de EMVKIT o EMV Kit
- EmvKitDirectorService: Servicio del componente agente de Director correspondiente a EMVKIT o 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 EMVKIT o 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 |
doc | Contiene |
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 los archivos 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 EMVKIT o EMV Kit |
lib | Contiene todos los archivos JAR, propietarios y de terceros, requeridos para el funcionamiento de EMVKIT |
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 |
Dentro de la carpeta "doc", se encuentran los siguientes archivos:
Carpeta / Archivo | Descripción |
---|---|
map_port.sh | Script, exclusivo para entorno Linux (versión soportada por VTOL) e idealmente para que sea ejecutado al inicio del sistema, que permite asignarle un alias específico a los puertos que poseen una conexión establecida con pinpads para poder definirlos por ese alias. Nota: El alias se configura desde el archivo serialPinPad.properties |
README.txt | Documento de texto que informa los objetivos de los archivos contenidos en la carpeta "doc" |
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
EMVKIT cuenta con los siguientes archivos de configuración:
4.1 Opciones de configuración JAVA
Para que EMVKIT 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 EMV KIT recibirá y enviará los mensajes al punto de venta. Si no se menciona esta propiedad, el bind por defecto es 127.0.0.1 |
-DLIB_BIND_PORT | Puerto en el cual la EMV KIT recibirá y enviará los mensajes al punto de venta. Si no se menciona esta propiedad, el bind por defecto es 3500 |
-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) |
4.2 Archivos de configuración
EMVKIT cuenta con los siguientes archivos de configuración:
Archivo | Descripción |
---|---|
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 |
crypt.properties | Archivo con parámetros criptográficos del pinpad |
devices.properties | Archivo de configuración de controllers y drivers del pinpad. Uso interno de la librería. No se debe modificar |
EXCEPTION_BIN.cfg | Archivo creado y gestionado por la librería. Se utiliza para persistir la configuración de los bines de excepción |
LAST_RSA.pem | Contiene el valor RSA. No se debe modificar |
log4j.properties | Configuración de logeo de la librería |
messages.properties | Configuración de los descriptores de respuesta y las leyendas del pinpad |
operations.properties | Contiene el conjunto de operaciones y reglas de la librería. Uso interno de la aplicación. No se debe modificar |
serialPinPad.properties | Configuración del dispositivo pinpad (No es requerido para GeoItd) |
session.obj | Archivo que registra información de estado y transaccional de la última sesión que el POS estableció con EMVKIT |
synthesis.keystore | Archivo que almacena claves y certificados de la librería |
restPinPad.properties | Contiene las propiedades de conexión con la API de Geoitd. |
4.3 Configuración de logeo
EMVKIT 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 "XXXplicac" (cambio a otro archivo de logeo) |
log4j.appender.file.MaxBackupIndex | Máxima cantidad de archivos de logs que se conservarán |
5. Integración
Como se mencionó anteriormente, EMVKIT 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 TCPIP, capaz de interpretar mensajes del protocolo VTOL.
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 EMVKIT, 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 EMVKIT, 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
EMVKIT 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 EMVKIT.
A continuación se detallan los campos que la aplicación punto de venta debe enviar a EMVKIT, haciendo uso de la librería cliente.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | createSession | Descripción |
---|---|---|---|---|
0 | company | Numérico | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | X | Tipo de Transacción:
|
25 | dateTime | Numérico | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
1025 | transactionalControl | Alfanumérico | X | Campo opcional del tipo flag. Este campo activo indica que se debe realizar un control transacción por transacción para decidir qué acción tomar sobre la última transacción procesada en la librería (confirmarla o reversarla). |
Ejemplo
Request to Full library: {25:20190401094039;1025:0;2:1;1:1;11:createSession;0:1} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | createSession | Descripción |
---|---|---|---|---|
1010 | currentSessionId | Numérico | X | Identificador de la nueva sesión |
1027 | libResponseCode | Numérico | X | Código de respuesta de la librería. |
1028 | libResponseMessage | Alfanumérico | X | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo
Response from Full library: {1010:27082015182500;1028:Ok;1027:000} |
B. Procesar Venta
Iniciación de transacción mediante método "Sale".
Para realizar esta operación no existe un tipo de transacción en particular. En su lugar, se debe enviar a EMVKIT el tipo de transacción que se desea realizar en el campo 11 – trxType.
Leer Datos de la Tarjeta
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | Descripción |
---|---|---|---|---|
0 | company | Numérico | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | X | Tipo de Transacción: Sale = Compra |
12 | amount | Importe | - | Monto de la transacción. 12 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 | - | Tipos de Moneda:
|
14 | payments | Numérico | - | Cantidad de cuotas. 2 dígitos como máximo. |
15 | plan | - | Plan. 1 caracter de longitud. | |
16 | originalDate | yyyyMMdd | - | Fecha y hora de realización de la transacción en formato YYYYMMDD |
22 | authorizationCode | Alfanumérico | - | Código de autorización telefónica. 6 dígitos como máximo. Este campo se encuentra presente sólo si la transacción se autorizó off-line por teléfono. |
24 | lastTrxId | Numérico | O | 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 | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
613 | taxRefund | Numérico | O | Indica si se debe realizar una devolución de impuestos. Valores posibles:
Importante: De no proporcionarse, tomará como referencia "0" (cero). |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {613:1;14:1;11:Sale;2:1;25:20220811095026;1:1;0:1} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | Descripción |
---|---|---|---|---|
10 | inputMode | Alfanumérico | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
1010 | currentSessionId | Numérico | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: |
1028 | libResponseMessage | Alfanumérico | X | Mensaje descriptivo del código de respuesta de la librería |
1102 | providers | Lista | X | Lista de proveedores/tarjetas que coinciden con la tarjeta ingresada en el PINPAD. Esta lista deberá ser utilizada para seleccionar la tarjeta manualmente |
1103 | cardContextId | Numérico | X | 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 “Procesar Operación con Tarjeta” |
1104 | prefixesList | Lista | X | Lista que informa el/los prefijo/s, proveedor/es, si se admite cashback, el límite del monto cashback de la tarjeta ingresada en el pinpad. Tener en cuenta que los últimos dos dígitos de los campos límite del monto cashback corresponden a decimales. |
1105 | panFirstDigit | Numérico | X | Primero 6 dígitos de la tarjeta. Si la tarjeta está dentro de los bines de excepción se devuelve el número entero |
1106 | panLastDigit | Numérico | X | Últimos 4 dígitos de la tarjeta. Si la tarjeta está dentro de los bines de excepción se devuelve el número entero |
1107 | pan | Alfanumérico | X | Valor de la tarjeta enmascarado según PCI |
1108 | isExceptionBin | Numérico | X | Flag que indica si se trata de un BIN de excepción (1) o si no lo es (0) |
1109 | ExceptionBinName | Alfanumérico | O | Si isExceptionBin = 1 entonces indica el nombre del bin de excepción |
1112 | CardHolderName | Alfanumérico | O | Si el valor es devuelto por el PINPAD. Nombre del titular de la tarjeta si el track I está presente y la lectura fue por banda |
1113 | cardIsDebit | Numérico | O | Si existe un único provider. Flag que indica si es una tarjeta de débito (1) o de crédito (0 o no viaja) |
1114 | bankCode | Numérico | O | Código de banco si es una tarjeta Master |
1115 | serviceCode | Numérico | O | Código de servicio devuelto por el PINPAD, siempre que no sea ingreso manual |
1116 | recordNumber | Numérico | O | Número de registro donde se almacena la transacción en el PINPAD. Reservado para uso futuro |
1117 | ExceptionBinExtraData | Alfanumérico | O | Si isExceptionBin = 1 entonces indica información adicional que pudiera servir al POS |
Ejemplo
Response from Full library: {1105:412322;1106:2322;1010:1660222218519;1027:000;1107:412322;1028:Ok;1108:0;1103:20220811095042427} |
Procesar Operación con Tarjeta
Operación utilizada para validar y obtener el resto de los datos de la tarjeta de Crédito Débito. Con estos datos, adicionados a los enviados por el POS, construye el mensaje que viaja hacia Geoitd para su autorización.
La utilización de esta operación es posterior a haber obtenido los datos básicos de la tarjeta por medio de la operación "Solicitud de nueva operación" (si la misma no fue realizada, no se podrán obtener datos asociados a la tarjeta).
En esta operación se debe confirmar el monto de la autorización, luego de haber aplicado las promociones y descuentos correspondientes. También deben incluirse todos los campos requeridos para que la autorización sea procesada según la mensajería.
Al igual que en la "Solicitud de nueva operación", para realizar esta operación no existe un tipo de transacción en particular. En su lugar, se debe enviar a EMVKIT el tipo de transacción que se desea realizar en el campo 11 – trxType.
Nota: La confirmación del monto se debe realizar en la aplicación de punto de venta.
No es necesario incluir campos asociados a la tarjeta, ya que EMVKIT es la encargada de obtener estos datos desde el PINPAD. Como ser: CVC, Fecha de expiración, Track I, Track II, etc., según el modo de ingreso.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | Descripción |
---|---|---|---|---|
0 | company | Numérico | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
11 | trxType | Alfanumérico | X | Tipo de Transacción:
|
12 | amount | Importe | X | Monto de la transacción. 12 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 | X | Tipos de Moneda:
|
14 | payments | Numérico | X | Cantidad de cuotas. 2 dígitos como máximo |
15 | plan | Alfanumérico | X | Plan. 1 caracter de longitud |
16 | originalDate | Fecha | - | Este campo debe viajar si el tipo de transacción es Refund. Se trata de la fecha de la transacción original en el formato YYYYMMDD |
17 | originalTrxTicketNr | Numérico | - | Este campo debe viajar si el tipo de transacción es Refund y es opcional cuando el tipo de transacción es VoidSale. Se trata del número de ticket de la transacción original. 4 dígitos como máximo |
18 | referedSale | Numérico | O | Se usa para indicar si una venta se hizo de forma referida. SOLO para AMEX. Se debe encender este campo con el valor 1 |
25 | dateTime | Numérico | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
53 | paymentCondition | Alfanumérico | O | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción |
54 | additionalAmount | Alfanumérico | - | Contiene el Importe del "Cash Back". Se usa en transacciones del tipo SaleCashBack. Debe contener 12 dígitos como máximo |
57 | accountType | Alfanumérico | O | Campo que se emplea para identificar el tipo de cuenta. Se usa para tarjetas de débito. Los valores posibles son:
El POS puede enviar este campo y de esa forma el pinpad no pedirá por el tipo de cuenta para Maestro, y a su vez el único que la envía es tarjeta Maestro. |
70 | effectiveDate | Alfanumérico | O | Fecha efectiva. Se usa para AMEX con formato YYMM |
73 | interestAmount | Alfanumérico | O | Este campo es por si se necesita enviar el monto de los intereses en el mensaje a Autorizar. Normalmente el monto que llega del POS ya contiene los intereses en el caso de pagar en cuotas. Existe algún caso de alguna tarjeta especial donde el monto hay que enviarlo libre de intereses y justamente el monto de los intereses viaja en este campo |
74 | requestAccountNumber | Alfanumérico | O | Indica si puede recibir el número de cuenta (Visa y Posnet). Default = 0. Valores posible:
|
101 | differDate | Alfanumérico | O | Fecha diferida. Solo utilizada para AMEX |
118 | terminalCapability | Alfanumérico | O | Capacidad de captura. Valores 1 = Manual / 2 = Lectura de Banda / 5 = Lectura de Chip |
130 | posPeriod | Numérico | O | Indica el Periodo del POS en que se realiza la operación. Solamente es registrado en VTOL. Longitud 5 |
131 | turn | Numérico | O | Indica Turno en que se realiza la operación. Solamente es registrado en VTOL. Longitud 2 |
132 | operatorCode | Alfanumérico | O | Código de operador. Solamente es registrado en VTOL. Longitud 20 |
133 | operatorName | Alfanumérico | O | Nombre de operador. Solamente es registrado en VTOL. Longitud 50 |
134 | sellerCode | Alfanumérico | O | Código del vendedor que realiza la operación. Solamente es registrado en VTOL. Longitud 20 |
135 | sellerName | Alfanumérico | O | Nombre del vendedor que realiza la operación. Solamente es registrado en VTOL. Longitud 50 |
136 | attentionMode | Alfanumérico | O | Modalidad de atención (AU ó AS). Longitud 2 |
605 | taxableAmount | Numérico | O | Monto grabado de la transacción con dos posiciones decimales sin puntos ni comas. (ej. 1.200,50 se debe enviar como 120050). |
607 | invoiceAmount | Numérico | O | Monto total de la factura con dos posiciones decimales sin puntos ni comas. (ej. 1.200,50 se debe enviar como 120050). |
612 | invoiceNumber | Alfanumérico | O | Número de factura con un máximo de 7 caracteres. Obligatorio si se envía TAXREFUND. Sin el número de factura la financiera no aplicara la devolución de impuestos. |
613 | taxRefund | Numérico | O | Indica si se debe realizar una devolución de impuestos. Valores posibles:
Importante: De no proporcionarse, tomará como referencia "0" (cero). |
1102 | provider | Alfanumérico | O | Proveedor / tarjeta seleccionada manualmente de la lista devuelta por la librería en la operación Leer Datos de la Tarjeta. Por Ejemplo: Si la operación Leer Datos de Tarjeta retorna la lista {VI, EL}, en la operación Procesar Operación con Tarjeta se debe enviar el valor seleccionado entre las dos opciones VI o EL. |
1103 | cardContextId | Numérico | O | 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 Datos Tarjeta" |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {1103:20220811095042427;15:0;613:1;14:1;13:$;12:10000;11:Sale;607:1500;605:200;2:1;25:20220811095055;1:1;0:1} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | Descripción |
---|---|---|---|---|
10 | inputMode | Alfanumérico | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
22 | authorizationCode | Alfanumérico | X | Código de autorización generado por el centro autorizador para la transacción cuando al transacción fue aprobada |
23 | authorizationMode | Alfanumérico | O | Modo de Autorización:
|
24 | lastTrxId | Numérico | X | Id de transacción en VTOL Server. La misma queda en estado pendiente y debe ser confirmada o cancelada cuando se cierra la sesión con EMVKIT |
25 | dateTime | Numérico | O | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. El valor en este campo debe ser el mismo que el valor de la fecha y hora del requerimiento. El POS utiliza este dato para validar que se trate de la misma transacción |
26 | responseCode | Alfanumérico | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. |
28 | responseMessage | Alfanumérico | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
31 | lotNumber | Numérico | X | Número de lote (String Máx. 10) |
32 | ticket | Numérico | X | Número de Ticket correspondiente a la transacción. |
33 | creditCardIssuerName | Alfanumérico | O | Nombre del Centro emisor de la tarjeta |
34 | name | Alfanumérico | O | Nombre del canal por el cual se autorizó la tarjeta |
35 | errorDescription | Alfanumérico | O | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
42 | lotDefinitionId | Numérico | O | Identificador de la definición de lote |
68 | rrn | Numérico | O | Reference referral number |
57 | accountType | Alfanumérico | O | Campo que se emplea para identificar el tipo de cuenta. Se usa para tarjetas de débito. Los valores posibles son:
|
75 | accountNumber | Alfanumérico | O | Campo que se emplea para identificar la cuenta. Informa el mismo valor que el accountType |
81 | responseAuth | Alfanumérico | O | Mensaje de repuesta para ser mostrado en el display del POS donde se indican promociones. También es utilizado en la operación de Cash Back, cuando el autorizador responde con código de respuesta 98. En este campo se informará el importe máximo que puede solicitarse |
603 | terminal | Numérico | O | Número de Terminal definido por Fiserv. |
613 | taxRefund | Alfanumérico | O | Informa el número de la ley que se aplicó para devolución de impuestos. Retorna de esta manera:
|
619 | acquirer | Numérico | O | Información del Adquirente. Es retornado por Fiserv. Este campo es utilizado para anular transacciones realizadas con tarjetas Contactless. |
631 | merchant | Numérico | O | Número de comercio definido por Fiserv. |
642 | taxAmount | Numérico | O | Es el monto que se retiene de IVA. |
1010 | currentSessionId | Numérico | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | Mensaje descriptivo del código de respuesta de la librería |
1103 | cardContextId | Numérico | X | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. |
1107 | pan | Alfanumérico | X | Valor de la tarjeta enmascarado según PCI |
1110 | pinpadApplicationId | Alfanumérico | X | Identificador de la Aplicación del PINPAD. |
1111 | pinpadApplicationName | Alfanumérico | X | Nombre de la Aplicación del PINPAD. |
1112 | cardHolderName | Alfanumérico | O | Nombre del titular de la tarjeta si el track I está presente y la lectura fue por banda. |
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. No implementado, reservado para uso futuro.
[Opcional 2]: Cuando la autorización fue aprobada y la librería retorna en un solo campo el Voucher formateado. No implementado, reservado para uso futuro.
[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
Ejemplo
Response from Full library: {31:003;32:98748191;1010:1661801597365;1027:000;1107:5399099990081043;1028:Ok;22:9874819100;27:00;28:APROBADA;1103:20220829163400864;603:00000014;631:1} |
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.
C. Procesar Devolución
Iniciación de transacción mediante método "VoidSale" o "Refund".
Para realizar esta operación no existe un tipo de transacción en particular. En su lugar, se debe enviar a EMVKIT el tipo de transacción que se desea realizar en el campo 11 – trxType.
Será posible anular pagos realizados con tarjeta, dentro de la misma transacción. Se debe tener el número de ticket de la autorización original para poder realizar una anulación/devolución.
Cuando se selecciona un pago a ser anulado, EMVKIT enviará un mensaje de anulación a Fiserv UY y la interacción con el servicio es similar al de una venta, en la que la tarjeta debe ser ingresada al PIN Pad para poder procesar la transacción de anulación/devolución.
El proceso de devolución requerirá el ingreso de la tarjeta en el PIN Pad.
Considerando y teniendo en cuenta:
- Solo se podrá devolver a tarjeta el mismo día de la compra y por el monto total del pago realizado con esa forma de pago.
- No será posible realizar devoluciones parciales de un pago a tarjeta.
- No será posible realizar devoluciones a tarjeta en días posteriores a la compra.
- Todas las devoluciones que entren en los escenarios que no son posibles, se devuelven a efectivo en la tienda y el comercio posteriormente realiza un proceso fuera de línea con Fiserv.
- Se deberá controlar operativamente los intentos de devoluciones inválidas, para prevenir fraudes.
- En caso de que se intente realizar una anulación/devolución un día diferente al de la compra original, el servicio de Fiserv generará respuesta de error.
- El circuito es una solo interacción. El POS envía el mensaje de VoidSale y la respuesta retorna el resultado “Aprobada” o “Rechazada” y se cierra la transacción.
- El POS debe enviar el Número de ticket devuelto por EMVKIT en la operación de Venta.
- Se debe leer la tarjeta en el dispositivo Pinpad. La lectura de la tarjeta se hace luego de que el POS envía el mensaje de "VoidSale" o "Refund".
- No se podrá realizar Anulación de Devolución.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
C = Condicional
Número | Nombre del campo | Tipo de dato | VoidSale | Refund | Descripción |
---|---|---|---|---|---|
0 | company | Numérico | X | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | X | X | Tipo de Transacción: |
12 | amount | Importe | O | X | Monto de la transacción. 12 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 | O | X | Tipos de Moneda:
|
14 | payments | Numérico | O | X | Cantidad de cuotas. 2 dígitos como máximo. |
15 | plan | Numérico | O | X | Plan. 1 caracter de longitud. |
16 | originalDate | yyyyMMdd | O | X | Fecha y hora de realización de la transacción en formato YYYYMMDD |
17 | originalTrxTicketNr | Numérico | X | X | Este campo debe viajar si el tipo de transacción es VoidSale o Refund. Se trata del número de ticket de la transacción original. |
24 | lastTrxId | Numérico | O | O | 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 | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
613 | taxRefund | Numérico | O | O | Indica si se debe realizar una devolución de impuestos.
Importante: De no proporcionarse, tomara como referencia "0" (cero). |
619 | acquirer | Numérico | C | C | Información del Adquirente. Este campo es obligatorio para anular transacciones realizadas con tarjetas Contactless. |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {16:20220811;15:0;613:1;14:1;13:$;12:1500;11:Sale;2:1;25:20220811095026;1:1;0:1} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | VoidSale | Refund | Descripción |
---|---|---|---|---|---|
10 | inputMode | Alfanumérico | X | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
22 | authorizationCode | Alfanumérico | O | O | Código de autorización generado por el centro autorizador para la transacción cuando al transacción fue aprobada |
24 | lastTrxId | Numérico | X | X | Id de transacción en VTOL Server. La misma queda en estado pendiente y debe ser confirmada o cancelada cuando se cierra la sesión con EMVKIT |
25 | dateTime | Numérico | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. El valor en este campo debe ser el mismo que el valor de la fecha y hora del requerimiento. El POS utiliza este dato para validar que se trate de la misma transacción. |
26 | responseCode | Alfanumérico | X | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. |
28 | responseMessage | Alfanumérico | X | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
32 | ticket | Numérico | X | X | Número de Ticket correspondiente a la transacción. |
31 | lotNumber | Numérico | X | X | Número de lote (String Máx. 10) |
642 | taxAmount | Numérico | O | O | Es el monto que se retiene de IVA. |
1010 | currentSessionId | Numérico | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | X | Mensaje descriptivo del código de respuesta de la librería |
1102 | providers | Lista | O | O | Lista de proveedores/tarjetas que coinciden con la tarjeta ingresada en el PINPAD. Esta lista deberá ser utilizada para seleccionar la tarjeta manualmente en el POS. |
1103 | cardContextId | Numérico | X | X | 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 “Procesar Operación con Tarjeta” |
1105 | panFirstDigit | Numérico | X | X | Primero 6 dígitos de la tarjeta. Si la tarjeta está dentro de los bines de excepción se devuelve el número entero |
1106 | panLastDigit | Numérico | X | X | Últimos 4 dígitos de la tarjeta. Si la tarjeta está dentro de los bines de excepción se devuelve el número entero |
1107 | pan | Alfanumérico | X | X | Valor de la tarjeta enmascarado según PCI |
1108 | isExceptionBin | Numérico | X | X | Flag que indica si se trata de un BIN de excepción (1) o si no lo es (0) |
1109 | exceptionBinName | Alfanumérico | O | O | Si isExceptionBin = 1 entonces indica el nombre del bin de excepción |
Ejemplo
Response from Full library: {31:003;32:0016;1105:412322;1106:0016;1010:1661205876040;1027:000;1107:412322******0016;1028:Ok;1108:0;22:593024;603:000000000000000;28:APROBADA;1103:20220822190539335;27:00} |
D. Obtener Configuración de POS
Operación que permite a la aplicación de punto de venta obtener la información existente en VTOL Server relacionada con los planes, cuotas, tarjetas, prefijos y bines de excepción.
Mensajería
- Requerimiento
Número | Nombre del campo | Tipo de dato | getConfiguration | Descripción |
---|---|---|---|---|
11 | trxType | Alfanumérico | X | Tipo de Transacción:
|
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {11:getConfiguration} |
- Respuesta
Número | Nombre del campo | Tipo de dato | getConfiguration | Descripción |
---|---|---|---|---|
137 | confVersion | Numérico | X | Número de versión de configuración. |
138 | confData | Alfanumérico | X | Configuración de POS recibida desde VTOL server. El valor recibido corresponde a los datos registrados en un archivo de configuración codificados en Base64. Ver sección Formato Configuración POS |
1010 | currentSessionId | Numérico | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo
Response from Full library: |
E. Cerrar Sesión
Permite cerrar la sesión entre la aplicación de punto de venta y EMVKIT.
Internamente EMVKIT se sincroniza con Geoitd, confirmando o cancelando las transacciones procesadas dentro de la sesión.
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 EMVKIT indicando las transacciones a confirmar.
Cuando se desee cancelar una transacción dentro de una sesión de EMVKIT, es requisito realizar la anulación de la transacción teniendo que ingresar nuevamente la tarjeta o ingresar los datos de la misma.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | closeSession | Descripción |
---|---|---|---|---|
11 | trxType | Alfanumérico | X | Tipo de Transacción:
|
1008 | closeSessionAction | Alfanumérico | X | Acción que se debe realizar sobre el cierre de sesión:
|
1009 | closeTrxIdList | Lista | O | Lista de los trxId (campo 24) recibidos en la respuestas a las distintas llamadas "Procesar Operación con la Tarjeta" Obligatorio cuando el campo 1008 es igual a CLOSE |
250 | actionCode | Alfanumérico | O | Identificación del motivo por el cual la sesión tuvo un cierre forzado. Código de 5 caracteres.
Obligatorio cuando el campo 1008 es igual a FORCED_CLOSE |
251 | actionNote | Alfanumérico | O | Motivo informado por el punto de venta cuando la sesión tuvo un cierre no tradicional. Máximo de 50 caracteres Se debe enviar cuando el campo 1008 es igual a FORCED_CLOSE |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo de Requerimiento
Request to Full library: {1009:{270};1008:CLOSE;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.
- El campo closeTrxIdList es la lista de los trxIds que la aplicación de punto de venta recibió y almacenó. Solamente debe enviar esta lista cuando el valor del campo closeSessionAction es igual a CLOSE
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | closeSession | Descripción |
---|---|---|---|---|
1010 | currentSessionId | Numérico | X | Identificador de la sesión que se cierra |
1027 | libResponseCode | Numérico | X | Código de respuesta de la librería. |
1028 | libResponseMessage | Alfanumérico | X | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo de Respuesta
Response from Full library: {1010:28082015003859;1028:Ok;1027:000} |
5.3 Autorización Aprobada
Para determinar que una autorización fue aprobada es necesario:
- 1° verificar el campo libResponseCode:
1027 | libResponseCode |
Si el valor es igual a 000, indica que la librería pudo enviar la solicitud a Geoitd 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.
Además para poder determinar que la operación resultó aprobada, se debe verificar que se encuentre el campo 27 (isoCode) y evaluar qué código respondió. Sin la presencia del campo 27, no se puede dar por aprobaba una autorización.
- 2° verificar el campo isoCode:
27 | isoCode |
En este caso, si el valor de isoCode es igual a 00, 11 o 85 indica que la autorización ha sido Aprobada por Geoitd y que debe capturarse el valor del campo 24 (lastTrxId) para ser enviado en el cierre de sesión:
24 | lastTrxId |
6. Anexos
6.1 Códigos de Respuesta de EMVKIT
El código de respuesta de EMVKIT y su detalle se encuentran en los siguientes campos:
- Campo 1027: Código
- Campo 1028: Descripción de la Respuesta
A continuación se detallan las respuestas posibles con una breve descripción y significado de cada una:
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 | (PINPAD) Aprobado | Operación satisfactoria |
001 | (PINPAD) Cancelado por el usuario | Se usó la tecla CANCEL del PINPAD |
002 | (PINPAD) Error ingreso 4 últimos dígitos | El PINPAD detectó errores en el ingreso de los últimos 4 dígitos |
003 | (PINPAD) Error de lectura Track2 | El PINPAD no pudo leer el Track II |
004 | (PINPAD) Error Pinpad-ingreso PIN | No se ingresó correctamente el PIN en el PINPAD |
005 | (PINPAD) Error Chip | El PINPAD no pudo leer o grabar en el CHIP |
006 | (PINPAD) Error Fecha inválida | Se ingresó un fecha inválida en el PINPAD |
007 | (PINPAD) Error TimeOut | El PINPAD suspendió la operación por TIMEOUT |
008 | (PINPAD) Error en secuencia de comando recibido | El PINPAD rechazó un comando por estar fuera de secuencia |
009 | (PINPAD) Error en formato de comando recibido | El PINPAD rechazó un comando por formato erróneo |
011 | (PINPAD) Error de LRC de comando recibido | El PINPAD rechazó un comando por LRC erróneo |
013 | (PINPAD) Error de lectura. Intente nuevamente | El PINPAD genera un error en la lectura de una tarjeta Chip. |
019 | (PINPAD) Error falta Master Key | El PINPAD informa que falta la master key. |
025 | (PINPAD) Error CTLS - Intente por chip | El PINPAD informa que no pudo leer por contactless. |
101 | A SESSION is already created. | No se puede crear una nueva sesión con EMVKIT, debido a que ya existe una sesión activa. Además en la respuesta se incluye el campo 1010 (currentSessionId) que es el identificador de la sesión actual. |
102 | Lib is processing requests. | EMVKIT se encuentra procesando un requerimiento. |
103 | Lib is processing response. | EMVKIT se encuentra procesando una respuesta a un requerimiento. |
104 | Lib is processing a reverse. | La librería se encuentra procesando un reverso. |
198 | Acción invalida | La librería suspendió la operación por que la acción que se requiere es no válida. |
199 | TimeOut | EMVKIT suspendió la operación por Timeout |
700 | No opera Offline | |
701 | (API) Archivo de Sesión no existe | No existe el archivo que contiene la información de sesión |
702 | (API) Existen Trxs Pendientes con VTOL Server | Existen Transacciones pendientes con VTOL que no se pueden cerrar |
703 | (API) Estado de Sesión no es válido | El estado de la sesión es inválido. |
704 | (API) Tipo de Transacción es invalido | El tipo de transacción enviado en la llamada no es válido |
705 | (API) Error enviando mensaje a VTOL Server | Error enviando autorización a VTOL Server |
706 | (API) 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 | Cuando el monto off-line excede el límite configurado en el servidor. |
708 | Monto Cash Back inválido | Cuando el monto cashback excede el límite configurado en el servidor. |
711 | Error cancelando las transacciones. Existe una inconsistencia | Cuando no logra realizar un rollback sobre una transacción existente en la sesión. |
713 | Transaccion invalida | Cuando el dispositivo no soporta el tipo de transacción ingresado. |
718 | Modo de ingreso invalido | Cuando la lectura realizada por el PINPAD no es soportada por la versión de EMVKIT. |
719 | Error en impresion de voucher | Existió un error y el comprobante no se puede imprimir |
720 | No permite operar con la tarjeta ingresada | Cuando el tipo de transacción que se intenta realizar no soporta la tarjeta ingresada. |
721 | Transaccion no soporta cashback | Cuando el tipo de transacción que se intenta realizar no soporta cashback. |
722 | Falta de papel en dispositivo | El pinpad se queda sin papel y no se puede imprimir el voucher. |
723 | Excede el máximo de líneas permitido | El pinpad no puede imprimir el voucher genérico debido a que excede la cantidad de líneas permitidas. |
724 | Modo Ingreso Error | El PINPAD no permite el tipo de ingreso recibido. |
725 | Error en la configuracion del sistema | Cuando se requiere un cambio en la configuración del servidor. |
726 | No se encontro un dispositivo conectado | Cuando el dispositivo no se encuentra debidamente configurado. |
727 | Compañía inválida | Cuando la compañía informada no es válida, según lo configurado en el servidor. |
728 | No existe configuracion para la version requerida | Cuando la librería intenta obtener una versión de configuración que no existe en VTOL Server. Problemas de compatibilidad. |
729 | Reintente otro modo de ingreso | Cuando VTOL no tiene habilitado la encripción de datos sensibles, o cuando el prefijo no tiene habilitada la opción para que utilice mensaje encriptado. |
730 | Reintente operación sin modificar monto original | Cuando se modifica el monto o monto cashback en la operación de "Procesar operación con tarjeta". |
731 | Error en provider | Cuando el POS envía el ProviderPosCode, y EMVKIT detecta que no coincide con el valor de la configuración de los prefijos. |
801 | (API-PINPAD) PAN: Proveedor desconocido | La librería no pudo determinar el proveedor de una tarjeta |
802 | (API-PINPAD) PAN: Dígito verificador inválido | La librería encontró inválido el DV de una tarjeta |
803 | (AP-PINPADI) Error en protocolo con el PINPAD | La librería detectó un mensaje del PINPAD fuera de contexto |
804 | (API-PINPAD) Error de formato de mensaje del PINPAD | La librería detectó errores de formato en un mensaje del PINPAD |
805 | (API-PINPAD) Error en configuración de tarjetas | No se pudo identificar la tarjeta o la configuración es nula |
806 | (API-PINPAD) Error llave RSA invalida o nula | La librería no tiene llave RSA para trabajar. Se debe descargar de VTOL |
807 | (API-PINPAD) Error WK nula o formato invalido | La llave WorkingKey enviada por el POS tiene un formato inválido o es nula |
808 | Error cancelando operacion Tarjeta Chip. Intente anularla | Cuando una operación con tarjeta Chip no puede realizar un rollback de la operación. |
809 | Error en la sincronización del PinPad. | El PINPAD no puede completar el proceso de sincronización. |
810 | Error en sincronización del PinPad. Intente anular la operación. | El PINPAD no puede completar el proceso de sincronización porque tiene transacciones pendientes. Se recomienda un cierre forzoso. |
811 | Comando no soportado por el Pinpad | Cuando el dispositivo o la versión del mismo, no soporta el tipo de transacción ingresado. |
812 | Reintente operación | Cuando se realiza un cambio en la configuración del servidor sobre la llave RSA, y se aplican los cambios en EMVKIT. |
813 | No se permite la impresion de la corriente transaccion | El PINPAD o dispositivo no puede imprimir la transacción enviada por el POS. |
901 | (API) Error del sistema (general) | Error interno de la librería |
902 | (API) Error del sistema (I/O) | Error de entrada/salida o comunicación de la librería |
911 | (API) Error del sistema (carga) | Error al cargar la librería |
912 | (API) Error del sistema (contexto inexistente) | El POS envió un CARD_CONTEXT_ID inexistente |
913 | (API) Error del sistema (contexto inválido) | El POS envió un CARD_CONTEXT_ID inválido |
914 | (API) Error del sistema (carga working key) | Error leyendo o registrando las Claves de Trabajo<br>Interno de la librería |
999 | Error no manejado | Error no manejado |
6.1.1 Código de respuesta de EmvKit (equivalencia GeoItd) al POS
A continuación se detallan la equivalencia entre los códigos de respuesta que EmvKit recibe desde GeoItd, y que éste último responde al POS.
EMVKIT | GEOITD | ||||
Id | Def | Desc | Id | Def | Desc |
000 | OK | Ok | 0 | PAYMENT_OK | Resultado OK |
007 | TIMEOUT | Error TimeOut | 11 | TRX_TIMEOUT | Tiempo de transacción excedido, envíe datos nuevamente |
726 | ERR_DEVICE | No se encontro un dispositivo conectado | 100 | INVALID_PINPAD | Número de pinpad inválido |
725 | ERR_CONFIG | Error en la configuracion del sistema | 101 | INVALID_BRANCH | Número de sucursal inválido |
725 | ERR_CONFIG | Error en la configuracion del sistema | 102 | INVALID_CLIENT_APP_ID | Número de caja inválido |
713 | ERR_INVALID_TRX | Transaccion invalida | 103 | INVALID_TRX_DATE | Fecha de la transacción inválida |
707 | ERR_INVALID_AMOUNT | Monto inválido | 104 | INVALID_AMOUNT | Monto no válido |
713 | ERR_INVALID_TRX | Transaccion invalida | 105 | INVALID_QUANTITY_FEES | Cantidad de cuotas inválidas |
713 | ERR_INVALID_TRX | Transaccion invalida | 106 | INVALID_PLAN | Número de plan inválido |
713 | ERR_INVALID_TRX | Transaccion invalida | 107 | INVALID_INVOICE_NUMBER | Número de factura inválido |
713 | ERR_INVALID_TRX | Transaccion invalida | 108 | INVALID_CURRENCY | Moneda ingresada no válida |
713 | ERR_INVALID_TRX | Transaccion invalida | 109 | INVALID_TICKET_NUMBER | Número de ticket inválido. |
713 | ERR_INVALID_TRX | Transaccion invalida | 110 | TRANSACTION_NOT_FOUND | No existe transacción. |
725 | ERR_CONFIG | Error en la configuracion del sistema | 112 | INVALID_SYSTEM_ID | Identificador de sistema inválido. |
UDF | UNDEFINED | INDEFINIDO | 999 | UNDETERMINED_ERROR | Error no determinado. |
Ejemplo:
En éste caso en particular, EmvKit retorna un código de error general "713 - trx inválida" pero está representando el "ResponseCode": 105 - (Cantidad de cuotas inválidas)
6.2 Control Transaccional
El control transaccional permite que EMVKIT pueda decidir qué acción tomar transacción a transacción. Es decir, si debe confirmar o reversar cada transacción.
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:
- Enviar activo el flag del campo 1025 – transactionalControl (valor = 1) en la operación createSession.
- Registrar cada uno de los campos 24 – trxId retornados por EMVKIT para las autorizaciones Aprobadas.
- 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 EMVKIT para dicha autorización.
- En la operación closeSession, cuando en el campo 1008 – closeSessionAction el valor es CLOSE, se debe incluir el campo 1009 – closeTrxIdList que contiene una lista de todos los trxId (campo 24) de las autorizaciones procesadas con éxito en el POS.
Ejemplos de Control Transaccional
Operaciones de pagos parciales:
Transacción Aprobada, 1 sola transacción en la sesión:
Apertura de sesión.
Lectura de tarjeta.
Procesamiento de tarjeta. El host APRUEBA la transacción.
Cierre de sesión: Se cierra sesión en estado Close. En el campo 1009 (closeTrxIdList) se envía con el trxid de la única transacción, la cual se confirma.
Transacción Rechazada. 1 sola transacción en la sesión:
Apertura de sesión.
Lectura de tarjeta.
Procesamiento de tarjeta. El host RECHAZA la transacción.
Cierre de sesión: Se cierra sesión en estado Close. En el campo 1009 (closeTrxIdList) no se envía ningún trxid dado que no hay nada para confirmar ni reversar.
Transacción Aprobada, pero el POS reversa, 1 sola transacción en la sesión:
Apertura de sesión.
Lectura de tarjeta.
Procesamiento de tarjeta. El host APRUEBA la transacción, pero el POS decide Cancelar.
Cierre de sesión: Se cierra sesión en estado Cancel. En el campo 1009 (closeTrxIdList) no se incluye el trxid, dado que se debe reversar.
Transacción Aprobada, más de 1 transacción en la sesión:
Apertura de sesión.
Lectura de tarjeta.
Procesamiento de tarjeta. El host APRUEBA la transacción.
Lectura de otra tarjeta, con trxid de la transacción anterior.
Procesamiento de tarjeta. El host APRUEBA la transacción.
Lectura de otra tarjeta, con trxid de la transacción anterior.
Procesamiento de tarjeta. El host APRUEBA la transacción.
Cierre de sesión: Se cierra sesión en estado Close. En el campo 1009 (closeTrxIdList) se envían todas las operaciones aprobadas (ii, iv y vi), incluyendo la última transacción.
- Transacciones Aprobadas, pero la última retorna Denegada (el cliente decide NO continuar con la compra), más de 1 transacción en la sesión:
- Apertura de sesión.
- Lectura de tarjeta.
- Procesamiento de tarjeta. El host APRUEBA la transacción.
- Lectura de otra tarjeta, con trxid de la transacción anterior.
- Procesamiento de tarjeta. El host APRUEBA la transacción.
- Lectura de otra tarjeta, con trxid de la transacción anterior.
- Procesamiento de tarjeta. El host DENIEGA la transacción.
- Anulación de transacción ii. No envía el trxid de la anterior ya que no fue aprobada.
- Procesamiento de tarjeta. El host APRUEBA la transacción.
- Anulación de transacción iv, con trxid de la transacción anterior.
- Procesamiento de tarjeta. El host APRUEBA la transacción.
- Cierre de sesión: Se cierra sesión en estado Close. En el campo 1009 (closeTrxIdList) se envían todas las operaciones aprobadas (ii, iv, viii y x).
- Apertura de sesión.
- Transacción Aprobada, más de 1 transacción en la sesión, en el medio, una transacción retorna Denegada:
- Apertura de sesión.
- Lectura de tarjeta.
- Procesamiento de tarjeta. El host APRUEBA la transacción.
- Lectura de otra tarjeta, con trxid de la transacción anterior.
- Procesamiento de tarjeta. El host DENIEGA la transacción.
- Lectura de otra tarjeta. No envía el trxid de la anterior ya que no fue aprobada.
- Procesamiento de tarjeta. El host APRUEBA la transacción.
- Cierre de sesión: Se cierra sesión en estado Close. En el campo 1009 (closeTrxIdList) se envían todas las operaciones aprobadas (ii y vi).
- Apertura de sesión.
6.3 Formato Configuración POS
A continuación se detalla la información que viaja en el campo confData de un mensaje de solicitud de configuración, que se corresponde con la interface de configuración generada para el POS en VTOL Server.
La versión de Formato de interface utilizada por Crédito Debito Argentina es la v110.
Header
Pos. | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | HD | 2 | AN | Identificador de tipo de registro |
2 | Local | 6 | AN | Código local. |
3 | Incremental | 6 | N | Nº de incremental. |
4 | CRC | 8 | N | |
5 | Fecha / Hora | 16 | AN | Fecha/Hora. yyyy/mm/dd |
Ejemplo:
HD:000001;000004;00003d23;2008/03/07 10:20
Tabla Provider
Pos. | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | PV | 2 | AN | Identificador de tipo de registro |
2 | ID Tarjeta | 2 | AN | ID proveedor VTOL |
3 | Nombre | 40 | AN | Nombre proveedor |
4 | Medio de Pago | 20 | AN | Código proveedor en POS. |
5 | Código de banco | 10 | AN | Código del banco (Opcional) |
6 | Descripción del banco | 40 | AN | Descripción del banco (Opcional) |
7 | Marca de la Tarjeta | 10 | AN | Código de la Marca de la tarjeta (Opcional). Si la tarjeta no tiene marca, no se informa el campo. |
Ejemplo:
PV:VI;Visa;;00;DEFAULT;VI
PV:VIG;Visa;;7;BANCO DE GALICIA Y BUENOS AIRES S.A.U.;VI
PV:MA;Maestro;;00;DEFAULT;MC
PV:MC;Master Card;;00;DEFAULT;MC
PV:AM;Amex;;00;DEFAULT;AM
PV:DI;Diners;;00;DEFAULT
Tabla Prefijos
Pos | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | PF | 2 | AN | Identificador de tipo de registro |
2 | Hasta | 20 | AN | Rango Desde. |
3 | Desde | 20 | AN | Rango Hasta. |
4 | Largo prefijo | 2 | N | Largo del prefijo. |
5 | Largo tarjeta | 2 | N | Largo de la tarjeta. |
6 | ID Tarjeta | 2 | AN | ID proveedor VTOL |
7 | Condición | 10 | AN | |
8 | Largo CVC | 2 | N | Largo código seguridad. |
9 | Validar digito | 1 | N | Valida el digito verificador. |
10 | Envía Track I | 1 | N | 0/vacío deshabilitado / 1 habilitado / 2 Opcional. |
11 | Validar vencimiento | 1 | N | Valida fecha vencimiento. |
12 | Offline permitido | 1 | N | Permite operar offline. |
13 | Offline monto | 14 | N | Límite para operación Offline. |
14 | Habilitado | 1 | N | Prefijo habilitado. |
15 | Valida fecha efectiva | 1 | N | Valida fecha emisión o fecha desde. |
16 | Valida CVC | 1 | N | 0/vacío deshabilitado / 1 habilitado / 2 Opcional. |
17 | Service code | 5 | AN | Se suele utilizar en VTOL para diferenciar Visa débito (2) de Visa crédito (0 ó vació) |
18 | Ingreso manual permitido | 1 | N | |
19 | Chequea boletines | 1 | N | Valida contra boletines protectivos. |
20 | Es debito | 1 | N | Es prefijo de tarjeta de tipo débito. |
21 | Requiere pin. | 1 | N | 0 deshabilitado / 1 habilitado / 2 Opcional. |
22 | Valida últimos N números. | 2 | N | Cantidad de últimos números a validar de la tarjeta. 0 no valida nada. |
23 | Pide tipo de cuenta. | 1 | N | Requiere envío tipo de cuenta. |
24 | Solicita número de cuenta | 1 | N | Solicita al autorizador el número de cuenta. |
25 | Cashback | 1 | N | Habilita la operatoria de Cashback |
26 | Puntos de Lealtad | 1 | N | Habilita la acumulación y/o redención de puntos de lealtad. |
27 | Tarjeta que Encripta punto a punto POS - CA. | 1 | N | Indica si la tarjeta encripta. |
28 | Posición de la Master Key | 1 | N | Indica la posición de la Master Key en los registros del Firmware. Valores posibles: |
29 | Código de banco | 10 | AN | Código del banco |
30 | Permite Fallback | 1 | N | Visa 1; Mastercard y Maestro 0 |
31 | CashBack Amount Limit | 10 | N | Límite de importe Cashback |
32 | Descripción del banco | 40 | AN | Descripción del banco (Opcional) |
Ejemplo:
PF:4;4;1;16;VI;;3;1;1;1;1;1000;1;0;1;;1;0;0;0;4;0;1;0;0;1;1;;1
PF:34;34;2;15;AM;;4;1;1;1;1;00;1;0;1;;1;0;0;0;0;0;0;0;0;0;99;;;;
PF:69;50;2;16;MA;;0;0;1;0;0;1000;1;0;0;;0;0;1;1;0;1;0;0;0;0;0;7;0;;BANCO DE GALICIA Y BUENOS AIRES S.A.U.
Tabla Monedas
Pos. | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | MN | 2 | AN | Identificador de tipo de registro |
2 | Símbolo moneda | 10 | AN | $ ó U$S |
3 | Descripción | 20 | AN | Nombre de la moneda. |
Ejemplo:
MN:$;PESOS
MN:U$S;DOLARES
Tabla Plan de Pagos
Al POS exclusivamente se le enviarán las opciones de pago con Canal de Origen Presencial o las informadas en la propiedad de configuración "Canal de origen a mostrar en Nro de comercio y Def. de lote, para locales físicos". Esta configuración se encuentra disponible en VTOL Server a partir de la versión 3.8.0.8a
Pos. | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | PP | 2 | AN | Identificador de tipo de registro |
2 | ID Tarjeta | 2 | AN | ID proveedor VTOL |
3 | Símbolo moneda | 10 | AN | |
4 | Condición de pago | 20 | AN | Información adicional del plan de pago. |
5 | Plan | 4 | N | Código del plan de pago. |
6 | Cuotas | 4 | N | |
7 | Numero de comercio | 30 | AN | |
8 | ID Lote | 6 | N | |
9 | Limite a superar. | 13 | N | Monto a superar para poder utilizar el plan de pagos. |
10 | Limite intereses | 13 | N | Si el monto es superior a éste valor, entonces el interés es = 0 |
11 | Interés | 5 | AN | Tasa de interés (%) para el plan de pago. En formato 00.00 |
12 | Promocional | 1 | N | Activa con 1 o Desactiva con 0 Si aplica o no una promoción para el plan de pago. |
13 | Descripción | 20 | AN | Descripción del Plan de pago. |
14 | Tipo de operación | 1 | N | Indica cuál es el tipo de operación asociado al plan de pagos. Opciones posibles:
|
Ejemplo:
PP:AM;$;;0;1;98765432;101607;0000000000.00;0000000000.00;12.30;1;Normal;1
PP:VI;$;;0;10;98765432;101608;0000000100.00;0000000000.00;15.00;0;Normal;1
Tabla Definición de Lote
Pos. | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | DL | 2 | AN | Identificador de tipo de registro |
2 | ID Lote | 6 | N | Identificador interno de Lote en VTOL |
3 | Caja o Nodo | 10 | N | |
4 | Número de serie terminal | 200 | AN |
Ejemplo:
DL:5;0000000001;99990080
DL:5;0000000002;99990081
DL:5;0000000003;99990082
DL:5;0000000004;99990083
DL:5;0000000005;99990084
DL:5;0000000006;99990085
DL:5;0000000007;99990086
Tabla Bines de Excepción
Pos. | Descripción | Longitud | Tipo de dato | Detalle |
---|---|---|---|---|
1 | BE | 2 | AN | Identificador de tipo de registro |
2 | Desde | 9 | N | Rango Desde |
3 | Hasta | 9 | N | Rango Hasta |
4 | Nombre tarjeta | 25 | AN | Nombre de tarjeta de Excepción |
5 | Información Adicional | 500 | AN | Informacion adicional de la tarjeta de excepción |
Ejemplo:
BE:6006;6006;17;ASOCIADO;Pepe-123
BE:601056;601056;16;GIFT CARD;Extra