VTOL EMVKIT AR 1.6.X
1. Introducción
1.1 Acerca de este documento
El presente documento explica la manera de integrarse a la Librería VTOL 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 VTOL
- detectar y resolver problemas de contingencia
- etc
1.3 Arquitectura de la Librería
Arquitectura general de EMVKIT
Como se observa en la imagen, EMVKIT 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, y con el Gateway de transacciones VTOL.
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 EMVKIT 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 EMVKIT.
Arquitectura y Comunicación de EMVKIT
En la imagen se observan ejemplos de tramas de requerimiento y de respuesta transmitidas por TCP IP entre la librería liviana y EMVKIT. Los tipos de operaciones son los siguientes y se explayan en el apartado 1.9 Tipos de Operación:
- Creación de la sesión
- Lectura de los datos de la tarjeta
- Cancelación de la lectura de la tarjeta
- Procesamiento de una operación con tarjeta
- Procesamiento del mensaje Crédito Débito
- Procesamiento de mensajes PEI
- Obtención de la configuración del POS
- Cierre de la sesión
1.4 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 los datos de tarjeta encriptados, los cuales solo podrán ser desencriptados por VTOL Server o por el HOST autorizador según corresponda
- 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
- Suministrar la configuración de VTOL Server a la aplicación de punto de venta (prefijos, tarjetas, cuotas, intereses, etc)
- Manejar contingencia entre PINPAD, caja y VTOL
- Comunicación entre aplicativo punto de venta y VTOL Server
- Resolver las reglas de negocio propias de cada PINPAD (VISA/POSNET)
- Funcionalidad de venta con cashback
- Soporte de operaciones de venta como devoluciones, anulación de venta, anulación de devolución
- Soporte de operaciones de PEI (Pago Electrónico Inmediato) como venta y devoluciones
- Gestionar la mensajería con VTOL Server
Es responsabilidad de la aplicación de punto de ventas:
- 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.5 Requisitos
A continuación, se listan los requisitos mínimos que requiere EMVKIT 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) 1.6.x/1.7.x/1.8.x (32/64 bits acorde con el sistema operativo)
- Conexión a VTOL Server 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 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
- 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 VTOL, 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 VTOL.
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 VTOL Server y este a su vez contra los centros autorizadores.
- 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.
- 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 VTOL Server 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-ar-installer-1.6.0.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
- El código de la compañía, configurado en Director
- El código de la tienda, configurado en Director
- El código de la terminal de la tienda desde donde se operará, configurado en Director
- La IP de VTOL Server para poder comunicarse
- El puerto de VTOL Server
- Por defecto 3003 (con SSL)
- La IP donde se comunica EMV Kit
- Por defecto localhost
- El puerto donde se vincula EMV Kit
- Por defecto 3500
- 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
Oprimir el botón "Siguiente".
8. Indicar el puerto donde se encuentra conectado el pinpad y seleccionar mediante el desplegable el driver del pinpad.
Presionar "Siguiente".
Para conocer en Windows el puerto donde se encuentra conectado el pinpad, dirigirse a Panel de control > Administrador de dispositivos, desplegar el submenú "Puertos (COM y LPT)" y revisar el COM que aparece. Ejemplo: Verifone Terminal (COM9).
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, 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 |
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 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 |
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 |
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 |
VTOL_CRDB_CONF.cfg | Archivo creado y gestionado por la librería. Lo utiliza para persistir la configuración de VTOL |
vtolClient.properties | Contiene las propiedades de conexión con VTOL Server |
vtolDaoFactory.properties | Contiene la configuración de clases de acceso de datos. Uso interno de la librería. No se debe modificar |
workingKeys.properties | Registra las Working Key por tarjeta. La clave de cada WK es la posición de la llave maestra en la memoria del PINPAD |
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 |
4.4 Configuración de enlace con VTOL
EMVKIT 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 |
Nota: El código de la tienda y el código de la caja en donde se origina la transacción se informa en la operación de creación de sesión.
4.5 Configuración de PINPAD
EMVKIT se conecta al PINPAD modelo Verifone VX820 con Firmware.
Para lograr dicha conexión se debe configurar adecuadamente el puerto de comunicación COM donde está conectado el PINPAD.
La configuración relacionada con el PINPAD se encuentra en el archivo serialPinPad.properties. Entre las propiedades más importantes se pueden encontrar:
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. | |
Y01Tec | Tiempo entre comandos expresado en segundos (Formato: NNN). Es el tiempo máximo que el PINPAD espera el siguiente comando. | 035 |
firmwareVersion | Opcional. Indica la versión de compatibilidad de firmware con la que trabajará EMVKIT. | |
requiredInitAppVersions | Opcional (Solo para FD). Indica que versiones de compatibilidad de firmware requieren enviar mensaje de inicio al PINPAD | |
approveInSecondInstance | Opcional. Indica si EMVKIT permite que el PINPAD apruebe en segunda decisión, una transacción rechazada por el HOST. | True |
Ejemplo de configuración para el PINPAD de POSNET (FD)
#serie
#PPVX820POSNET.portName=COM3
#USB
PPVX820POSNET.portName=COM9
PPVX820POSNET.dataBits=7
PPVX820POSNET.stopBits=1
PPVX820POSNET.baudRate=115200
PPVX820POSNET.parity=EVEN
#Timeout por defecto en esperar la respuesta del Pinpad.
PPVX820POSNET.timeout=30000
PPVX820POSNET.timeoutMilisecondsWrite=150
PPVX820POSNET.language=1
#Tamaño XXXplica del buffer de lectura del puerto serie.
PPVX820POSNET.bufferSize=2048
PPVX820POSNET.nativeImpleClass=com.synthesis.vtolClientLib.deviceAdapters.RxTxSimpleSerialNativeLibWrapperImpl
#PPVX820POSNET.nativeImpleClass=com.synthesis.vtolClientLib.deviceAdapters.JavaCommSimpleSerialNativeLibWrapperImpl
#PPVX820POSNET.nativeImpleClass=com.synthesis.vtol.ar.client.test.pinpad.POSNETVx820VA0600PinpadEmulatorConnector
#PPVX820POSNET.nativeImpleClass=com.synthesis.vtol.ar.client.test.pinpad.POSNETVx8203DESPinpadEmulatorConnector
#Timeout entre comandos expresado en segundos / Formato: NNN
PPVX820POSNET.y01Tec=035
#Timeout Ingreso de Datos expresado en segundos / Formato: NNN
PPVX820POSNET.y06Tom=020
#Tiempo de espera luego de enviar un Y06 (en millisecs)
PPVX820POSNET.y06ProcessWait=1000
#Tiempo de espera para un ACK de respuesta (en millisecs)
PPVX820POSNET.ackResponseTimeout=1000
#Version de la XXXplicación del PINPAD
PPVX820POSNET.firmwareVersion=A0700
#Versiones de Firmware que requieren mensaje de inicialización (separadas por coma).
PPVX820POSNET.requiredInitAppVersions=A0600,A0700
#Indica si el aprobado en 2da. Decisión del PINPAD está habilitado
PPVX820POSNET.approveInSecondInstance=true
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 (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 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.
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 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 | O | 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. Leer Datos de la Tarjeta
Operación que inicia el pago con una tarjeta. Se utiliza para obtener los datos básicos de la misma leídos por medio del PINPAD.
Si la tarjeta está dentro de los bines de excepción, EMVKIT devolverá los datos leídos pero no realizará ningún otro tipo de procesamiento como reconocimiento de bin, tarjeta, etc.
Nota: Para el tratamiento de los bines de excepción, deberá también invocarse la operación "Procesar Operación con Tarjeta" con el objeto de obtener todos los datos correspondientes. |
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 de VTOL Server que se desea realizar en el campo 11 – trxType, sin incluir el campo el cual indica el monto.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashBack | ServicePayment | VoidServicePayment | SalePEI | RefundPEI | Descripción |
11 | trxType | Alfanumérico | X | X | X | X | X | X | X | X | X | Tipo de Transacción:
|
22 | authorizationCode | Alfanumérico | O | O | O | O | O | O | O | - | - | 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. Obligatorio solamente cuando la autorización fue aprobada telefónicamente |
24 | lastTrxId | Numérico | O | O | O | O | O | 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 | X | X | X | X | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 157 | customerDoc | Alfanumérico | - | - | - | - | - | - | - | X | - | Numero de documento del titular de la tarjeta |
| 161 | operationConcept | Numérico | - | - | - | - | - | - | - | O | - | Concepto por el cual se realiza la operación, valores posibles:
|
| 53 | idOperationPEI | Numérico | - | - | - | - | - | - | - | - | X | Identificador de la operación PEI de pago que se desea anular |
| 155 | cbu | Alfanumérico | - | - | - | - | - | - | - | - | O | Dato informado por el cliente sobre la cuenta destino de la devolución para tarjetas Banelco. Se debe informar el CBU o el Alias CBU. |
| 156 | cbuAlias | Alfanumérico | - | - | - | - | - | - | - | - | O | Dato informado por el cliente sobre la cuenta destino de la devolución para tarjetas Banelco |
| 12 | amount | Numérico | O | O | O | O | O | - | - | - | - | Requerido para operar con tarjetas Contactless. 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. |
| 54 | additionalAmount | Numérico | - | - | - | - | O | - | - | - | - | Requerido para operar con tarjetas Contactless con Cashback. Contiene el Importe del "CashBack". Se usa en transacciones del tipo SaleCashBack. Debe contener 12 dígitos como máximo. Los últimos dos representan los decimales. |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {25:20190401114640;2:1;1:1;11:Sale;0:1} |
Ejemplo de SalePEI
| Request: {161:1;157:32644050;25:20190122093125;11:SalePEI} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashBack | ServicePayment | VoidServicePayment | SalePEI | RefundPEI | Descripción |
10 | inputMode | Alfanumérico | X | X | X | X | X | X | X | X | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
1010 | currentSessionId | Numérico | X | X | X | X | X | X | X | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | X | X | X | X | X | X | X | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | X | X | X | X | X | X | X | X | Mensaje descriptivo del código de respuesta de la librería |
1102 | providers | Lista | X | X | X | X | X | X | X | X | 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 | X | X | X | X | X | X | 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” |
| 1104 | prefixesList | Lista | X | X | X | X | X | X | X | X | X | Lista que informa el/los prefijo/s, proveedor/es, si se admite cashback, el límite del monto cashback, si se permite operar offline y el límite del monto para operar offline de la tarjeta ingresada en el pinpad. Tener en cuenta que los últimos dos dígitos de los campos límite del monto cashback y límite del monto para operar offline corresponden a decimales |
1105 | panFirstDigit | Numérico | X | X | X | X | X | X | X | 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 | X | X | X | X | X | 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 | X | X | X | X | X | X | X | Valor de la tarjeta enmascarado según PCI |
1108 | isExceptionBin | Numérico | X | X | X | X | X | X | X | 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 | O | O | O | O | O | O | O | Si isExceptionBin = 1 entonces indica el nombre del bin de excepción |
1112 | CardHolderName | Alfanumérico | O | O | O | O | O | O | O | X | X | 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 | O | O | O | O | O | O | X | X | 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 | O | O | O | O | O | O | O | O | Código de banco si es una tarjeta Master |
1115 | serviceCode | Numérico | O | O | O | O | O | O | O | X | X | Código de servicio devuelto por el PINPAD, siempre que no sea ingreso manual |
1116 | recordNumber | Numérico | O | O | O | O | O | O | O | X | X | Número de registro donde se almacena la transacción en el PINPAD. Reservado para uso futuro |
1117 | ExceptionBinExtraData | Alfanumérico | O | O | O | O | O | O | O | X | - | Si isExceptionBin = 1 entonces indica información adicional que pudiera servir al POS |
Ejemplo
Response from Full library: {1103:20150827182503734;1102:{[PosCodeVI NameVisa PosTenderCodenull]};1010:27082015182500;1028:Ok;1027:000{*};1116:000001;1115:101;1114:072;1108:0;1107:450979******1495;1106:1495;1105:450979;1104:[{"start":"4","end":"4","provider":"MC","cashBackAllowed":1,"cashBackAmountLimit":"50000","offLineAllowed":1,"offlineAmountLimit":"90000"},{"start":"4","end":"4","provider":"VI","cashBackAllowed":0,"cashBackAmountLimit":"0","offLineAllowed":1,"offlineAmountLimit":"10000"}]} |
C. Cancelar Lectura de Tarjeta
Este comando procede a cancelar la operatoria posterior lectura de la tarjeta en el pinpad.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | cancel | 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:cancel} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | cancel | Descripció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: {1028:Ok;1027:000} |
D. 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 VTOL Server 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 "Leer Datos de la Tarjeta" (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 "Lectura de Datos de la Tarjeta", 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 de VTOL Server 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 | VoidSale | Refund | VoidRefund | SaleCashBack | ServicePayment | VoidServicePayment | SalePEI | RefundPEI | Descripción |
11 | trxType | Alfanumérico | X | X | X | X | X | X | X | X | X | Tipo de Transacción:
|
12 | amount | Importe | X | X | X | X | X | X | X | X | 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. Para operaciones PEI el monto tendrá un TOPE, el cual estará definido por LINK, quienes validan que no se supere por transacción el equivalente a un Salario Mínimo, Vital y Móvil. |
13 | currencyPosCode | Alfanumérico | X | X | X | X | X | X | X | X | X | Tipos de Moneda:
|
14 | payments | Numérico | X | X | X | X | X | X | X | - | - | Cantidad de cuotas. 2 dígitos como máximo |
15 | plan | Alfanumérico | X | X | X | X | X | X | X | - | - | Plan. 1 caracter de longitud |
16 | originalDate | Fecha | - | - | X | - | - | - | - | - | - | 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 | - | O | X | - | - | - | - | - | - | 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 | X | X | X | X | X | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
53 | paymentCondition | Alfanumérico | O | O | O | O | O | O | 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 | - | - | - | - | X | - | - | - | - | Contiene el Importe del "Cash Back". Se usa en transacciones del tipo SaleCashBack. Debe contener 12 dígitos como máximo |
70 | effectiveDate | Alfanumérico | O | O | O | O | O | O | O | - | - | Fecha efectiva. Se usa para AMEX con formato YYMM |
73 | interestAmount | Alfanumérico | O | O | O | O | O | O | 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 | O | O | O | O | O | O | - | - | Indica si puede recibir el número de cuenta (Visa y Posnet). Default = 0. Valores posible:
|
101 | differDate | Alfanumérico | O | O | O | O | O | O | O | - | - | Fecha diferida. Solo utilizada para AMEX |
118 | terminalCapability | Alfanumérico | O | O | O | O | O | O | O | - | - | Capacidad de captura. Valores 1 = Manual / 2 = Lectura de Banda / 5 = Lectura de Chip |
130 | posPeriod | Numérico | O | O | O | O | O | O | 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 | O | O | O | O | O | O | - | - | Indica Turno en que se realiza la operación. Solamente es registrado en VTOL. Longitud 2 |
132 | operatorCode | Alfanumérico | O | O | O | O | O | O | O | - | - | Código de operador. Solamente es registrado en VTOL. Longitud 20 |
133 | operatorName | Alfanumérico | O | O | O | O | O | O | O | - | - | Nombre de operador. Solamente es registrado en VTOL. Longitud 50 |
134 | sellerCode | Alfanumérico | O | O | O | O | O | O | O | - | - | Código del vendedor que realiza la operación. Solamente es registrado en VTOL. Longitud 20 |
135 | sellerName | Alfanumérico | O | O | O | O | O | O | O | - | - | Nombre del vendedor que realiza la operación. Solamente es registrado en VTOL. Longitud 50 |
136 | attentionMode | Alfanumérico | O | O | O | O | O | O | O | - | - | Modalidad de atención (AU ó AS). Longitud 2 |
1102 | provider | Alfanumérico | O | O | O | O | O | O | O | X | X | 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 | X | X | X | X | X | X | X | X | X | 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: {15:0;1103:20150827182503734;14:1;13:$;12:10000;11:Sale;25:20150828003911} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashBack | ServicePayment | VoidServicePayment | SalePEI | RefundPEI | Descripción |
| 0 | company | Numérico | X | X | X | X | X | X | X | X | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | X | X | X | X | X | X | X | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | X | X | X | X | X | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
| 6 | cardNumber | Numérico | O | O | O | O | O | O | O | - | - | Número de tarjeta en texto plano. Solo presente en Tarjeta de Excepción o Tarjetas de Empleados |
| 9 | track2 | Alfanumérico | O | O | O | O | O | O | O | - | - | Track2 de la tarjeta entero. Solo presente en Tarjeta de Excepción o Tarjetas de Empleados |
10 | inputMode | Alfanumérico | X | X | X | X | X | X | X | X | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
22 | authorizationCode | Alfanumérico | O | O | O | O | O | O | O | - | - | Código de autorización generado por el centro autorizador para la transacción cuando al transacción fue aprobada |
23 | authorizationMode | Alfanumérico | X | X | X | X | X | X | X | - | - | Modo de Autorización:
|
24 | lastTrxId | Numérico | X | X | X | X | X | 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 | X | X | X | X | X | 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 | X | X | X | X | X | X | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | X | X | X | X | X | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server |
28 | responseMessage | Alfanumérico | X | X | X | X | X | X | X | X | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
29 | serialNumber | Numérico | X | X | X | X | X | X | X | - | - | Número que identifica de la terminal lógica en la que se procesó la transacción |
30 | businessNumber | Numérico | X | X | X | X | X | X | X | - | - | Número de comercio en el que se procesó la transacción |
31 | lotNumber | Numérico | X | X | X | X | X | X | X | - | - | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | O | O | O | O | O | O | O | - | - | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo |
33 | creditCardIssuerName | Alfanumérico | O | O | O | O | O | O | O | - | - | Nombre del Centro emisor de la tarjeta |
34 | Name | Alfanumérico | O | O | O | O | O | O | O | - | - | Nombre del canal por el cual se autorizó la tarjeta |
35 | errorDescription | Alfanumérico | O | O | O | O | O | O | O | O | O | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
42 | lotDefinitionId | Numérico | X | X | X | X | X | X | X | - | - | Identificador de la definición de lote |
57 | accountType | Alfanumérico | O | O | O | O | O | O | O | - | - | Campo que se emplea para identificar el tipo de cuenta. Se usa para tarjetas de débito. Los valores posibles son:
|
58 | workingKey | Alfanumérico | O | O | O | O | O | O | O | O | O | VTOL devuelve este campo tal como lo entrega el Centro Autorizador. Representa la llave que el PINPAD deberá usar para generar el PINBLOCK en la próxima transacción |
| 59 | offlinePinCheck | Numérico | O | O | O | O | O | O | O | O | O | Informa si se verifica o no el Pin Offline con AMEX EMV. Valores posibles:
|
| 66 | track1 | Alfanumérico | O | O | O | O | O | O | O | - | - | Track1 de la tarjeta entero. Solo presente en Tarjeta de Excepción o Tarjetas de Empleados |
68 | rrn | Numérico | O | O | O | O | O | O | O | - | - | Reference referral number |
75 | accountNumber | Alfanumérico | O | O | O | O | O | O | O | - | - | Número de cuenta. Este campo es devuelto si el campo 74- requestAccountNumber fue activado en el requerimiento. Longitud 28. |
81 | responseAuth | Alfanumérico | O | O | O | O | O | O | 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 |
82 | softwareVersion | Alfanumérico | O | O | O | O | O | O | O | - | - | Versión de la aplicación |
130 | posPeriod | Numérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Periodo enviado por el POS. Longitud 5 |
131 | turn | Numérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Turno. Longitud 2 |
132 | operatorCode | Alfanumérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Código de operador. Longitud 20 |
133 | operatorName | Alfanumérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Nombre de operador. Longitud 50 |
134 | sellerCode | Alfanumérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Código del vendedor. Longitud 20 |
135 | sellerName | Alfanumérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Nombre del vendedor. Longitud 50 |
136 | attentionMode | Alfanumérico | O | O | O | O | O | O | O | - | - | [Opcional si viaja en la solicitud] Modalidad de atención (AU ó AS). Longitud 2 |
| 145 | exceptionBinName | Alfanumérico | O | O | O | O | O | O | O | - | - | Nombre de la tarjeta de Excepción. Solo presente en Tarjeta de Excepción o Tarjetas de Empleados |
166 | trxReferenceNumber | Numérico | X | X | X | X | X | X | X | - | - | Identificador único de la transacción en VTOL Server. Longitud entre 19 y 20 dígitos, debido a que utiliza el día como parte de formato. |
1010 | currentSessionId | Numérico | X | X | X | X | X | X | X | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | X | X | X | X | X | X | X | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | X | X | X | X | X | X | X | X | Mensaje descriptivo del código de respuesta de la librería |
| 1103 | cardContextId | Numérico | X | X | X | X | X | X | X | X | X | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. |
1110 | pinpadApplicationId | Alfanumérico | X | X | X | X | X | X | X | - | - | Identificador de la Aplicación del PINPAD. |
1111 | pinpadApplicationName | Alfanumérico | X | X | X | X | X | X | X | - | - | Nombre de la Aplicación del PINPAD. |
1112 | cardHolderName | Alfanumérico | O | O | O | O | O | O | O | X | X | Nombre del titular de la tarjeta si el track I está presente y la lectura fue por banda. |
1120 | voucherHeader | Mapa | O | O | O | O | O | O | O | - | - | [Opcional 1] Reservado para uso futuro. Retorna los datos del encabezado del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valor: [clave1|valor1, clave2|valor2,…, claveN|valorN] |
1121 | voucherFooter | Mapa | O | O | O | O | O | O | O | - | - | [Opcional 1] Reservado para uso futuro. Retorna los datos del pie del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valor: [clave1|valor1, clave2|valor2,…, claveN|valorN] |
1122 | voucherBody | Mapa | O | O | O | O | O | O | O | - | - | [Opcional 1] Reservado para uso futuro. Retorna el cuerpo del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valor: [clave1|valor1, clave2|valor2,…, claveN|valorN] |
1123 | formattedVoucher | Alfanumérico | O | O | O | O | O | O | O | - | - | [Opcional 2] Reservado para uso futuro. Retorna el voucher completo y formateado para ser impreso. |
1124 | printVoucher | Numérico | O | O | O | O | O | O | O | - | - | [Opcional 3] Reservado para uso futuro. Indica si la impresión del voucher tuvo éxito o no. Valores permitidos:
|
| 170 | idCommercePEI | Alfanumérico | - | - | - | - | - | - | - | X | X | Identificador PEI de compañía |
| 171 | idBranchPEI | Alfanumérico | - | - | - | - | - | - | - | X | X | Identificador PEI de local |
| 172 | idTerminalPEI | Alfanumérico | - | - | - | - | - | - | - | X | X | Identificador PEI de terminal |
| 153 | idOperationPEI | Alfanumérico | - | - | - | - | - | - | - | X | X | Identificador de la operación PEI de pago o devolución. |
| 154 | idOperationOrigenPEI | Alfanumérico | - | - | - | - | - | - | - | - | X | Identificador de la operación PEI de origen con la cual se solicitó la devolución. Sólo para RefundPEI |
| 278 | bankingRefNum | Alfanumérico | - | - | - | - | - | - | - | X | - | Numero de referencia de la transacción de pago. Se utiliza para conciliar con los reportes de las entidades bancarias. Número generado por LINK. Largo máximo 12. |
| 280 | clientCopyVoucher | Alfanumérico | X | X | X | X | X | X | X | - | - | Campo para imprimir copia al cliente. Valores posibles: False: imprimir copia al cliente sin consultarlo. |
| 281 | requiresSignature | Alfanumérico | X | X | X | X | X | X | X | - | - | Campo para solicitar firma al cliente. Valores posibles: False: no requerido |
| 1138 | emvData | Alfanumérico | O | O | O | O | O | O | O | - | - | Este campo sólo será retornado en operaciones CHIP con tarjetas Amex. Corresponden a datos del criptograma, los cuales deben ser impresos en el ticket. |
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
| Response from Full library: {10:MSR;42:101001;1028:Ok;1027:000;82:STS;34:Visa;81:,---esta es una prueba de impresion---|-------esta es la segunda linea-----|-------esta es la tercera linea------|-------esta es la cuarta linea------|-------esta es la quinta linea-------^;33:Visa;32:231;31:14;1112:GOMEZ/JUAN HORACIO ;30:123456788;1111:VISA CLASSIC;29:00000001;1110:A0000000031010;28:APROBADA;27:00;26:ISO8583;25:20150828003911;24:270;23:onLine;1010:28082015003859;22:123456;68:123456789012;110:false;2:1;1: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 con VTOL Server.
E. Procesar Mensaje Crédito Débito
Operación que permite enviar directamente un mensaje de Crédito Débito a VTOL Server.
En este tipo de operación no se realiza interacción con el PINPAD. El mensaje que se recibe desde el POS es enviado sin cambios a VTOL Server para su autorización. No se debe ejecutar previamente la operación de lectura de datos de la tarjeta.
Para poder procesar este tipo de mensajes debe incluirse en la mensajería información de la tarjeta, como ser los campos: número de tarjeta, fecha de expiración, código de seguridad, track2, etc. Además se debe indicar el modo de ingreso realizado: Manual o Banda.
EMVKIT valida si llega un mensaje Crédito Debito con el Número de Tarjeta o Track2. Si es así envía el mensaje directamente VTOL Server.
Mensajería
- Requerimiento:
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashBack | ServicePayment | VoidServicePayment | Descripción |
6 | cardNumber | Numérico | O | O | O | O | O | O | O | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. |
7 | expiration | Numérico | O | O | O | O | O | O | O | Formato YYMM Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
8 | Cvc | Numérico | O | O | O | O | O | O | O | Código de seguridad de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
9 | track2 | Alfanumérico | O | O | O | O | O | O | O | Track2 de la tarjeta entero (se envía todo el contenido del track2 en este campo) Este campo sólo está presente si la banda magnética / chip de la tarjeta pudo ser leído. |
10 | inputMode | Alfanumérico | X | X | X | X | X | X | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
11 | trxType | Alfanumérico | X | X | X | X | X | X | X | Tipo de Transacción:
|
12 | amount | Importe | X | X | X | X | X | X | 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 | X | X | X | X | X | X | Tipos de Moneda:
|
14 | payments | Numérico | X | X | X | X | X | X | X | Cantidad de cuotas. 2 dígitos como máximo |
15 | plan | Alfanumérico | X | X | X | X | X | X | X | Plan. 1 caracter de longitud |
16 | originalDate | Fecha | - | - | X | - | - | - | - | 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 | - | O | X | - | - | - | - | 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 | O | O | O | O | O | 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 |
22 | authorizationCode | Alfanumérico | O | O | O | O | O | O | O | 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 | O | O | O | O | 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 | X | X | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
53 | paymentCondition | Alfanumérico | O | O | O | O | O | O | 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 | - | - | - | - | X | - | - | Contiene el Importe del "Cash Back". Se usa en transacciones del tipo SaleCashBack. Debe contener 12 dígitos como máximo |
70 | effectiveDate | Alfanumérico | O | O | O | O | O | O | O | Fecha efectiva. Se usa para AMEX con formato YYMM |
73 | interestAmount | Alfanumérico | O | O | O | O | O | O | 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 | O | O | O | O | O | O | Indica si puede recibir el número de cuenta (Visa y Posnet). Default = 0. Valores posible:
|
101 | differDate | Alfanumérico | O | O | O | O | O | O | O | Fecha diferida. Solo utilizada para AMEX |
130 | posPeriod | Numérico | O | O | O | O | O | O | 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 | O | O | O | O | O | O | Indica Turno en que se realiza la operación. Solamente es registrado en VTOL. Longitud 2 |
132 | operatorCode | Alfanumérico | O | O | O | O | O | O | O | Código de operador. Solamente es registrado en VTOL. Longitud 20 |
133 | operatorName | Alfanumérico | O | O | O | O | O | O | O | Nombre de operador. Solamente es registrado en VTOL. Longitud 50 |
134 | sellerCode | Alfanumérico | O | O | O | O | O | O | O | Código del vendedor que realiza la operación. Solamente es registrado en VTOL. Longitud 20 |
135 | sellerName | Alfanumérico | O | O | O | O | O | O | O | Nombre del vendedor que realiza la operación. Solamente es registrado en VTOL. Longitud 50 |
136 | attentionMode | Alfanumérico | O | O | O | O | O | O | O | Modalidad de atención (AU ó AS). Longitud 2 |
1103 | cardContextId | Numérico | X | X | X | X | X | X | X | 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: {15:0;1103:20150827182503734;14:1;13:$;12:10000; 11:Sale;10:Manual;8:648;7:1905;6:4507990000977787;25:20150828003911} |
- Respuesta
Número | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashBack | ServicePayment | VoidServicePayment | Descripción |
| 0 | company | Numérico | X | X | X | X | X | X | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | X | X | X | X | X | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | X | X | X | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
22 | authorizationCode | Alfanumérico | O | O | O | O | O | O | O | Código de autorización generado por el centro autorizador para la transacción. |
23 | authorizationMode | Alfanumérico | X | X | X | X | X | X | X | Modo de Autorización:
|
24 | lastTrxId | Numérico | X | X | X | X | X | 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 | X | X | X | 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 | X | X | X | X | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | X | X | X | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server |
28 | responseMessage | Alfanumérico | X | X | X | X | X | X | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
29 | serialNumber | Numérico | X | X | X | X | X | X | X | Número que identifica de la terminal lógica en la que se procesó la transacción |
30 | businessNumber | Numérico | X | X | X | X | X | X | X | Número de comercio en el que se procesó la transacción |
31 | lotNumber | Numérico | X | X | X | X | X | X | X | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | O | O | O | O | O | O | O | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo |
33 | creditCardIssuerName | Alfanumérico | X | X | X | X | X | X | X | Nombre del Centro emisor de la tarjeta |
34 | hostName | Alfanumérico | O | O | O | O | O | O | O | Nombre del canal por el cual se autorizó la tarjeta |
35 | errorDescription | Alfanumérico | O | O | O | O | O | O | O | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
42 | lotDefinitionId | Numérico | X | X | X | X | X | X | X | Identificador de la definición de lote |
58 | workingKey | Alfanumérico | O | O | O | O | O | O | O | VTOL devuelve este campo tal como lo entrega el Centro Autorizador. Representa la llave que el PINPAD deberá usar para generar el PINBLOCK en la próxima transacción |
68 | rrn | Numérico | X | X | X | X | X | X | X | Reference referral number |
75 | accountNumber | Alfanumérico | O | O | O | O | O | O | O | Número de cuenta. Este campo es devuelto si el campo 74- requestAccountNumber fue activado en el requerimiento. Longitud 28. |
81 | responseAuth | Alfanumérico | O | O | O | O | O | O | 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 |
82 | softwareVersion | Alfanumérico | X | X | X | X | X | X | X | Versión de la aplicación |
130 | posPeriod | Numérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Periodo enviado por el POS. Longitud 5 |
131 | turn | Numérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Turno. Longitud 2 |
132 | operatorCode | Alfanumérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Código de operador. Longitud 20 |
133 | operatorName | Alfanumérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Nombre de operador. Longitud 50 |
134 | sellerCode | Alfanumérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Código del vendedor. Longitud 20 |
135 | sellerName | Alfanumérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Nombre del vendedor. Longitud 50 |
136 | attentionMode | Alfanumérico | O | O | O | O | O | O | O | [Opcional si viaje en la solicitud] Modalidad de atención (AU ó AS). Longitud 2 |
166 | trxReferenceNumber | Numérico | X | X | X | X | X | X | X | Identificador único de la transacción en VTOL Server. Longitud entre 19 y 20 dígitos, debido a que utiliza el día como parte de formato. |
1010 | currentSessionId | Numérico | X | X | X | X | X | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | X | X | X | X | X | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | X | X | X | X | X | X | Mensaje descriptivo del código de respuesta de la librería |
1110 | pinpadApplicationId | Alfanumérico | X | X | X | X | X | X | X | Identificador de la Aplicación del PINPAD. |
1111 | pinpadApplicationName | Alfanumérico | X | X | X | X | X | X | X | Nombre de la Aplicación del PINPAD. |
1112 | CardHolderName | Alfanumérico | O | O | O | O | O | O | O | Nombre del titular de la tarjeta si el track I está presente y la lectura fue por banda. |
1120 | voucherHeader | Mapa | O | O | O | O | O | O | O | [Opcional 1] Reservado para uso futuro. Retorna los datos del encabezado del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valor: [clave1|valor1, clave2|valor2,…, claveN|valorN] |
1121 | voucherFooter | Mapa | O | O | O | O | O | O | O | [Opcional 1] Reservado para uso futuro. Retorna los datos del pie del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valor: [clave1|valor1, clave2|valor2,…, claveN|valorN] |
1122 | voucherBody | Mapa | O | O | O | O | O | O | O | [Opcional 1] Reservado para uso futuro. Retorna el cuerpo del voucher. El valor recibido corresponde a un campo compuesto mapa con una serie de claves y valor: [clave1|valor1, clave2|valor2,…, claveN|valorN] |
1123 | formattedVoucher | Alfanumérico | O | O | O | O | O | O | O | [Opcional 2] Reservado para uso futuro. Retorna el voucher completo y formateado para ser impreso. |
1124 | printVoucher | Numérico | O | O | O | O | O | O | O | [Opcional 3] Reservado para uso futuro. Indica si la impresión del voucher tuvo éxito o no. Valores permitidos:
|
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
Response from Full library: {42:101001;1028:Ok;1027:000;82:STS;34:Visa;81:,---esta es una prueba de impresion---|-------esta es la segunda linea-----|-------esta es la tercera linea------|-------esta es la cuarta linea------|-------esta es la quinta linea-------^;33:Visa;32:231;31:14;1112:GOMEZ/JUAN HORACIO ;30:123456788;1111:VISA CLASSIC;29:00000001;1110:A0000000031010;28:APROBADA;27:00;26:ISO8583;25:20150828003911;24:270;23:onLine;1010:28082015003859;22:123456;68:123456789012;110:false;2:1;1: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 con VTOL Server.
F. Procesar Mensaje PEI sin PinPad
Operatoria para realizar Pagos Electrónicos Inmediatos (PEI) en los puntos de venta. Estos pagos inmediatos se efectúan con tarjetas de débito con banda magnética y se transfieren y acreditan de manera instantánea con un costo inferior a una venta tradicional.
En esta operación, EMV Kit no realiza una interacción con el pinpad y el mensaje recibido por el POS es enviado directamente a VTOL Server para su posterior autorización con Link. Tener en cuenta que no se deberá ejecutar previamente la operación "Leer Datos de la Tarjeta".
Las operaciones soportadas en EMV Kit para PEI son:
- SalePEI = Permite realizar un pago presencial PEI (transferencia bancaria).
- RefundPEI = Permite realizar una devolución (parcial o total) de un pago presencial PEI realizado con anterioridad.
- QueryPEI = Permite realizar una consulta de una operación de pago o de devolución que tuvo como respuesta el error "391 - Error en comunicación" para conocer si fue autorizada la operación y así obtener los datos de la misma por parte del centro autorizador. Este mensaje surge ya que hay una limitante por parte del autorizador que no existe un mecanismo de reversa de transacciones.
Nota: La operatoria PEI no posee tercer mensaje, por lo que cada operación queda automáticamente en estado "Commited" (comiteado). Tener en cuenta que al efectuar cierre de sesión (tipo de transacción closeSession), siempre deberá enviarse en el campo 1008 (closeSessionAction) el valor CLOSE.
Mensajería
- Requerimiento:
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | SalePEI | RefundPEI | QueryPEI | Descripción |
|---|---|---|---|---|---|---|
| 3 | server | Alfanumérico | X | X | X | Identificador del Server que procesará la transacción. Enviar "VTOL" |
8 | Cvc | Numérico | X | X | - | Código de seguridad de la tarjeta |
9 | track2 | Alfanumérico | X | X | X | Track2 de la tarjeta entero (se envía todo el contenido del track2 en este campo) |
10 | inputMode | Alfanumérico | X | X | X | Forma en que se ingresó/leyó la tarjeta. Valor posible:
|
11 | trxType | Alfanumérico | X | X | X | Tipo de Transacción:
|
12 | amount | Importe | X | 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 Para operaciones PEI el monto tendrá un TOPE, el cual estará definido por LINK, quienes validan que no se supere por transacción el equivalente a un Salario Mínimo, Vital y Móvil. |
13 | currencyPosCode | Alfanumérico | X | X | - | Tipos de Moneda:
|
25 | dateTime | Numérico | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. Es importante persistir este valor para consultar el resultado de una operación en caso de algún inconveniente |
| 66 | track1 | Alfanumérico | X | X | X | Track1 de la tarjeta entero (se envía todo el contenido del track1 en este campo) |
| 153 | idOperationPEI | Alfanumérico | - | X | - | Identificador de la operación PEI de pago que se desea devolver |
| 155 | cbu | Alfanumérico | - | O | - | CBU de la cuenta destino de la devolución asociada con la tarjeta Banelco. Si el dato se envía, el valor es validado por Link |
| 156 | cbuAlias | Alfanumérico | - | O | - | Alias del CBU de la cuenta destino de la devolución asociada con la tarjeta Banelco. Si el dato se envía, el valor es validado por Link |
| 157 | customerDoc | Alfanumérico | X | O | - | Número de documento del titular de la tarjeta |
158 | lastFourDigits | Numérico | X | X | - | Últimos 4 dígitos de la tarjeta. La solicitud de la validación de los últimos 4 dígitos de la tarjeta es configurable por prefijo |
| 161 | operationConcept | Numérico | O | - | - | Concepto por el cual se realiza la operación, valores posibles:
|
| 173 | dateTimeOriginalTrx | Numérico | - | - | X | Fecha y hora de realización de la transacción de venta o devolución que se desea consultar en formato YYYYMMDDHHMMSS. Se debe enviar el valor del campo 25 de la transacción a consultar |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to EMV Kit (SalePEI): Request: {158:9002;66:%b778899000000049002^apellido24/nombre24 ^371212000000000840;157:34000499;13:$;12:100;11:SalePEI;10:MSR;9:778899000000049002=371212000000000840;8:523;25:20180904131343;161:1;3:VTOL} Request to EMV Kit (RefundPEI): Request: {158:9002;66:%b778899000000049002^apellido24/nombre24 ^371212000000000840;157:34000499;156:alias;155:12345678945612345879;153:5439999999999999543;13:$;12:100;11:RefundPEI;10:MSR;9:778899000000049002=371212000000000840;8:523;25:20180904131400;3:VTOL} Request to EMV Kit (QueryPEI): Request: {10:MSR;9:778899000000049002=371212000000000840;173:20180904131400;25:20180904131915;11:QueryPEI;66:%b778899000000049002^apellido24/nombre24 ^371212000000000840;3:VTOL} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | SalePEI | RefundPEI | QueryPEI | Descripción |
|---|---|---|---|---|---|---|
| 0 | company | Numérico | X | X | X | Identificador de la compañía donde se generó la transacción. |
| 1 | store | Alfanumérico | X | X | X | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
25 | dateTime | Numérico | X | 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 | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para PEI |
28 | responseMessage | Alfanumérico | X | X | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
35 | errorDescription | Alfanumérico | X | X | X | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
153 | idOperationPEI | Alfanumérico | X | X | X | Identificador de la operación PEI de pago o de devolución |
| 154 | idOperationOrigenPEI | Alfanumérico | - | X | O | Identificador de la operación PEI de origen con la cual se solicitó la devolución |
| 170 | idCommercePEI | Alfanumérico | X | X | X | Identificador PEI de compañía |
| 171 | idBranchPEI | Alfanumérico | X | X | X | Identificador PEI de local |
| 172 | idTerminalPEI | Alfanumérico | X | X | X | Identificador PEI de terminal |
| 174 | originalTrxStatus | Numérico | - | - | O | Informa el estado de la transacción original en una operación de consulta. Si el campo en la respuesta no se recibe es porque la consulta falló. Puede contener uno de los siguientes valores:
|
| 278 | bankingRefNum | Alfanumérico | X | - | X | Numero de referencia de la transacción de pago. Se utiliza para conciliar con los reportes de las entidades bancarias. Número generado por LINK. Largo máximo 12. |
1010 | currentSessionId | Numérico | X | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | X | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería |
1028 | libResponseMessage | Alfanumérico | X | X | X | Mensaje descriptivo del código de respuesta de la librería |
Response from EMV Kit (SalePEI): Response message: {1:1;2:1;1027:000;1028:Ok;170:143;171:87;172:SYN001;1010:1536077609492;153:5439999999999999543;25:20180904131343;26:ISO8583;27:00;28:APROBADA} Response from EMV Kit (RefundPEI): Response message: {1:1;2:1;1027:000;1028:Ok;170:143;171:87;172:SYN001;1010:1536077609492;153:1969999999999999196;25:20180904131400;154:5439999999999999543;26:ISO8583;27:00;28:APROBADA} Response from EMV Kit (QueryPEI): Response message: {1:1;2:1;1027:000;1028:Ok;170:143;171:87;172:SYN001;174:0;1010:1536077952001;153:1969999999999999196;25:20180904131915;154:5439999999999999543;26:ISO8583;27:00;28:APROBADA} |
G. Procesar Mensaje QueryPEI con Pinpad
Este mensaje permite al POS realizar una consulta de una operación de pago o devolución PEI que obtuvo como respuesta el error "391 - Error en comunicación" para conocer si fue autorizada la operación y así obtener los datos de la misma por parte del centro autorizador. Este mensaje surge debido a una limitante por parte del autorizador, porque no existe un mecanismo de reversa de transacciones.
El mensaje queryPEI debe generarse dentro de la sesión del POS en la cual se realizó la operación de pago o devolución PEI, es decir que previamente se ejecutaron las operaciones de "Leer datos de tarjeta" y "Procesar operación con tarjeta". Esto se debe a que la consulta a Link se deben enviar los track 1 y 2 de la tarjeta.
- Requerimiento
Número | Nombre del campo | Tipo de dato | QueryPEI | 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 | Tipos de Transacciones:
|
| 25 | dateTime | Numérico | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 173 | dateTimeOriginalTrx | Numérico | X | Fecha y hora de realización de la transacción de venta o devolución que se desea consultar en formato YYYYMMDDHHMMSS. Se debe enviar el valor del campo 25 de la transacción a consultar. |
Ejemplo
| Request: {173:20190122093302;25:20190122093352;11:QueryPEI;0:1} |
- Respuesta
Número | Nombre del campo | Tipo de dato | QueryPEI | 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 |
| 25 | dateTime | Numérico | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. Es importante persistir este valor para consultar el resultado de una operación en caso de algún inconveniente. |
| 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 | Numérico | X | Mensaje de la Respuesta con la descripción ISO-8583 del Centro Autorizador relacionado con el código del campo 27. |
| 153 | idOperationPEI | Alfanumérico | X | Identificador de la operación PEI de pago o devolución. |
| 154 | idOperationOrigenPEI | Alfanumérico | X | Identificador de la operación PEI de origen con la cual se solicitó la devolución. |
| 170 | idCommercePEI | Alfanumérico | X | Identificador PEI de compañía |
| 171 | idBranchPEI | Alfanumérico | X | Identificador PEI de local |
| 172 | idTerminalPEI | Alfanumérico | X | Identificador PEI de terminal |
| 174 | originalTrxStatus | Numérico | X | Informa el estado de la transacción original en una operación de consulta. Si el campo en la respuesta no se recibe es porque la consulta falló. Puede contener uno de los siguientes valores:
|
| 278 | bankingRefNum | Alfanumérico | X | Numero de referencia de la transacción de pago. Se utiliza para conciliar con los reportes de las entidades bancarias. Número generado por LINK. Largo máximo 12. |
| 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 Error <> 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 message: {0:1;1:1;2:1;1027:000;1028:Ok;170:143;171:SYN1;172:SYN001;174:0;1010:1553778037824;153:100442;25:20190328100306;26:ISO8583;27:00;28:APROBADA} |
H. Impresión de Vouchers
Este comando tiene como funcionalidad la solicitud de firma digital en el dispositivo pinpad, y la impresión de vouchers o comprobantes de pago. La solicitud de firma digital queda restringida a los dispositivos con firmware A0808 o superior de los dispositivos de First Data.
Las transacciones que se pueden imprimir son compras, anulaciones, devoluciones, compra con cashback, anulación de compra con cashback, devolución de compra con cashback. Con los tipos de ingreso manual, banda y chip.
Los comprobantes digitales tienen la posibilidad de ser guardados en EMVKit y luego ser enviado VTOL Server. Para las transacciones que no resulten aprobadas, se podrá imprimir un cupón físico, pero no se guardará comprobante digital.
La guarda de los cupones se realizará en base a los siguientes escenarios del campo requestSignature:
- requestSignature = 1: Solicita firma digital y genera comprobante digital.
- requestSignature distinto de 1: No genera comprobante digital.
Importante
Esta funcionalidad se encuentra disponible para los pinpad de First Data, a partir del firmware A0808.
En el archivo devices.properties de EMVKIT se debe habilitar el siguiente driver: pinPad_driver=com.synthesis.vtol.ar.client.devices.posnet.PinpadVx820A0808PosnetDriver
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | PrintTrxVoucher | Descripció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. Es importante persistir este valor para consultar el resultado de una operación en caso de algún inconveniente |
| 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. Es el valor devuelto por la última operación "Leer Datos Tarjeta" |
| 1118 | voucherParameters | Mapa | X | Se informa con el siguiente formato [copyCount|nroCopia] la cantidad de copias a efectuar del comprobante, donde:
|
| 1130 | requestSignature | Numérico | X | Se informa si se solicitará o no la firma en el Pinpad. Valores posibles:
Importante: En caso de no solicitar firma digital (opciones 0 y 2), no se genera el archivo .POS (del comprobante) por lo que no se tendrá constancia del mismo en VTOL Server. |
| 1131 | voucherHeader | Mapa | O | Se informa la leyenda del header del comprobante con el siguiente formato [headerNro|detalle,...,headerNro|detalle], donde Nro es un número del 1 al 5 y detalle es la leyenda a imprimir. El largo máximo para cada línea es de 40 caracteres |
| 1132 | clientDNI | Alfanumérico | O | DNI del cliente. Valor hasta 9 caracteres |
| 1133 | billNumber | Numérico | O | Número de la factura. Valor hasta 11 caracteres |
| 1134 | voucherPromoMessage | Mapa | O | Se informa el mensaje de promoción con el siguiente formato [promotionalNro|detalle,...,promotionalNro|detalle], donde Nro es un número del 1 al 7 y detalle es la leyenda de promoción a imprimir. El largo máximo para cada línea es de 28 caracteres Nota: A partir del firmware 810 de FirstData, se podrá enviar o el campo 1134 - voucherPromoMessage o el campo 1135 - voucherPromoLine |
| 1135 | voucherPromoLine | Alfanumérico | O | Se informa la promoción obtenida. Valor hasta 40 caracteres Nota: A partir del firmware 810 de FirstData, se podrá enviar o el campo 1134 - voucherPromoMessage o el campo 1135 - voucherPromoLine |
| 1136 | billType | Alfanumérico | O | Tipo de factura. Valor hasta 1 caracter |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {1103:20190115143308991;1118:[copyCount|1];11:PrintTrxVoucher;1136:B;1135:Vale Otro!;1134:[promotional1|**************************,promotional2| Gracias por utilizar,promotional3| nuestros Servicios,promotional4| Esperamos su regreso,promotional5| El presente voucher,promotional6| no contiene premios,promotional7|**************************];1133:1235456;1132:123456789;1131:[header1| ******************************,header2| ** NAPSE **,header3| ******************************,header4|Conectate con la evolucion del Retail,header5|-------------------------------------];1130:1;2:1;25:20190115143332;1:1} |
- Respuesta
Número | Nombre del campo | Tipo de dato | PrintTrxVoucher | Descripción |
| 1010 | currentSessionId | Numérico | X | Identificador de la 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 |
| 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. Es el valor devuelto por la última operación "Leer Datos Tarjeta" |
Ejemplo
Response from Full library: {1010:1547573567858;1027:000;1028:Ok;1103:20190115143308991} |
I. Impresión Libre
Este comando tiene como funcionalidad la libre impresión y formateo de comprobantes por parte del punto de venta.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Print | Descripció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. Es importante persistir este valor para consultar el resultado de una operación en caso de algún inconveniente |
| 1137 | printContent | Base 64 | X | Texto en plano codificado en base 64 con el siguiente formato: XXNN ***************************** Donde XX indican el formato de la línea, valores posibles:
El texto por linea es de hasta 40 caracteres cuando no es doble ancho, seguido de un salto de línea. Lineas permitidas: 30 |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to Full library: {1137:MDJOTiAgICAgKioqKioqKioqKioqKioqKioqKioqKioqKioqKiogICAgIA0KMDJOTiAgICAgICAg ICAgIEFWSVNPIERFIFBSRU1JTyAgICAgICAgICAgIA0KMDJOTiAgICAgKioqKioqKioqKioqKioq KioqKioqKioqKioqKiogICAgIA0KMjBOTg0KMDFOTlNZTlRIRVNJUyBMQUJPUkFUT1JJTyAxICAt ICA1OTcwNDAwMDQ0NzENCjAxTk4gICAgICAgICAgICAgICAgMjMvMTAvMTcgICAgICAgICAgICAg ICANCjIwTk4NCjIwTk4NCjAxTk4gICAgICAgICAgICAgICBQUk9NT0NJT04gICAgICAgICAgICAg ICAgICAgICAgDQowMU5OICAgICAgICAgICAgIFBFTDFQVE9ERVZFTlRBICAgICAgICAgICAgDQoy ME5ODQowMU5OICAgRkVMSUNJVEFDSU9ORVMsIFVTVEVEIFNFIEhBIEdBTkFETyAgDQowMU5OICAg WFlYIEgySCBQRUwgMSAtIFBSRU1JTyBDT01JRU5aQSBZICAgDQowMU5OICAgICAgVEVSTUlOQSBD T04gLSBQRUwgMSBIMkggWFlYICAgICAgDQoyME5ODQowM05OICAgICAgICAgICBDT0RJR08gREVM IFBSRU1JTyAgICAgICAgICAgDQowMU5OICAgICAgICAgIDc5MTQyNyBCIC0gMDAwMzU2MjIgICAg ICAgICAgDQoyME5OICAgDQoyME5OICAgDQowMU5OICBQQVJBIENBTkpFQVIgU1UgUFJFTUlPIFBS RVNFTlRFIEVTVEUgDQowMU5OVkFMRSBBIENVQUxRVUlFUiBWRU5ERURPUiBERSBFU1RFIExPQ0FM DQoyME5ODQoyME5ODQowMU5OUkVDSUJJIENPTkZPUk1FOg0KMTBOTg0KMjBOTg0KMjBOTg0KMjBO Tg==;25:20190115143513;11:Print} |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | Descripción | |
| 1010 | currentSessionId | Numérico | X | Identificador de la 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 |
| 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. Es el valor devuelto por la última operación "Leer Datos Tarjeta" |
Ejemplo
Response from Full library: {1010:1547573567858;1027:000;1028:Ok;1103:20190115143513} |
J. Procesar Mensaje Billeteras Electrónicas
VTOL se integra con las siguientes billeteras electrónicas para permitir efectuar pagos en los puntos de venta:
- Mercado Pago: La plataforma de pagos online más importante de América Latina
Las operaciones soportadas en VTOL Server para Billeteras electrónicas son:
- SaleWallet = Permite realizar una compra presencial con billetera
- RefundWallet = Permite realizar una devolución (parcial o total) de una compra presencial con billetera realizada con anterioridad
- QuerySaleWallet = Permite realizar una consulta de una operación de compra con billetera para conocer si la misma fue autorizada y así obtener los datos de la misma por parte del Autorizador
Procedimiento para Mercado Pago
El proceso de pagos con billetera virtual se realizará de la siguiente manera:
- Se inicia con el envío de una orden de venta (transacción SaleWallet) por parte del POS a VTOL.
- Recién en ese momento el comprador podrá efectuar la lectura del código QR impreso en la caja mediante su smartphone.
- Mercado Pago, con la información de la orden de venta recibida por VTOL, le comunicará a la app de la billetera virtual el importe total y el detalle de los artículos adquiridos.
- El comprador visualizará en su app mobile el detalle de la compra, y efectuará el pago seleccionado el medio de pago (tarjeta, o saldo de Mercado Pago), la tarjeta enrolada (o incorporando una nueva), las cuotas y confirmando el pago.
- El POS recibirá la respuesta de la transacción SaleWallet a través de VTOL, quien informará si la operación resultó autorizada por Mercado Pago.
- Puede darse el caso que VTOL responda "Consulte el pago por tiempo expirado". Este escenario puede surgir cuando el cliente demora en confirmar el pago desde su app mobile, y expira el tiempo designado por defecto en VTOL, entonces al POS se le da una respuesta automática por timeout. Para conocer el resultado de la operación, el POS deberá realizar una consulta (transacción QuerySaleWallet). Las respuestas del QuerySaleWallet pueden ser las siguientes:
- VTOL responde "Aprobado". Indica que el pago fue autorizado por Mercado Pago. El paso siguiente del POS es confirmar o cancelar la transacción, con un tercer mensaje.
- VTOL responde "Pago Rechazado, desea seguir esperando?". Indica que el cliente intentó pagar pero Mercado Pago rechazó el pago, pero a su vez el cliente puede volver a intentar realizar el pago con otra tarjeta u otro medio de pago, por lo cual el POS puede "seguir esperando" para permitirle al cliente intentar pagar nuevamente, y luego el POS deberá enviar un nuevo QuerySaleWallet, o directamente cancelar la operación.
- Puede darse el caso que VTOL responda "Consulte el pago por tiempo expirado". Este escenario puede surgir cuando el cliente demora en confirmar el pago desde su app mobile, y expira el tiempo designado por defecto en VTOL, entonces al POS se le da una respuesta automática por timeout. Para conocer el resultado de la operación, el POS deberá realizar una consulta (transacción QuerySaleWallet). Las respuestas del QuerySaleWallet pueden ser las siguientes:
- Por último, el POS deberá confirmar la operación, mediante el cierre de sesión (en estado Close).
Para obtener de forma completa todo el detalle de la transacción, posterior venta, el POS deberá enviar de forma automática la transacción QuerySaleWallet.
La anulación, no precisa de interacción por parte del comprador en la caja. Simplemente el POS envía el identificador del número de pago del Autorizador en el mensaje RefundWallet.
Procedimiento para operar cashout con Mercado Pago
Se podrán realizar las siguientes operaciones:
Ventas
- Ventas de productos y retiro de efectivo
- En estos casos, se aprueban ambas cosas. No es posible obtener aprobaciones parciales.
Devoluciones
- Realizar devoluciones de los productos y del cashout.
- Operación de venta con productos y cashout. Permite devolver en una misma transacción, lo siguiente:
- Devolución total de los productos y del cashout
- Devolución parcial de los productos, y devolución total del cashout
- Devolución total o parcial solo de los productos
- Devolución total solo del cashout
- Varias devoluciones parciales de los productos
- Operación de venta sólo con productos. Permite devolver en una misma transacción, lo siguiente:
- Devolución total o parcial de los productos
- Varias devoluciones parciales de los productos
- Operación de venta con productos y cashout. Permite devolver en una misma transacción, lo siguiente:
- En la operación de devolución parcial de productos, se permiten efectuar varias devoluciones parciales de un pago. Se pueden realizar hasta 20 devoluciones parciales a un mismo pago. VTOL valida que no se supere el monto de la venta.
- La devolución de cashout siempre debe ser por el monto total.
Anulaciones
- Una vez recibida la respuesta de operación Aprobada por parte de Mercado Pago, se puede realizar lo siguiente:
- Para una venta con productos y cashout. Permite anular:
- Los productos y el cashout, todo junto. Esto se logra enviando un UnSyncCompletion=rollback
- Para una venta sólo con productos. Permita anular:
- Todos los productos. Esto se logra enviando un UnSyncCompletion=rollback.
- Para una venta con productos y cashout. Permite anular:
- No es posible realizar anulaciones intermedias.
- Requerimiento
Referencias:
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | SaleWallet | RefundWallet | QuerySaleWallet | Descripción |
|---|---|---|---|---|---|---|
11 | trxType | Alfanumérico | X | X | X | Tipo de Transacción:
|
12 | amount | Importe | X | 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 Nota: El importe debe ser el número correspondiente a la moneda informada |
13 | currencyPosCode | Alfanumérico | X | X | - | Tipos de moneda:
Nota: En el punto de venta se deberá informar la moneda de la cuenta vendedor de Mercado Pago (si el retailer posee una cuenta argentina en Mercado Pago entonces tendrá que informar la moneda $ -pesos argentinos-) Importante: Tener en cuenta que operando con Mercado Pago siempre debe coincidir el país de la cuenta vendedor con el país de la cuenta comprador |
| 16 | originalDate | Numérico | - | X | X | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD |
| 24 | lastTrxId | Numérico | O | O | O | Utilizado cuando está activo el control transaccional. En este campo el POS debe enviar la última transacción procesada correctamente. |
25 | dateTime | Numérico | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 54 | additionalAmount | Importe | O | O | - | Contiene el Importe del "Cashout". 12 dígitos como máximo. Valor entero. Los últimos 2 dígitos corresponden a los decimales. Para devoluciones, se debe enviar el monto total del cashout. Para devolver sólo el cashout, se debe enviar el campo 12 (amount) con valor 0. Sólo disponible para billetera de Mercado Pago. |
| 268 | walletPosTrxId | Alfanumérico | X | - | O | Identificador único de la transacción de billetera para la compañía. Es originado por el POS para realizar una compra con billetera Formato: Opcional en QuerySaleWallet: Se informa este campo o el campo walletPaymentId para localizar una transacción de compra |
| 269 | walletType | Numérico | X | X | X | Tipo de billetera por la cual se cursará la transacción en el POS. Opciones: 1: Mercado Pago |
| 270 | posTicket | Base 64 | X | - | - | Información del ticket en formato xml y posteriormente transformado en Base 64. Ver sección Estructura del campo posTicket |
| 271 | walletPaymentId | Alfanumérico | - | X | O | Identificador del número de pago informado por el Autorizador en el campo 271 de la respuesta de la operación SaleWallet Opcional en QuerySaleWallet: Se informa este campo o el campo walletPosTrxId para localizar una transacción de compra |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
Request to VTOL (SaleWallet): Request: {270:PG1lc3NhZ2U+CiAgICAgICA8aXRlbS1hZGQgc2VxPSIxIiBjb2RlPSIwMDAxIiBkaXNjb3VudGFibGU9InRydWUiIHVuaXRwcmljZT0iMjUuMCIgcXR5PSIxLjAiIGxldmVsMT0iTUVOIiBsZXZlbDI9IkNBU1VBTCIgc3VwcGxpZXI9IiIgYnJhbmQ9IkxFVklTIiB4cHJpY2U9IjI1LjAiIG1hZ25pdHVkZT0iMS4wIiBkZXNjcmlwdGlvbj0iSmVhbiBjYXN1YWwiIGN1cnJlbmN5PSIkIiAvPgogICAgICAgPGl0ZW0tYWRkIHNlcT0iMiIgY29kZT0iMDAwMiIgZGlzY291bnRhYmxlPSJ0cnVlIiB1bml0cHJpY2U9IjI4LjAiIHF0eT0iMi4wIiBsZXZlbDE9Ik1FTiIgbGV2ZWwyPSJDQVNVQUwiIHN1cHBsaWVyPSIiIGJyYW5kPSJMRVZJUyIgeHByaWNlPSI0OC4wIiBtYWduaXR1ZGU9IjEuMCIgZGVzY3JpcHRpb249IkplYW4gY2FzdWFsIiBjdXJyZW5jeT0iJCIgLz4KPC9tZXNzYWdlPg==;269:1;268:1120181116055713;13:$;12:1200;11:SaleWallet;4:DATA;3:VTOL;2:1;25:20181116055713;71:True;1:1} Request to VTOL (RefundWallet): Request: {271:4379999999999999437;269:1;16:20181116;13:$;12:1200;11:RefundWallet;4:DATA;3:VTOL;2:1;25:20181116105619;71:True;1:1} Request to VTOL (QuerySaleWallet): Request: {271:2289999999999999228;269:1;16:20190214;268:11020190514050534;25:20190214050534;11:QuerySaleWallet} |
Estructura del campo posTicket
El mensaje con la estructura del ticket estará en XML. El elemento raíz de ese mensaje XML deberá ser la etiqueta <message>, siendo la misma lo que se llamará encabezado.
La manera de ejecutar un comando es utilizando una etiqueta con la forma <elemento-comando>. El elemento "item" identifica a los artículos. De esta manera, si se desea, por ejemplo, agregar un nuevo artículo el comando a utilizar será <item-add>. En el cuerpo del mensaje podrá contener uno, ninguno o varios de estos comandos.
Cada uno de los comandos que se envían posee diversos atributos, los cuales identifican al elemento que se está enviando y definen diversas propiedades que poseen los mismos. Poseerá un número de secuencia, el cual identifica cada elemento unívocamente:
Propiedad | Tipo de dato | Descripción | Requerido |
|---|---|---|---|
seq | Entero positivo | Número identificador único del elemento dentro de la transacción. | Sí |
Cada comando posee una serie de atributos que definirán las distintas propiedades del elemento que se está agregando (además del número de secuencia antes mencionado).
Para el elemento ítem, los atributos serán los siguientes:
Elemento | Atributo | Tipo de dato | Descripción | Requerido | Valor ante ausencia |
|---|---|---|---|---|---|
Ítem | unitprice | Numérico positivo | Precio unitario del artículo en cuestión. | Si | |
xprice | Numérico positivo | Precio extendido del artículo en cuestión. Es igual a la cantidad por el precio unitario. | Si | ||
qty | Entero positivo | Cantidad de artículos en la línea. | Si | ||
magnitude | Numérico positivo | Si el artículo es mensurable por otro unidad que no sea la cantidad, deberá ser expresad en esta propiedad. | No | 0 | |
code | Alfanumérico | Código propio del artículo. | No | "-" | |
brand | Alfanumérico | Marca del artículo. | No | "-" | |
supplier | Alfanumérico | Proveedor al que pertenece el artículo. | No | "-" | |
discountable | Alfanumérico | Si el artículo es puede recibir descuentos o no. | No | "-" | |
level1 | Alfanumérico | Nivel 1 de categorización del artículo. Anteriormente este nivel se conocía con el nombre de Departamento. | No | "-" | |
level2 | Alfanumérico | Nivel 2 de categorización del artículo. Anteriormente este nivel se conocía como la Familia del artículo. | No | "-" | |
level3 | Alfanumérico | Nivel 3 de categorización del artículo. Anteriormente este nivel se conocía como la Categoría del artículo. | No | "-" | |
level4 | Alfanumérico | Nivel 4 de categorización del artículo. Anteriormente este nivel se conocía como la subcategoría del artículo. | No | "-" | |
| description | Alfanumérico | Descripción del ítem | Si | ||
| currency | Alfanumérico | Moneda utilizada en el precio del ítem Nota: En el punto de venta se deberá informar la moneda de la cuenta vendedor de Mercado Pago (si el retailer posee una cuenta argentina en Mercado Pago entonces tendrá que informar la moneda $ -pesos argentinos-). | Si | ||
| measure | Alfanumérico | Unidad de medida del ítem. Valores posibles: unit - pack | No | "unit" |
Ejemplo
<message> |
- Respuesta
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | SaleWallet | RefundWallet | QuerySaleWallet | Descripción |
|---|---|---|---|---|---|---|
| 0 | company | Numérico | X | X | X | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | X | X | X | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
| 12 | amount | Importe | X | - | X | Monto de la transacción. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
| 13 | currencyPosCode | Alfanumérico | - | - | X | Tipos de moneda:
|
| 14 | payments | Numérico | - | - | O | Cantidad de cuotas seleccionadas al momento de realizar el pago QR. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago |
| 22 | authorizationCode | Alfanumérico | X | - | X | Código de autorización informado por el Autorizador |
| 24 | trxId | Numérico | X | X | X | Identificador de la transacción |
25 | dateTime | Numérico | X | 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 | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | Código de Respuesta emitido por el centro autorizador. 3 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para Billeteras Electrónicas |
28 | responseMessage | Alfanumérico | X | X | X | Mensaje de la Respuesta relacionado con el código del campo 27 |
| 54 | additionalAmount | Importe | O | O | O | Contiene el Importe del "Cashout". Para aquellas operaciones realizadas con retiro de efectivo. Valor entero. Los últimos 2 dígitos corresponden a los decimales. Sólo disponible para billetera de Mercado Pago. |
| 140 | paymentType | Numérico | - | - | X | Tipo de pago. Valores posibles: 0: Tarjeta |
| 142 | providerName | Alfanumérico | - | - | O | Proveedor de la tarjeta seleccionada al momento de efectuar el pago QR. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago |
| 166 | trxReferenceNumber | Numérico | X | X | - | Identificador único de la transacción en VTOL Server. Longitud entre 19 y 20 dígitos, debido a que utiliza el día como parte de formato |
271 | walletPaymentId | Alfanumérico | X | - | X | Identificador del número de pago informado por el Autorizador |
| 272 | amountRefunded | Importe | - | - | X | Monto devuelto en la transacción |
| 273 | paymentStatus | Alfanumérico | - | - | X | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
| 274 | paymentStatusDetail | Alfanumérico | - | - | X | Detalle del estado de la transacción de pago informado por el Autorizador |
| 275 | cardType | Numérico | - | - | O | Tipo de tarjeta seleccionada al momento de efectuar el pago QR. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago. Valores posibles: 0: Débito |
| 1010 | currentSessionId | Numérico | X | X | X | Identificador de la sesión |
| 1027 | libResponseCode | Numérico | X | X | X | Código de respuesta de la librería. |
| 1028 | libResponseMessage | Alfanumérico | X | X | X | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo
Response from VTOL (SaleWallet): Response message: {1:1;2:1;1027:000;1028:Ok;166:14021905052200000204;271:2289999999999999228;1010:1550131493463;22:1234567;24:121;25:20190214050518;26:ISO8583;27:00;28:APROBADA} Response from VTOL (RefundWallet): Response message: {1:1;2:1;1010:1550131493463;1027:000;1028:Ok;25:20190214050543;26:ISO8583;27:509;28:Estado trx original no acepta devolucion} Response from VTOL (QuerySaleWallet): Response message: {1:1;2:1;1027:000;1028:Ok;6:450995xxxxxx3704;140:0;12:53.0;13:$;14:1;142:visa;271:2289999999999999228;272:0.0;273:0;274:accredited;1010:1550131493463;275:1;22:1234567;24:121;25:20190214050534;26:ISO8583;27:00;28:APROBADA} |
Tener en cuenta
Si la respuesta de un mensaje QuerySaleWallet retorna con código 514 ("Tiempo expirado. Elija Consultar o Cancelar pago") el POS al aplicar la acción "Cancelar" sobre dicho mensaje, deberá enviar un mensaje de sincronización a EMVKit, sin incluir el id de transacción de la operación saleWallet. De esa manera EMVKit podrá sincronizar contra VTOL Server y este enviará una cancelación de la orden de compra contra la billetera virtual que se esté operando.
Ver mensaje de sincronización de transacciones
K. Procesar Mensaje Cuenta DNI
Operatoria para realizar pagos en los Puntos de Venta utilizando como medio de pago un código de barras o token generado por una aplicación mobile del Banco Provincia. Una operación con CuentaDNI es una operación PEI, salvo que el modo de ingreso será diferente, ya que no se utilizará ningún tipo de tarjeta. El cliente deberá informar al cajero del POS el código generado por la aplicación mobile. Las operaciones serán presenciales.
Las operaciones PEI (Pago Electrónico Inmediato) se transfieren desde la cuenta del cliente a la cuenta del retailer y se acreditan de manera instantánea.
En esta operación, EMV Kit no realiza una interacción con el pinpad y el mensaje recibido por el POS es enviado directamente a VTOL Server para su posterior autorización con Link. Tener en cuenta que no se deberá ejecutar previamente la operación "Leer Datos de la Tarjeta".
Las operaciones soportadas en EMV Kit para Cuenta DNI son:
- SalePEI = Permite realizar un pago presencial con Cuenta DNI, utilizando código de barras o softToken
- RefundPEI = Permite realizar una devolución (parcial o total) de un pago presencial con Cuenta DNI realizado con anterioridad.
- QueryPEI = Permite realizar una consulta de una operación de pago o de devolución que obtuvo como respuesta el error "391 - Error en comunicación" o una respuesta de timeout. Este mensaje surge ya que hay una limitante por parte del autorizador que no existe un mecanismo de reversa de transacciones.
Estados de operaciones:
Cuando las transacciones de Cuenta DNI sean aprobadas por el autorizador LINK, el estado de las operaciones quedarán en estado "Commit".
Reintentos
VTOL no efectuará ni manejará reintentos de solicitudes. En caso de que la autorización por parte de LINK no se haya realizado, VTOL no reintentará enviar el request de pago/devolución, sino que le informará al POS la situación de error, denegación o falla. El POS será el responsable de efectuar el reintento.
Reversos
La operación de reversa automática en Link no existe.
Mensajería
Referencias
X = Obligatorio
O = Opcional
- = No requerido
- Requerimiento
Número | Nombre del campo | Tipo de dato | SalePEI | RefundPEI | QueryPEI | Descripción |
|---|---|---|---|---|---|---|
| 3 | server | Alfanumérico | X | X | X | Identificador del Server que procesará la transacción. Enviar "VTOL" |
10 | inputMode | Alfanumérico | X | X | X | Forma de ingreso:
|
11 | trxType | Alfanumérico | X | X | X | Tipo de Transacción:
|
12 | amount | Importe | X | X | - | Monto de la transacción de Venta o de Devolució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 Se validará el importe enviado por el POS:
|
13 | currencyPosCode | Alfanumérico | X | X | - | Tipos de Moneda:
|
25 | dateTime | Numérico | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. Es importante persistir este valor para consultar el resultado de una operación en caso de algún inconveniente |
| 153 | idOperationPEI | Alfanumérico | - | X | O | Identificador de operación Cuenta DNI PEI de pago que se desea devolver o consultar. |
| 157 | customerDoc | Alfanumérico | O | - | - | Número de documento del titular de la cuenta. Obligatorio junto con softToken, únicamente si el modo de ingreso es softToken. |
| 173 | dateTimeOriginalTrx | Numérico | - | - | X | Fecha y hora de realización de la transacción de venta o devolución que se desea consultar en formato YYYYMMDDHHMMSS. Se debe enviar el valor del campo 25 de la transacción a consultar. |
| 279 | softToken | Alfanumérico | O | - | - | Token generado por la app mobile. Este token se lo informa el cliente al cajero, para que sea ingresado en el POS. Obligatorio junto con customerDoc, únicamente si el modo de ingreso es softToken. |
| 300 | barCode | Alfanumérico | O | - | - | Código generado por la app mobile. Este código se lo informa el cliente al cajero, para que sea ingresado en el POS. Obligatorio únicamente si el modo de ingreso es barCode. |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
- Respuesta
Número | Nombre del campo | Tipo de dato | SalePEI | RefundPEI | QueryPEI | Descripción |
|---|---|---|---|---|---|---|
| 0 | company | Numérico | X | X | X | Identificador de la compañía donde se generó la transacción. |
| 1 | store | Alfanumérico | X | X | X | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
| 25 | dateTime | Numérico | X | 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 | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para PEI |
28 | responseMessage | Alfanumérico | X | X | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
35 | errorDescription | Alfanumérico | X | X | X | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
153 | idOperationPEI | Alfanumérico | X | X | X | Identificador de la operación PEI de pago o de devolución |
| 154 | idOperationOrigenPEI | Alfanumérico | - | X | O | Identificador de la operación original de pago. |
| 170 | idCommercePEI | Alfanumérico | X | X | X | Identificador PEI de compañía |
| 171 | idBranchPEI | Alfanumérico | X | X | X | Identificador PEI de local |
| 172 | idTerminalPEI | Alfanumérico | X | X | X | Identificador PEI de terminal |
| 174 | originalTrxStatus | Numérico | - | - | O | Informa el estado de la transacción original en una operación de consulta. Si el campo en la respuesta no se recibe es porque la consulta falló. Puede contener uno de los siguientes valores:
|
| 278 | bankingRefNum | Alfanumérico | X | X | X | Número de referencia de la transacción de pago. |
1010 | currentSessionId | Numérico | X | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | 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 | X | Mensaje descriptivo del código de respuesta de la librería |
L. Procesar Mensaje Promociones PEI
Operatoria que permite al Punto de Venta (POS) informar promociones sobre una operación de pago PEI, e informar la devolución de un pago PEI sujeto a promoción.
Actualmente la funcionalidad de Promociones PEI estará vinculada únicamente con transacciones realizadas por CuentaDNI.
Para realizar un mensaje de Promociones PEI, se debe haber realizado previamente un pago y contar con los datos de idOperacion y nroReferenciaBancaria que son devueltos por Link cuando una operación resulta Aprobada.
Las operaciones soportadas en EMV Kit para Promociones PEI son:
- promoPEI = Permite informar una promoción sobre una operación de pago PEI, y permite informar una devolución de un pago PEI que fue sujeto a promoción.
Sólo será requerido informar Promociones PEI en caso que se realice una venta PEI con productos que tengan promociones.
Cómo informa el POS una Promoción
Luego de realizar una operación de Pago PEI, el POS deberá informar (en caso que aplique) la promoción sobre ese pago. Informará en el campo amount el monto original de la venta y en el campo promoAmount la sumatoria del importe de los productos sujetos a promoción. Si el pago completo está sujeto a promoción, el promoAmount será igual al amount. Si sólo una porción del pago está sujeta a promoción, entonces promoAmount será solamente el importe sujeto a promoción. El cálculo de la promoción lo realizará LINK.
Este mecanismo se ideó para el caso que los comercios tengan solo algunos productos sujetos a promoción, entonces se informará a LINK la porción del pago al cual aplicar promoción.
Cómo informa el POS una Devolución de un pago sujeto a Promoción
Luego de realizar una devolución de un pago PEI, el POS deberá informar (en caso que aplique) la promoción que se aplicó a los productos de esa devolución. Informará en el campo amount la sumatoria del importe de los productos a devolver y en el campo promoAmount la sumatoria del importe de los productos a devolver que fueron informados como promoción en el pago.
Mensajería
Referencias
X = Obligatorio
O = Opcional
- = No requerido
- Requerimiento
Número | Nombre del campo | Tipo de dato | PromoPei | Descripción |
|---|---|---|---|---|
| 3 | server | Alfanumérico | X | Identificador del Server que procesará la transacción. Enviar "VTOL" |
11 | trxType | Alfanumérico | X | Tipo de Transacción:
|
| 301 | originalTrxType | Alfanumérico | X | Identificador del Tipo de Promoción que se está informando. Valores posibles: "1" para Pagos con promociones y "2" para Devoluciones de pagos con promoción. |
12 | amount | Importe | X | Monto total de la transacción original de venta, debe ser el mismo valor. 12 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. |
| 13 | currencyPosCode | Alfanumérico | X | Tipos de Moneda:
|
302 | promoAmount | Importe | X | Importe para informar una promoción o para informar la devolución de un pago con promoción. En donde los últimos 2 dígitos serán los decimales. Puede ser igual al importeOperacion (amount), en el caso en que todo el importe del pago esté sujeto a promoción. Pero no puede superar el importeOperacion. Para informar una Promoción en una Venta, se informará la sumatoria del importe de los productos sujetos a promoción. Si el pago completo está sujeto a promoción, el PromoAmount será igual a amount. El mismo comportamiento se aplicará para informar la Devolución de un pago sujeto a promoción. Se informará la suma del importe de los productos que fueron sujetos a promoción en la venta. |
25 | dateTime | Numérico | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. Es importante persistir este valor para consultar el resultado de una operación en caso de algún inconveniente |
| 153 | idOperationPEI | Alfanumérico | X | Identificador de operación PEI de pago que devuelve Link en la respuesta del pago. |
| 278 | bankingRefNum | Alfanumérico | X | Número de referencia bancaria de la operación de pago. Es devuelta por Link en la operación de pago. |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
- Respuesta
Número | Nombre del campo | Tipo de dato | PromoPei | 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 |
25 | dateTime | Numérico | 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 | 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. Ver sección Códigos de Respuesta de VTOL Server para PEI |
28 | responseMessage | Alfanumérico | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
35 | errorDescription | Alfanumérico | X | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
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 |
M. 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. |
1010 | currentSessionId | Numérico | X | Identificador de la sesión actual |
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: |
N. Procesar Mensaje Tarjeta Contactless
Mensajería que permite realizar operaciones con tarjetas Contactless, leídas por el pinpad de First Data. También será posible operar con cualquier modo de ingreso: Manual, Banda y Chip.
Sólo compatible con tarjetas Mastercard y Pinpad de First Data firmware A809R02 o superior.
Mensajería
Referencias
X = Obligatorio
O = Opcional
- = No requerido
- Requerimiento
| Nro. | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashback | Descripción |
|---|---|---|---|---|---|---|---|---|
| 11 | trxType | Alfanumérico | X | X | X | X | X | Tipo de Transacción:
|
| 22 | authorizationCode | Alfanumérico | O | O | O | O | O | Código de autorización telefónica. 6 dígitos como máximo. Obligatorio solamente cuando la autorización fue aprobada telefónicamente. No disponible para operaciones por Contactless. |
| 24 | lastTrxId | Numérico | O | O | O | 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 | X | X | X | Fecha y hora de realización de la transacción, en formato: YYYYMMDDHHMMSS |
| 12 | amount | Numérico | X | X | X | X | X | 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 | X | X | X | X | X | Tipos de Moneda:
|
| 54 | additionalAmount | Alfanumérico | - | - | - | - | X | Contiene el Importe del "Cash Back". Se usa en transacciones del tipo SaleCashBack. Debe contener 12 dígitos como máximo. Los últimos dos representan los decimales. |
| 14 | payments | Numérico | O | O | O | O | O | Cantidad de cuotas. 2 dígitos como máximo Si no tiene cuotas, el valor por defecto es 1. |
| 15 | plan | Alfanumérico | O | O | O | O | O | Plan. 1 caracter de longitud |
| 16 | originalDate | Fecha | - | - | X | - | - | 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 | - | O | X | - | - | 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. |
| 73 | interestAmount | Alfanumérico | O | O | O | O | 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. |
| 1102 | provider | Alfanumérico | O | O | O | O | O | Proveedor/tarjeta seleccionada por el POS. |
Los valores de compañía, tienda y caja serán obtenidos de la sesión.
Ejemplo
| Request to Full library: {15:0;14:1;13:$;12:1500;54:2500;11:Sale;1102:VI;2:1;25:20190808093818;1:1;0:1} |
- Respuesta
| Nro. | Nombre del campo | Tipo de dato | Sale | VoidSale | Refund | VoidRefund | SaleCashback | Descripción |
|---|---|---|---|---|---|---|---|---|
| 0 | company | Numérico | X | X | X | X | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Alfanumérico | X | X | X | X | X | Identificador del sitio originador de la transacción |
2 | node | Numérico | X | X | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
10 | inputMode | Alfanumérico | X | X | X | X | X | Forma en que se ingresó/leyó la tarjeta. Valores posibles:
|
22 | authorizationCode | Alfanumérico | O | O | O | O | O | Código de autorización generado por el centro autorizador para la transacción cuando la transacción fue aprobada. |
23 | authorizationMode | Alfanumérico | X | X | X | X | X | Modo de Autorización:
|
24 | lastTrxId | Numérico | X | X | X | 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 | X | 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 | X | X | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | X | X | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server |
28 | responseMessage | Alfanumérico | X | X | X | X | X | Mensaje de la Respuesta ISO-8583 relacionado con el código del campo 27 |
29 | serialNumber | Numérico | X | X | X | X | X | Número que identifica la terminal lógica en la que se procesó la transacción. |
30 | businessNumber | Numérico | X | X | X | X | X | Número de comercio en el que se procesó la transacción |
31 | lotNumber | Numérico | X | X | X | X | X | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | O | O | O | O | O | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo |
33 | creditCardIssuerName | Alfanumérico | O | O | O | O | O | Nombre del Centro emisor de la tarjeta |
34 | hostName | Alfanumérico | O | O | O | O | O | Nombre del canal por el cual se autorizó la tarjeta |
35 | errorDescription | Alfanumérico | O | O | O | O | O | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es “Error” |
42 | lotDefinitionId | Numérico | X | X | X | X | X | Identificador de la definición de lote |
57 | accountType | Alfanumérico | O | O | O | O | O | Campo que se emplea para identificar el tipo de cuenta. Se usa para tarjetas de débito. Los valores posibles son:
|
58 | workingKey | Alfanumérico | O | O | O | O | O | VTOL devuelve este campo tal como lo entrega el Centro Autorizador. Representa la llave que el PINPAD deberá usar para generar el PINBLOCK en la próxima transacción |
68 | rrn | Numérico | O | O | O | O | O | Número de referencia de recuperación |
75 | accountNumber | Numérico | O | O | O | O | O | Número de cuenta. Este campo es devuelto si el campo 74- requestAccountNumber fue activado en el requerimiento |
81 | responseAuth | Alfanumérico | O | O | O | O | 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 |
82 | softwareVersion | Alfanumérico | O | O | O | O | O | Versión de la aplicación |
166 | trxReferenceNumber | Numérico | X | X | X | X | X | Identificador único de la transacción en VTOL Server. Longitud entre 19 y 20 dígitos, debido a que utiliza el día como parte de formato. |
1010 | currentSessionId | Numérico | X | X | X | X | X | Identificador de la sesión actual |
1027 | libResponseCode | Numérico | X | X | X | 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 | X | X | X | Mensaje descriptivo del código de respuesta de la librería |
| 1103 | cardContextId | Numérico | X | X | X | X | X | Identifica el contexto de la tarjeta. Es un valor de referencia a la tarjeta leída a través del PINPAD. |
1110 | pinpadApplicationId | Alfanumérico | X | X | X | X | X | Identificador de la Aplicación del PINPAD. |
1111 | pinpadApplicationName | Alfanumérico | X | X | X | X | X | Nombre de la Aplicación del PINPAD. |
1112 | cardHolderName | Alfanumérico | O | O | O | O | O | Nombre del titular de la tarjeta si el track I está presente y la lectura fue por banda. |
| 280 | clientCopyVoucher | Alfanumérico | X | X | X | X | X | Campo para imprimir copia al cliente. Valores posibles: False: imprimir copia al cliente sin consultarlo. |
| 281 | requiresSignature | Alfanumérico | X | X | X | X | X | Campo para solicitar firma al cliente. Valores posibles: False: no requerido |
O. Sincronizar transacciones
Mensaje que permite sincronizar el estado de las operaciones entre la aplicación de punto de venta y la librería EMVKIT. Se utilizará cuando está activo el control transaccional.
El POS puede utilizar este mensaje luego de recibir una respuesta de operación aprobada por parte de la librería. Enviará el ID de la última transacción procesada correctamente. Internamente EMVKIT se sincroniza con VTOL Server, confirmando o reversando la transacción.
Este mensaje podrá ser utilizado para confirmar o cancelar una transacción antes de hacer un cierre de sesión con EMVKit. Es una alternativa al control transaccional, pero si no se usa el Synchronize, se debe usar el mecanismo tradicional de control transaccional.
A continuación se detallan dos ejemplos de aplicación de este mensaje.
1. Dos ventas distintas dentro de la misma sesión:
- Se crea sesión
- Se realiza una venta con Mercado Pago y el resultado es Aprobado. trxId 10
- El POS envía un Synchronize con id 10. Lo cual confirma dicha transacción.
- Se realiza otra venta con Mercado Pago y el resultado es Rechazado por MP. trxId 11
- El POS envía un Synchronize con lastTrxId 10. En ese momento la transacción 11 es reversada tanto en VTOL como en MP.
- La venta que no pudo ser realizada con Mercado Pago, se realiza con tarjeta de crédito. La cual finaliza Aprobada. trxId 12
- Se realiza una venta con Mercado Pago y el resultado es Aprobado. trxId 10
- Se cierra sesión informando los id {10, 12}.
2. Una misma venta con pagos parciales. Una parte se paga con tarjeta de crédito y la otra parte con Mercado Pago.
- Se crea sesión
- Una parte de la venta se paga con tarjeta de crédito y el resultado es Aprobado. trxId 20
- El POS envía un Synchronize con id 20. Lo cual confirma dicha transacción.
- La otra parte de la venta se paga con Mercado Pago y el resultado es Rechazado por MP. trxId 21
- El POS envía Synchronize con lastTrxId 20. En ese momento la transacción 21 es reversada tanto en VTOL como en MP.
- La parte de la venta que no pudo ser pagada con Mercado Pago, se realiza con tarjeta de débito. La cual finaliza Aprobada. trxId 22
- Una parte de la venta se paga con tarjeta de crédito y el resultado es Aprobado. trxId 20
- Se cierra sesión informando los id {20, 22}.
Mensajería
- Requerimiento
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | synchronize | Descripció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 |
| 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) |
Ejemplo:
Request to Full library: {25:20200310110302;24:55;11:synchronize}
- Respuesta
Número | Nombre del campo | Tipo de dato | synchronize | Descripció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: {1028:Ok;1027:000}
P. Cerrar Sesión
Permite cerrar la sesión entre la aplicación de punto de venta y EMVKIT.
Internamente EMVKIT se sincroniza con VTOL Server, 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
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
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 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.
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 VTOL Server y que debe capturarse el valor del campo 24 (lastTrxId) para ser enviado en el cierre de sesión:
24 | lastTrxId |
5.4 Integraciones para operar con tarjetas Contactless
Importante
Únicamente se podrá operar con Pinpad de First Data con firmware A809R02 o superior. Se debe configurar en EMVKit el Driver de la versión de Firmware A809.
En el archivo devices.properties se debe habilitar el siguiente driver: pinPad_driver=com.synthesis.vtol.ar.client.devices.posnet.PinpadVx820A0809PosnetDriver
El sistema POS podrá integrar operaciones con tarjetas Contactless, de dos formas posibles:
5.4.1 Interacción única con el POS
En los casos de una única interacción, el POS deberá enviar los campos correspondientes a la tradicional segunda interacción con el POS, EmvKit evaluará si se envía los campos:
- Amount
- AdditionalAmount (Opcional)
- Currency
- Payment
- Plan
- Provider (Opcional)
En este tipo de implementación, EmvKit activará el pinpad con todos los modos de ingreso.
Luego de realizar el ingreso de la tarjeta por el pinpad (puede ser en cualquier modo, incluyendo Contactless), se realizarán las evaluaciones correspondientes con el prefijo, ruteo de la transacción y no volverá interactuar nuevamente con el pinpad ni con el POS. En la respuesta de EMVKit se obtendrá el resultado final de la operación.
Limitante:
- En caso de querer operar con cashback, dicho monto debe enviarse sin conocer si la tarjeta lo tiene habilitado y sin conocer los límites permitidos.
5.4.2 Interacción doble con el POS
En los casos de doble interacción, el POS deberá enviar el importe de la operación, y pudiendo o no enviar el importe de cashback. Luego en la segunda interacción, el importe de la operación podrá ser modificado, debido a la aplicación de descuentos o intereses sobre cuotas.
En este tipo de implementación, si se envían los montos en la primer interacción, EmvKit activará el pinpad con todos los modos de ingreso.
Si el POS envía el monto cashback en la primer interacción, deberá enviar el mismo monto cashback en la segunda interacción, caso contrario EMVKit rechazará la transacción. Si el POS no envía el monto cashback en la primer interacción, y el modo de ingreso es distinto de Contactless, EMVKit permitirá ingresar un monto cashback en la segunda interacción, validando los límites del mismo.
Si el POS no envía los montos de la operación en la primer interacción, EMVKit manejará doble interacción con el POS (flujo tradicional: lectura y procesamiento), pero no se podrá utilizar lectura Contactless.
Limitante:
- En caso de querer operar con cashback, dicho monto debe enviarse sin conocer si la tarjeta lo tiene habilitado y sin conocer los límites permitidos.
- En caso de querer operar con cashback, dicho monto debe enviarse igual en las dos interacciones. Si EMVKIT responde que el monto cashback excede el límite, se rechazará la operación y se deberá iniciar nuevamente con el monto correcto.
Importante
En las transacciones con lectura Contactless, EMVKit responderá al POS campos con información sobre la impresión de copia del cliente y la firma del cliente. Dichos campos son: clientCopyVoucher y requiresSignature
clientCopyVoucher (Consulta por copia para cliente)
Si el valor es "false", imprimir copia al cliente sin consultarlo. Si el valor es "true", consultar al cliente si quiere copia del voucher.
requiresSignature (Solicita firma del cliente en el ticket)
Si el valor es "false", no se deberá solicitar firma del cliente. Si el valor es "true", se deberá solicitar firma al cliente.
El manejo de los resultado de estos campos, para la utilización de impresión de voucher por parte del pinpad de First Data, queda bajo responsabilidad del sistema del POS.
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. |
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.2 Códigos de Respuesta de VTOL Server
La respuesta que el POS recibe de VTOL se encuentra en los siguientes campos:
- Campo 27: Código de Respuesta ISO
- Campo 28: Descripción de la Respuesta ISO
A continuación se detallan las respuestas posibles con una breve descripción de cada una:
Código | Descripción |
|---|---|
'00' | Aprobada |
'01' | Pedir autorización telefónica |
'02' | Pedir autorización |
'03' | Comercio inválido |
'04' | Capturar tarjeta |
'05' | Denegada |
'07' | Retenga y llame |
'11' | Aprobada |
'12' | Transacción inválida |
'13' | Monto inválido |
'14' | Tarjeta inválida |
'25' | No existe original |
'30' | Error en formato |
'38' | Excede ingreso de PIN |
'43' | Retener tarjeta |
'45' | No opera en cuotas |
'46' | Tarjeta no vigente |
'47' | PIN requerido |
'48' | Excede máximo de cuotas |
'49' | Error fecha de vencimiento |
'50' | Entrega supera límite |
'51' | Fondos insuficientes |
'53' | Cuenta inexistente |
'54' | Tarjeta vencida |
'55' | PIN incorrecto |
'56' | Tarjeta no habilitada |
'57' | Transacción no permitida |
'58' | Servicio inválido |
'61' | Excede límite |
'65' | Excede límite de tarjeta |
'76' | Llamar al emisor |
'77' | Error plan/cuotas |
'85' | Aprobada |
'86' | No envía fecha original |
'89' | Terminal inválida |
'91' | Emisor fuera de línea |
'94' | Número de secuencia duplicado |
'95' | Re-transmitiendo |
'96' | Error en sistema |
'98' | No aprobada |
'99' | Error no clasificado |
Modo de ingreso inválido | |
Proveedor inválido | |
Error CVC | |
Error creando mensaje | |
Tipo de mensaje inválido | |
No envía código de autorización | |
Error en fecha efectiva | |
Error en fecha vencimiento | |
Tarjeta no efectiva | |
No opera off-line | |
Devolución monto mayor | |
Original ya anulada | |
Original ya devuelta | |
Original reversada | |
Moneda inválida | |
No envía fecha | |
Campo 71 inválido | |
Campo 71 nulo | |
CVC inválido | |
Tarjeta inválida | |
Track2 inválido | |
No envía moneda | |
No envía CVC | |
Timeout | |
Fecha original inválida | |
No envía ticket original | |
Ticket original inválido | |
No envía código de autorización de venta referida | |
Reintente | |
Chiptokens Invalido | |
Pinpad R. Cod. Error | |
Pinpad A. Cod. Error |
6.2.1 Códigos de Respuesta de VTOL Server para PEI
A continuación se detallan las respuestas posibles de VTOL Server, cuando se opera con PEI, con una breve descripción de cada una:
Código | Descripción |
|---|---|
| 00 | APROBADA |
| 300 | Se agoto el tiempo de espera |
| 301 | La sucursal ingresada es incorrecta |
| 302 | El concepto ingresado es incorrecto |
| 303 | El concepto ingresado no esta disponible |
| 304 | El concepto ingresado no esta habilitado |
| 305 | La cuenta destino del pago es incorrecta |
| 306 | La cuenta destino no esta habilitada |
| 307 | La cuenta origen del pago es incorrecta |
| 308 | La cuenta origen no esta habilitada |
| 309 | La Red destino del pago es incorrecta |
| 310 | La cuenta del comercio es incorrecta |
| 311 | La cuenta de la sucursal es incorrecta |
| 312 | El comercio supero el importe máximo |
| 313 | La sucursal supero el importe máximo |
| 314 | La tarjeta ha superado el importe diario |
| 315 | Comercio ha superado el importe diario |
| 316 | Comercio ha superado el importe mensual |
| 317 | Comercio supero las trxs diarias |
| 318 | Comercio supero las trxs mensuales |
| 319 | La sucursal supero el importe diario |
| 320 | La sucursal supero el importe mensual |
| 321 | La sucursal supero las trxs diarias |
| 322 | La sucursal supero las trxs mensuales |
| 323 | Encriptacion incorrecta |
| 324 | El DNI no coincide con el de la tarjeta |
| 325 | Los datos de tarjeta no se condicen |
| 326 | El comercio es invalido |
| 327 | Cuenta destino del comercio es invalida |
| 328 | La tarjeta es invalida |
| 329 | La referencia de trx ya fue utilizada |
| 330 | El importe no es un numero mayor a cero |
| 331 | Ultimos 4 dig. no coinciden con la tarj. |
| 332 | Tarjeta inhabilitada para operar |
| 333 | Tarjeta vencida |
| 334 | Fondos insuficientes |
| 335 | El CBU Banelco ingresado es incorrecto |
| 336 | El ALIAS CBU Banelco es incorrecto |
| 337 | El id de pago es invalido |
| 338 | El id del canal es invalido |
| 339 | Importe excede saldo remanente del pago |
| 340 | El ID de requerimiento es invalido |
| 341 | IP de cliente invalida |
| 342 | Existe una devolucion aprobada del pago |
| 343 | El pago tiene devoluciones parciales |
| 344 | Pago no admite el tipo de devolucion |
| 345 | Pago no admite el tipo de devolucion |
| 346 | Terminal en uso |
| 347 | Terminal PEI Invalida |
| 348 | Comercio PEI Invalido |
| 349 | Sucursal PEI Invalida |
| 350 | Id operacion Requerido |
| 351 | Id operacion Rango invalido |
| 352 | Ultimos cuatro digitos invalidos |
| 353 | Numero de documento requerido |
| 354 | Trx original no se puede devolver |
| 355 | La cuenta es incorrecta |
| 356 | La cuenta no está habilitada |
| 357 | La cuenta del comercio es incorrecta |
| 358 | La cuenta de la sucursal es incorrecta |
| 359 | Comercio supero monto para concepto |
| 360 | Sucursal supero monto para concepto |
| 361 | Tarjeta supero monto tipo de operacion |
| 362 | Comercio supero monto tipo operacion |
| 363 | Comercio supero monto tipo operacion |
| 364 | Comercio supero cantidad transacciones |
| 365 | Comercio supero cantidad transacciones |
| 366 | Sucursal supero monto diario permitido |
| 367 | Sucursal supero monto mensual permitido |
| 368 | Sucursal supero cantidad trxs diarias |
| 369 | Sucursal supero cantidad trx mensuales |
| 370 | Error al desencriptar campos encriptados |
| 371 | La cuenta destino del comercio invalida |
| 372 | Ref de trx del comercio ya fue utilizada |
| 373 | Ultimos 4 digitos incorrectos |
| 374 | El ID de requerimiento enviado invalido |
| 375 | Error General |
| 376 | Concepto ingresado no habilitado |
| 377 | Concepto ingresado no habilitado |
| 378 | Cuenta es incorrecta |
| 379 | Cuenta no está habilitada |
| 380 | ALIAS CBU red Banelco es incorrecto |
| 381 | El pago tiene devoluciones parciales |
| 382 | Esta operacion no acepta devol. total |
| 383 | Esta operacion no acepta devol. parcial |
| 384 | La fecha es invalida |
| 385 | El estado del pago es invalido |
| 386 | El Concepto Operacion es invalido |
| 387 | Estado trx original no acepta devolucion |
| 388 | Importe devolucion supero monto limite |
| 389 | No se encontró la trx original |
| 390 | No es posible devolver una devolución |
| 391 | Error en comunicación |
| 392 | Campo DateTimeOriginalTrx invalido |
| 393 | Autorizacion Original en Proceso |
| 600 | El codigo de barras es requerido |
| 601 | El softToken es requerido |
| 602 | El importe de promoción es invalido |
| 603 | Original transaction type es requerido |
| 604 | El numero de referencia bancaria es requerido |
| 605 | El importe original informado es invalido |
| 606 | La venta original no tiene promoción aplicada |
| 607 | El numero de referencia bancaria es incorrecto |
| 608 | La venta original no permite promoción |
| 609 | Clave DNI inválido |
6.2.2 Códigos de Respuesta de VTOL Server para Billeteras Electrónicas
A continuación se detallan las respuestas posibles de VTOL Server, cuando se opera con Billeteras Electrónicas, con una breve descripción de cada una:
| Código | Descripción |
|---|---|
| 00 | APROBADA |
| 500 | No se encuentra la transaccion original |
| 501 | El campo WalletPosTrxId es requerido |
| 502 | El campo WalletType es requerido |
| 503 | No esta configurado una Compañia MP |
| 504 | No esta configurado una Caja MP |
| 505 | El tipo de billetera es invalido |
| 506 | El campo WalletPaymentId es requerido |
| 507 | El campo OriginalDate es requerido |
| 508 | No es posible devolver una devolucion |
| 509 | Estado trx original no acepta devolucion |
| 510 | Importe devolucion supero monto limite |
| 511 | No se pudo realizar la orden de pago |
| 512 | La transaccion no posee estado |
| 513 | El campo posTicket es requerido |
| 514 | Tiempo expirado. Elija Consultar o Cancelar pago |
| 515 | Tiempo expirado confirmacion devolucion |
| 516 | No se encuentra el pago original |
| 517 | Estado trx original no acepta devolucion |
| 518 | No se encuentra la devolucion |
| 519 | Acceso a MP no esta autorizado |
| 520 | Accion a MP no esta autorizada |
| 521 | El campo WalletPosTrxId es invalido |
| 523 | Estado trx original no acepta devolucion |
| 524 | Importe invalido para devolucion |
| 525 | Estado trx original no acepta devolucion |
| 526 | Compañia MP no permite operar |
| 527 | Numero devoluciones parciales superados |
| 528 | El pago es antiguo para ser devuelto |
| 529 | No es posible devolver una devolucion |
| 530 | Compañia MP sin dinero para devolver |
| 531 | Compañia MP sin dinero disponible |
| 532 | Estado trx original no acepta devolucion |
| 533 | Devolucion parcial no soportada |
| 534 | Url de notificacion invalido |
| 535 | El monto de la transaccion es invalido |
| 536 | Error general por parte de MP |
| 537 | No se encuentra la transaccion original |
| 538 | El campo WalletPosTrxId es requerido |
| 539 | Devuelto |
| 540 | Pendiente |
| 541 | Autorizado |
| 542 | En Progreso |
| 543 | En mediacion |
| 544 | Rechazado |
| 545 | Cancelado |
| 546 | Contracargo |
| 547 | No se encontró la trx original |
| 548 | Error en comunicación |
| 549 | No existe comunicación con Mercado Pago |
| 550 | Error al consultar venta original online |
| 552 | Orden no generada por Todo Pago |
| 553 | Pago Rechazado por parte de TodoPago |
| 554 | Esta operación requiere autorización |
| 555 | Esta operación requiere autorización |
| 556 | Pago rechazado, reintente con otro medio de pago |
| 557 | Pago rechazado, reintente con otro medio de pago |
| 558 | Pago rechazado, reintente con otro medio de pago |
| 559 | Pago rechazado, reintente con otro medio de pago |
| 560 | Pago rechazado, reintente con otro medio de pago |
| 561 | No fue posible procesar su pago, intente más tarde |
| 562 | No fue posible procesar su pago, intente más tarde |
| 563 | No fue posible procesar su pago, intente más tarde |
| 564 | No fue posible procesar su pago, intente más tarde |
| 565 | No fue posible procesar su pago, intente más tarde |
| 566 | La cantidad de cuotas seleccionada es inválida |
| 567 | La cantidad de cuotas seleccionada es inválida |
| 568 | Tarjeta de crédito vencida |
| 569 | Tarjeta de crédito no habilitada |
| 570 | Fondos insuficientes, reintente otro medio de pago |
| 571 | Fondos insuficientes, reintente otro medio de pago |
| 572 | Datos incorrectos, revíselos y reintente |
| 573 | Datos incorrectos, revíselos y reintente |
| 574 | No fue posible procesar su pago, intente más tarde |
| 575 | No fue posible procesar su pago, intente más tarde |
| 576 | Tarjeta no vigente, reintente otro medio de pago |
| 577 | Esta operación requiere autorización |
| 578 | No fue posible procesar su pago, intente más tarde |
| 579 | No fue posible procesar su pago, intente más tarde |
| 580 | La cantidad de cuotas seleccionada es inválida |
| 581 | Datos incorrectos, revíselos y reintente |
| 582 | Datos incorrectos, revíselos y reintente |
| 583 | Las cuotas informadas son incorrectas |
| 584 | No existe la compra que se desea anular |
| 585 | El originante no es válido |
| 586 | El comercio informado es inválido |
| 587 | El establecimiento informado es inválido |
| 588 | El establecimiento no pertenece al comercio |
| 589 | El punto de venta informado es inválido |
| 590 | El punto de venta no pertenece al establecimiento |
| 591 | El tipo de documento es inválido |
| 592 | Se debe informar el ID de la operación |
| 593 | Se debe informar un timeStamp |
| 594 | Se debe informar el traceNumber |
| 595 | Intención de pago vencida en Todo Pago |
| 598 | Las cuotas del pago ya fueron informadas |
| 599 | Debe informar cuotas |
| 650 | Importe de devolución de cashout invalido |
| 651 | Importe de cashout invalido |
| 733 | La transacción no corresponde a una operación de Billeteras Electrónicas |
| 734 | No es posible cancelar la transacción informada |
6.3 Códigos de Error del CORE de VTOL Server
Es posible que VTOL responda "Error" en el campo 26 del mensaje de respuesta. Este valor indica que se ha producido un error dentro del flujo inicial y principal del CORE de VTOL, previo al procesamiento de las reglas de negocio asociadas al tipo de transacción.
Normalmente los casos en donde se puede dar ésta situación son los siguientes:
Por ejemplo:
- Si el nodo o el store son inválidos
- Si el mensaje tiene un formato erróneo
- Si el campo 11 no fue enviado en el requerimiento
- Si el campo 11 tiene un valor no soportado por VTOL
- Si el campo 1 no fue enviado en el requerimiento
- Si el campo 2 no fue enviado en el requerimiento
- Si un campo enviado en el requerimiento no es soportado por VTOL
- Si VTOL no tienen conexión con base de datos
- Si hay otro error interno al CORE (la transacción no llegó al módulo)
- Si la transacción se empezó a procesar en el módulo y éste nunca responde. Esto provoca que se active un flujo alternativo de Timeout del CORE que se da a los 60 segundos
- Si el CORE no puede aceptar más transacciones porque está sobrecargado
El mensaje de respuesta tiene siempre el siguiente formato:
Donde:
- Los campos 32 y 31 se responden por compatibilidad hacia atrás con otras implementaciones
- El campo 28 siempre posee la descripción del error
- El campo 27 siempre es "99"
- El campo 26 siempre dice "Error"
- El campo 25 es la hora del requerimiento
6.4 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 v108.
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. |
Ejemplo:
PV:VI;Visa;
PV:MA;Mastercard;
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 |
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;;0
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
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 | |
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. |
Ejemplo:
PP:AM;$;;0;1;98765432;101607;0000000000.00;0000000000.00;12.30;1;Normal
PP:VI;$;;0;10;98765432;101608;0000000100.00;0000000000.00;15.00;0;Normal
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
6.5 Circuito Operativo de EMVKIT
6.5.1 Flujo a Implementar
En este anexo se mencionará el flujo a implementar los tipos de operaciones soportadas por la Librería dependiendo el dispositivo de captura que posea la terminal:
Operatoria con Pinpad
- Crear Sesión
- Leer Datos de la Tarjeta
Flujo alternativo:
2.1 Cancelar Lectura de Tarjeta
2.2 Vuelve al paso 2 - Procesar Operación con Tarjeta
Flujo alternativo:
3.1 Leer Datos de la Tarjeta
3.2 Procesar Operación con Tarjeta - Cerrar Sesión
Operatoria sin Pinpad
- Crear Sesión
- Procesar Mensaje Crédito Débito
Flujo alternativo:
2.1 Procesar Mensaje Crédito Débito - Cerrar Sesión
Operatorias PEI (sin Pinpad)
- Crear Sesión
- Procesar Mensaje PEI
Flujo alternativo:
2.1 Procesar Mensaje PEI - Cerrar Sesión
Operatorias de Impresión de Voucher
Opción A: Impresión de voucher posterior procesamiento de tarjeta
- Crear Sesión
- Leer Datos de la Tarjeta
Flujo alternativo:
2.1 Cancelar Lectura de Tarjeta
2.2 Vuelve al paso 2 - Procesar Operación con Tarjeta
Flujo alternativo:
3.1 Leer Datos de la Tarjeta
3.2 Procesar Operación con Tarjeta - Impresión de voucher
Flujo alternativo:
4.1 Impresión libre de voucher - Cerrar Sesión
Opción B: Impresión libre de voucher
- Crear Sesión
- Impresión libre de voucher
- Cerrar Sesión
Nota: La operación "Obtener Configuración de POS" se recomienda ejecutar por lo menos una vez a día: al inicio del día, tras efectuar un cierre de caja, etc.
6.5.2 Procesamiento de Tarjetas de Empleados
A continuación se detalla la forma de procesarse una tarjeta de empleados con EMVKIT:
- Crear sesión.
- Leer Datos de la Tarjeta (con valor "Sale" en el campo 11 -trxType-, tipo de transacción).
- Procesar Operación con Tarjeta (se deberá informar el valor "Sale" en el campo 11 -trxType- y el valor del proveedor en el campo 1102 -provider-. No es necesario enviar otros valores como importe, divisa, plan, etc).
EMVKIT le informará al POS que se trata de una tarjeta de empleado o bin de excepción y le enviará datos propios de la tarjeta (número de tarjeta, nombre de la tarjeta, etc). - Cerrar Sesión
Ejemplo de Mensajería de Integración
Request: {25:20180522151512;2:1;1:1;11:createSession}
Response message: {1010:1527012912324;1027:000;1028:Ok}
Request: {25:20180522151512;2:1;1:1;11:Sale}
Response message: {1027:000;1028:Ok;10:MSR;1103:20180522151513346;1105:600000;1106:4501;1010:1527012912324;1107:600000******4501;1108:1;1109:LIVE;1112:BIN EXCEP PRUEBA;1115:101;1116:123456}
Request: {1103:20180522151513346;1102:BE;1010:1527012912324;11:Sale;2:1;25:20180522151513;1:1}
Response message: {1:1;66:B6000000000534501^GLAD*S MART*NEZ GUT*ERREZ/^9912501;2:1;1027:000;3:VTOL;1028:Ok;4:DATA;6:6000000000534501;9:6000000000534501=9912501;10:MSR;145:LIVE;1010:1527012912324;25:20180406091519;26:ISO8583;27:00;59:0;28:APROBADA}
Request: {1008:CLOSE;25:20180522151514;2:1;1:1;11:closeSession}
Response message: {1010:1527012912324;1027:000;1028:Ok}
6.5.3 Pagos Parciales
A continuación se muestra un diagrama de secuencia donde se explica la operatoria entre el POS, EMVKIT y el Pinpad.
Venta
Cuando en una sesión exista un sólo pago, se deberá efectuar la operatoria de lectura y de procesamiento de la operación. En caso de que en una sesión existan más de un pago; es decir, pagos parciales, se deberá efectuar el proceso de lectura y procesamiento por cada una de las tarjetas.
Anulación de venta
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. En caso de anulación de pagos parciales en una sesión, se deberá efectuar una anulación por cada pago parciales, finalizando de esta manera la sesión con tanta cantidad de ventas como de anulaciones de venta.
Diagrama de secuencia de Pagos Parciales
6.6 Mecanismo de Autorización Telefónica
Cuando el centro autorizador responde a una operatoria de autorización con el mensaje "Autorización telefónica", EMVKIT de igual forma le envía un comando de requerimiento al pinpad.
- Si el pinpad aprueba la transacción, se envía un mensaje de advice al centro autorizador.
- Si el pinpad rechaza la transacción, se realiza un echo de los valores y se retorna el resultado al punto de venta.
Luego, el retailer deberá comunicarse telefónicamente con el Centro Autorizador para proceder a autorizar por teléfono la transacción rechazada.
- Si la transacción intentada era procedente de una tarjeta con chip, se marca la transacción para realizarse nuevamente. El punto de venta reintentará efectuar la transacción.
- Si la transacción intentada era procedente de una tarjeta sin chip, el Centro Autorizador entrega un código de autorización. El punto de venta debe volver a ejecutar las operaciones de EMVKIT "Leer Datos de la Tarjeta" y "Procesar Operación con Tarjeta", esta vez informando el código de autorización otorgado por el Centro Autorizador y enviando la transacción como offline.
Importante: El punto de venta es el responsable de validar que tanto la primera transacción de venta como la segunda, en la que se informa el código de autorización, se trate de la misma operación de venta. Para EMVKIT, estas transacciones, se consideran como dos ventas individuales.
6.7 Timeout de EMVKIT
Se recomienda que el punto de venta implemente un timeout con EMVKIT de 240 segundos (4 minutos) antes de cerrar la comunicación. Este estimativo se obtiene en base a un análisis de los valores de setup de fábrica del pinpad y considerando los peores escenarios de interacción entre el servidor, el usuario y el pinpad.
Se debe tener en cuenta que el tiempo de espera para una respuesta de EMVKIT que se debe configurar en el punto de venta tiene que ser mayor al valor configurado en el archivo business.properties:
#Tiempo de espera de la respuesta de la librería antes de responder al POS con TO.
ServiceApiBridge.responsePosTimeOut=230000
El valor de este parámetro indica cuánto tiempo espera EMVKIT para responder con un error de Timeout y no dejar al punto de venta esperando respuesta.
Por cada solicitud, se activa ese tiempo; y si no tiene una respuesta para enviar al punto de venta, cumplido ese tiempo, se enviará un mensaje de timeout.
Este valor en principio no debería subirse pues está calculado en base a los escenarios de sincronización y autorización.
6.8 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.
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.
Operaciones de pagos QR con Billeteras:
- La transacción se cae por tiempo expirado, el POS ejecuta un QuerySaleWallet para consultar el estado.
- Apertura de sesión.
- SaleWallet
- Rta: Consulte pago por tiempo expirado - 24:trxid 7
- QuerySaleWallet - 24:trxid 7 (transacción de la venta original)
- Rta: 27:516 28:Pago aún no realizado, desea seguir esperando? - 24:trxid 7
- QuerySaleWallet - 24:trxid 7 (transacción de la venta original)
- Rta: Pago Aprobado - 24:trxid 7
- SaleWallet
- Cierre de sesión: Se cierra sesión en estado Close. En el campo 1009 (closeTrxIdList) se envían las operaciones aprobadas (iii). 1009:7
- Apertura de sesión.
El cliente confirma el pago desde la app de su celular, pero después le indica al cajero que quiere cancelar la operación.
create session
SaleWallet
Rta: Pago Aprobado - 24:trxid 8
QuerySaleWallet - 24:trxid 8 (transacción de la venta original)
Rta: 27:00 28:Aprobada - 24:trxid 8
SI EL CLIENTE DECIDE CANCELAR LA COMPRA, EL POS DEBERÁ GENERAR UN refundWallet
CloseSession en estado CLOSE (1009:8). En el campo 1009 (closeTrxIdList) se envían las operaciones aprobadas (i).
6.9 Ejemplo de integración
A continuación se da un ejemplo de integración con EMVKit para poder realizar una venta con tarjeta presencial.
El código que se muestra a continuación sería lo que van en el Punto de Venta.
Las pre-condiciones para poder ejecutar con éxito ésta pruebas son las siguientes:
- tener Java/.NET instalado
- poseer un pinpad soportado para poder realizar la lectura de tarjeta (si Ud no cuenta con un Pinpad, Napse podrá proveer un emulador a fines de poder realizar la integración)
- tener un VTOL Server instalado (si ud no tiene uno, puede solicitar a Napse acceso a un entorno de pruebas de VTOL en la nube)
La única dependencia será la librería liviana de VTOL que será suministrada por el equipo de productos de Napse.
Ejemplo en JAVA
import java.util.ArrayList; import java.util.List; import ar.com.synthesis.vtol.client.Message; import ar.com.synthesis.vtol.client.NodeStatus; import ar.com.synthesis.vtol.client.StaticVtolClient; import ar.com.synthesis.vtol.client.TransactionField; import ar.com.synthesis.vtol.client.VtolClient; import ar.com.synthesis.vtol.client.VtolClientConstants; import ar.com.synthesis.vtol.client.VtolNode; public class SaleOKExample { public static void main(String[] args) { SaleOKExample example = new SaleOKExample(); example.run(); } public void run(){ StaticVtolClient vtolClient = null; //**************************************************************************************************** //* LOS SIGUIENTE DATOS SERAN SUMINISTRADOS POR NAPSE //**************************************************************************************************** String EMVKIT_IP = "127.0.0.1"; String EMVKIT_PORT = "3500"; String store = "1"; String terminal="1"; VtolNode vtolNode = null; try{ //**************************************************************************************************** //1-INICIALIZAR LIBRERIA CLIENTE LIVIANA DE VTOL //**************************************************************************************************** System.out.println("1-Inicializando librería cliente VTOL THIN"); vtolClient = (StaticVtolClient) VtolClient.getStaticVtolClient(store); vtolClient.setParameter(VtolClientConstants.HOSTIP, EMVKIT_IP);//direccion ip de EMVKit vtolClient.setParameter(VtolClientConstants.HOSTPORT, EMVKIT_PORT);//puerto de EMVKit vtolClient.setParameter(VtolClientConstants.TIMEOUTCONNECTIONHOST, "3000"); vtolClient.setParameter(VtolClientConstants.RESPONSETIMEOUT, "65000");//timeout de respuesta de EMVKit vtolClient.setParameter(VtolClientConstants.USEVTOLCLIENTFINDER, "False"); vtolClient.setParameter(VtolClientConstants.CLIENTFINDER, VtolClient.COMMITSTATUS); vtolClient.setParameter(VtolClientConstants.USEENCRYPTEDDATA, "False"); vtolClient.init(); System.out.println("Librería cliente VTOL THIN iniciada correctamente."); //**************************************************************************************************** //2-OBTENER UN NODO/CAJA PARA OPERAR CONRA EMVKIT //**************************************************************************************************** System.out.println("2-Creando nodo/caja para operar"); vtolNode = vtolClient.createNode(terminal); vtolNode.setStatus(NodeStatus.INUSE); //**************************************************************************************************** //3-CONSTUIR UNA TRANSACCION DE INICIO DE SESION Y ENVIARLA A EMVKIT //**************************************************************************************************** System.out.println("3-Iniciando sesion en EMVkit"); vtolNode.createTransaction(); vtolNode.addField(11, "createSession"); vtolNode.addField(1025, "1");//Se activa el control transaccional vtolNode.sendTransaction(); //**************************************************************************************************** //4-EVALUAR RESULTADO //**************************************************************************************************** Message responseMessage = vtolNode.getCurrentTransaction().getResponseMessage(); TransactionField rc = responseMessage.getField(1027);//codigo de repsuesta if ("000".equals(rc.getValue())) {//000 es aprobado TransactionField currentSessionId = responseMessage.getField(1010); System.out.println("4-Sesion iniciada correctamente. ID: " + currentSessionId.getValue()); //************************************************** //5-PEDIR LECTURA DE TARJETA //************************************************** System.out.println("5-Iniciando sesion en EMVKIT"); vtolNode.createTransaction(); vtolNode.addField(11, "Sale"); vtolNode.sendTransaction(); responseMessage = vtolNode.getCurrentTransaction().getResponseMessage(); rc = responseMessage.getField(1027);//codigo de repsuesta if ("000".equals(rc.getValue())) { //************************************************** //SI EL SISTEMA LO REQUIERE, PUEDE VALIDAR LA TARJETA //O CALCULAR PROMOCIONES //************************************************** List proveedores = responseMessage.getField(1102).getListValue();//Lista de proveedores identificados por EMVKit //************************************************** //6-PEDIR AUTORIZACION DE LA VENTA ANTERIOR //************************************************** TransactionField cardContextId = responseMessage.getField(1103); vtolNode.createTransaction(); vtolNode.addField(11, "Sale");//tipo de transaccion vtolNode.addField(12, "1000");//monto (2 ultimos son decimales) vtolNode.addField(13, "$");//moneda vtolNode.addField(14, "1");//cuotas vtolNode.addField(15, "0");//plan vtolNode.addField(1103, cardContextId.getValue());//cardContextId System.out.println("6-Enviando autorizacion de venta..."); vtolNode.sendTransaction(); responseMessage = vtolNode.getCurrentTransaction().getResponseMessage(); rc = responseMessage.getField(1027);//codigo de repsuesta EMVKIT TransactionField vtolRC = responseMessage.getField(27);//codigo de repsuesta VTOL TransactionField libFullRC = responseMessage.getField(28);//descripcion respuesta List<String> closeTrxIdList = new ArrayList<String>(); if("000".equals(rc.getValue()) && "00".equals(vtolRC.getValue())){ System.out.println("Venta aprobada: " + libFullRC.getValue()); TransactionField trxId = responseMessage.getField(24); closeTrxIdList.add(trxId.getValue()); }else{ System.out.println("Venta rechazada: " + rc.getValue()); } //*************************************************************************** //7-CERRAR SESION //*************************************************************************** System.out.println("7-Cerrando sesion..."); vtolNode.createTransaction(); vtolNode.addField(11, "closeSession"); vtolNode.addField(1008, "CLOSE"); vtolNode.addField(1009, closeTrxIdList); vtolNode.sendTransaction(); System.out.println("Sesion cerrada, FIN!"); }else{ System.out.println("Error al solicitar venta. Codigo de error: " + rc.getValue()); } }else{ System.out.println("No se puedo incializar la sesion. Codigo de error: " + rc.getValue()); vtolNode.createTransaction(); vtolNode.addField(11, "closeSession"); vtolNode.addField(1008, "CANCEL"); vtolNode.sendTransaction(); } }catch(Exception e){ e.printStackTrace(); } finally { // libera el nodo para un proximo mensaje if (vtolNode != null) { vtolNode.setStatus(NodeStatus.AVAILABLE); } } } }
Ejemplo en .NET
using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Linq; using System.Text; using System.Windows.Forms; using VtolClientLib; namespace VtolTestPinPad { public partial class Form1 : Form { //Cliente Vtol StaticVtolClient StaticVtolClient = new StaticVtolClient(); //Lista de transacciones a confirmar System.Collections.ArrayList trxToConfirm = new System.Collections.ArrayList(); public EjemploIntegracion() { InitializeComponent(); } private VtolNode IniciarSesion() { //Inciar Sesion contra la libreria VTOL Full //Seleccionar el Local StaticVtolClient.SetParameter(VtolClientLib.VtolParam.StoreId, "6"); //Setear Parámateros StaticVtolClient.SetParameter(VtolClientLib.VtolParam.HostIp, "127.0.0.1"); StaticVtolClient.SetParameter(VtolClientLib.VtolParam.HostPort, 3500); StaticVtolClient.SetParameter(VtolParam.TimeOutConnectionHost, 30000); StaticVtolClient.SetParameter(VtolParam.ResponseTimeout, 10000); StaticVtolClient.SetParameter(VtolParam.TimeOutExpirationNode, 10000); StaticVtolClient.SetParameter(VtolParam.TimeOutObtainNode, 10000); StaticVtolClient.SetParameter(VtolParam.UseVtolClientFinder, false); StaticVtolClient.SetParameter(VtolParam.VtolClientFinder, new DefaultVtolClientFinder()); StaticVtolClient.SetParameter(VtolParam.UseEncryptedData, false); StaticVtolClient.SetParameter(VtolParam.Encrypter, "DESede"); StaticVtolClient.SetParameter(VtolParam.EncrypterKey, "SynthesisSynthesisSynthe"); //Iniciar libreria StaticVtolClient.Init(); //Crear un nuevo Nodo (Caja Existente en VTOL) VtolNode vtolNode = StaticVtolClient.CreateNode("1"); //Limpiar lista de transacciones a Confirmar trxToConfirm.Clear(); textBox1.Clear(); textBox1.AppendText("Iniciando Sesion \r\n"); vtolNode.Status = NodeStatus.INUSE; vtolNode.CreateTransaction(); vtolNode.AddField(11, "createSession"); vtolNode.SendTransaction(); //Obtener Respuesta String responseCodeString = vtolNode.GetField(1027).ToString(); if ("000".Equals(responseCodeString)) { textBox1.AppendText("Sesion creada \r\n"); } else { textBox1.AppendText("Error: " + vtolNode.GetField(1028).ToString() + " \r\n"); } //Retornar el nodo creado return vtolNode; } private void CerrarSesion(VtolNode vtolNode, String SessionAction, System.Collections.ArrayList trxList) { //Cerrar sesion vtolNode.CreateTransaction(); vtolNode.AddField(11, "closeSession"); textBox1.AppendText("Cerrando Sesion \r\n"); switch (SessionAction) { case "Close": //Cerrar y confirmar las transacciones pendientes //{Debug textBox1.AppendText("Enviando Commit"); //Recorrer el array para indicar las trx a informar foreach (String element in trxToConfirm) { textBox1.AppendText("trxID : " + element + "\r\n"); } //}Debug vtolNode.AddField(1008, "CLOSE"); vtolNode.AddField(1009, trxList); break; default: //Cerrar y enviar RollBack de todas las transacciones vtolNode.AddField(1008, "CANCEL"); break; } vtolNode.SendTransaction(); String responseCodeString = vtolNode.GetField(1027); if ("000".Equals(responseCodeString)) { textBox1.AppendText("Sesion Cerrada \r\n"); } else { textBox1.AppendText("Error al cerrar session [" + responseCodeString + "] "+ vtolNode.GetField(1028) +"\r\n"); } vtolNode.Status = NodeStatus.AVAILABLE; } private void btnSend_Click(object sender, EventArgs e) { textBox1.Clear(); //============================================================================================== //Iniciar sesion VtolNode vtolNode = IniciarSesion(); //============================================================================================== textBox1.AppendText("Enviando Compra \r\n"); vtolNode.CreateTransaction(); vtolNode.AddField(6, "5432219380000102"); //Tarjeta vtolNode.AddField(7, "1612"); //Vto vtolNode.AddField(8, "123"); //CVC vtolNode.AddField(10, "Manual"); //Mod. Ingreso vtolNode.AddField(11, "Sale"); //Operacion vtolNode.AddField(12, "100"); //Monto vtolNode.AddField(13, "$"); //Moneda vtolNode.AddField(14, "2"); //Cuotas vtolNode.AddField(15, "0"); //Plan //envia la trnsaccion. Es bloqueante hasta recibir la repsuesta o darse un timeout con el server vtolNode.SendTransaction(); string responseCodeString = vtolNode.GetField(FieldId.ResponseCodeFieldId); if (String.Compare(responseCodeString, "ISO8583", true) == 0) { String isoResponseCodeString = vtolNode.GetField(FieldId.ISOResponseCodeFieldId); if ("00".Equals(isoResponseCodeString)) { String transactionIdString = vtolNode.GetField(FieldId.TrxIdFieldId); trxToConfirm.Add(vtolNode.GetField(FieldId.TrxIdFieldId)); textBox1.AppendText("Aprobada trxID: "+ transactionIdString +"\r\n"); } else { textBox1.AppendText("Rechazada \r\n"); } } else { textBox1.AppendText("Error :"+ responseCodeString +" \r\n"); } //============================================================================================== textBox1.AppendText("Enviando Compra 2 \r\n"); vtolNode.CreateTransaction(); vtolNode.AddField(6, "5432219380000102"); //Tarjeta vtolNode.AddField(7, "1612"); //Vto vtolNode.AddField(8, "123"); //CVC vtolNode.AddField(10, "Manual"); //Mod. Ingreso vtolNode.AddField(11, "Sale"); //Operacion vtolNode.AddField(12, "200"); //Monto vtolNode.AddField(13, "$"); //Moneda vtolNode.AddField(14, "2"); //Cuotas vtolNode.AddField(15, "0"); //Plan //envia la trnsaccion. Es bloqueante hasta recibir la repsuesta o darse un timeout con el server vtolNode.SendTransaction(); responseCodeString = vtolNode.GetField(FieldId.ResponseCodeFieldId); if (String.Compare(responseCodeString, "ISO8583", true) == 0) { String isoResponseCodeString = vtolNode.GetField(FieldId.ISOResponseCodeFieldId); if ("00".Equals(isoResponseCodeString)) { String transactionIdString2 = vtolNode.GetField(FieldId.TrxIdFieldId); trxToConfirm.Add(vtolNode.GetField(FieldId.TrxIdFieldId)); textBox1.AppendText("Aprobada trxID: "+ transactionIdString2 +"\r\n"); } else { textBox1.AppendText("Rechazada \r\n"); } } else { textBox1.AppendText("Error :" + responseCodeString + " \r\n"); } //============================================================================================== //Cerrarr sesion CerrarSesion(vtolNode, "Close", trxToConfirm); } private void button1_Click(object sender, EventArgs e) { // ************** Prueba utilizando el pinpad ************************************** //****** Iniciar sesion ************ VtolNode vtolNode = IniciarSesion(); //****************************************************************************************************** //****************************************************************************************************** //Solicitar Lectura de Tarjeta textBox1.AppendText("Pase la Tarjeta por el PinPad \r\n"); vtolNode.CreateTransaction(); vtolNode.AddField(11, "Sale"); vtolNode.SendTransaction(); String responseCodeString = vtolNode.GetField(1027); //****************************************************************************************************** if ("000".Equals(responseCodeString)) { //Mostrar detalle de tarjeta Leida textBox1.AppendText("Lectura de Tarjeta "+ vtolNode.GetField(1028)+ " [" + vtolNode.GetField(1107) +"]\r\n"); //obtener datos necesarios String cardContextId = vtolNode.GetField(1103); vtolNode.CreateTransaction(); vtolNode.AddField(11, "Sale"); vtolNode.AddField(12, "100"); vtolNode.AddField(13, "$"); vtolNode.AddField(14, "2"); vtolNode.AddField(15, "0"); vtolNode.AddField(1103, cardContextId); vtolNode.SendTransaction(); responseCodeString = vtolNode.GetField(1027); if ("000".Equals(responseCodeString)) { //Obtener Respuesta responseCodeString = vtolNode.GetField(27); textBox1.AppendText("Respuesta: " + responseCodeString + "\r\n"); if (responseCodeString.Equals("ISO8583")) { //Obtener codigo ISO String ISOresponseCodeString = vtolNode.GetField(27); if ("00".Equals(ISOresponseCodeString)) { //Aprobada, guardar trxID trxToConfirm.Add(vtolNode.GetField(FieldId.TrxIdFieldId)); textBox1.AppendText("Aprobada trxID: " + vtolNode.GetField(FieldId.TrxIdFieldId) + "\r\n"); } } else { textBox1.AppendText("Error " + vtolNode.GetField(28) + "\r\n"); } } else { textBox1.AppendText("Error " + vtolNode.GetField(1028) + "\r\n"); } } //****** Cerrar sesion ************* CerrarSesion(vtolNode, "CLOSE", trxToConfirm); //********************************** } } }
6.10 Vouchers
En este anexo se mencionan los datos de los vouchers o comprobantes a tener en cuenta en base al canal por el cual se autorizó la tarjeta (34 - hostName), la tarjeta y el tipo de transacción. También se especifica el campo de EMV Kit correspondiente para lograr obtener dicha información.
Canal Visa - Transacción Compra - Tarjeta Visa
Canal Visa - Transacción Compra - Tarjeta Maestro
Canal Visa - Transacción Compra + Extracción - Tarjeta Visa Electrón
Canal Visa - Transacción Anulación de compra - Tarjeta Visa
Canal Visa - Transacción Anulación de compra + Extracción - Tarjeta Visa Electrón
Canal Visa - Transacción Devolución - Tarjeta Mastercard
Canal Visa - Transacción Anulación de devolución - Tarjeta VISA
Canal Posnet - Transacción Compra - Tarjeta Maestro
Canal Posnet - Transacción Anulación - Tarjeta Maestro
Canal Posnet - Transacción Devolución - Tarjeta Maestro
Canal Posnet - Transacción Compra + Retiro - Tarjeta Mastercard Debit
Canal Posnet - Transacción Compra + Retiro - Tarjeta Maestro
Referencias
X = Obligatorio
O = Opcional
- = No requerido
Ref | Dato | Canal VISA | Canal POSNET | Canal AMEX | Campo EMV Kit | Nota |
|---|---|---|---|---|---|---|
| 1 | Tipo de transacción u operación Opciones VISA:
Opciones Posnet y AMEX:
| X | X | X | 11 - trxType | |
| 2 | Número de comercio o establecimiento asignado por el Emisor | X | X | X | 30 - businessNumber | |
| 3 | Número de Terminal | X | X | X | 29 - serialNumber | |
| 4 | Número de Lote | X | X | X | 31 - lotNumber | |
| 5 | Número de cupón correspondiente a la transacción | X | X | X | 32 - ticket | |
| 6 | Últimos 4 números de la tarjeta | X | X | X | 1106 - panLastDigit | Cuando VISA autoriza, se debe enmascarar toda la tarjeta con X exceptuando los últimos 4 dígitos. Cuando Posnet autoriza, se deberá imprimir el número de tarjeta enmascarando con el carácter “*” o “#” los primeros doce dígitos de la misma, a solicitud de cada emisor. Nota: Tener en cuenta que la longitud de la tarjeta puede variar |
| 7 | Modo de ingreso del número de tarjeta Opciones VISA:
Opciones Posnet:
| X | X | X | 10 - inputMode | Cuando el ingreso es manual (Mastercard), se debe dejar en el voucher un espacio de embozado para marcar el relieve de la tarjeta |
| 8 | Fecha de vencimiento de la tarjeta | X | X | X | 7 - expiration, pero la fecha de vencimiento de la tarjeta debe ser siempre XX/XX | La fecha de vencimiento de la tarjeta siempre va enmascarada |
| 9 | Número de cuenta | O | O | O | 75 - accountNumber | Se debe imprimir el número de cuenta en caso de que la tarjeta lo devuelva En Posnet, cuando se reciba al menos un asterisco (“*”) se deberá imprimir el Número de Tarjeta en forma completa y se deberá imprimir el campo Número de Cuenta tal como se lo recibió |
| 10 | Tarjeta o proveedor con que se efectuó la operación | X | X | X | 33 - creditCardIssuerName | |
| 11 | Importe y moneda de la operación | X | X | X | 12 - amount y 13 - currencyPosCode | |
| 12 | Cantidad de cuotas | X | X | X | 14 - payments | |
| 13 | Identificador de la aplicación (AID) | O | - | O | 1110 - pinpadApplicationId | Se debe imprimir este valor en caso de que el ingreso de la tarjeta sea Chip y cuando el valor sea devuelto |
| 14 | Nombre de la aplicación (APN) | O | - | O | 1111 - pinpadApplicationName | Se debe imprimir este valor en caso de que el ingreso de la tarjeta sea Chip y cuando el valor sea devuelto |
| 15 | Modo de autorización | X | X | X | 23 - authorizationMode | Cuando la transacción es offline, se debe dejar en el voucher un espacio de embozado para marcar el relieve de la tarjeta |
| 16 | Código de autorización otorgado por el Emisor | X | X | X | 22 - authorizationCode | |
| 17 | Número de cupón original | O | O | O | 17 - originalTrxTicketNr | Sólo en las transacciones de Anulaciones de compra y Devoluciones |
| 18 | Fecha del cupón original | O | O | O | 16 - originalDate | Sólo en las transacciones de Devoluciones |
| 19 | Importe y moneda de la extracción en efectivo | O | O | - | 54 - additionalAmount | |
| 20 | Importe y moneda total de la operación (suma entre la compra/anulación y la extracción) | O | O | - | N/A | Sólo en operación compra + extracción y anulación de compra + extracción |
| 21 | Tipo de cuenta de tarjetas de débito Maestro Opciones:
| O | O | - | 57 - accountType | Exclusivo para tarjetas Maestro. Mastercard Debit no solicita el ingreso de este dato ni se imprime en el voucher |
| 22 | Tipo de plan | O | O | - | 15 - plan | Sólo para emisores que lo requieran |
| 23 | Nombre del tarjeta habiente | O | O | O | 1112 - cardHolderName | Nombre del titular de la tarjeta si el track I está presente y la lectura fue por banda |
| 24 | Versión del software o aplicación | X | X | X | 82 - softwareVersion | |
| 25 | Resultado descriptivo de la operación | O | O | O | 27 - isoCode | |
| 26 | Leyenda "Operación a confirmar" | O | - | - | N/A | Cuando es una devolución realizada por VISA, siempre se debe imprimir esta leyenda en el voucher |
| 27 | Mensaje adicional | O | - | - | 81 - responseAuth | Es opcional y se puede agregar para informarle alguna información adicional al cliente |
| 28 | Tipo de tarjeta | X | X | X | 1113 - cardIsDebit | Tarjeta de débito o tarjeta de crédito |
| - | Verificación de pin offline | - | - | O | 59 - offlinePinCheck | Si el dato se encuentra, se imprime en el voucher |
| - | Tipo de criptograma y valor | - | - | O | 1138 - emvData | Sólo será retornado en operaciones CHIP con tarjetas Amex |
| - | Número de referencia de recuperación (RRN) | - | - | O | 68 - rrn |
- Ubicación de los datos
La ubicación de los datos en el voucher no poseen alguna obligatoriedad, pero se recomienda seguir una estructura lógica como ser que los datos del cliente a completar se encuentren al final del voucher o que la fecha y hora se encuentren en la cabecera del voucher - Original y Copia
Los mencionados en esta documentación son los vouchers "Original Comercio", los vouchers "Copia Cliente" deberán ser similares pero contener esta nota al pie del voucher y omitir los datos a completar (Firma, Aclaración y Tipo y N° Doc) - Vouchers de rechazo
Cuando la operación resulte rechazada, el POS deberá imprimir un voucher similar a los mencionados pero informando solamente la terminal, el número de comercio y el motivo del rechazo obtenido del campo 28 - responseMessage
7. Compatibilidad con VTOL Server
La versión 1.5.X de EMVKit y superior tendrá compatibilidad con VTOL Server para rutear las transacciones, según las siguientes variantes:
- EMVKit 1.5 con VTOL Server 3.8.0.5
- Compatibilidad: Se puede realizar el ruteo de transacciones por local, según la configuración que se establezca en VTOL Server.
- Compatibilidad: Se puede realizar el ruteo de transacciones por local, según la configuración que se establezca en VTOL Server.
- EMVKit 1.5 con VTOL Server 3.8.0.4
- Compatibilidad: Estas versiones no son compatibles, por lo cual no se podrá transaccionar. VTOL Server no va a tener los datos de configuración que permitan que EMVKIT haga el ruteo de transacciones. En este escenario, se deberá actualizar VTOL Server a una versión superior, por ejemplo la 3.8.0.5.
- Compatibilidad: Estas versiones no son compatibles, por lo cual no se podrá transaccionar. VTOL Server no va a tener los datos de configuración que permitan que EMVKIT haga el ruteo de transacciones. En este escenario, se deberá actualizar VTOL Server a una versión superior, por ejemplo la 3.8.0.5.
- EMVKit 1.4 con VTOL Server 3.8.0.5
- Compatibilidad: no va a ser posible rutear las transacciones por local. La posición de la llave maestra mantendrá la configuración definida en los prefijos del server anterior a la actualización, por ejemplo de la 3.8.0.4 a la 3.8.0.5.