VTOL EMVKIT - Manual de mensajería POS - EMVK MX

1. Introducción

El presente documento describe la mensajería que se utiliza entre el POS y la aplicación EMV/KIT.

  1.1 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
• el reconocimiento de tarjetas (crédito/débito y otras, como vales, tarjeta regalo, etc)
• la comunicación e integración con Gateway de transacciones VTOL
• detectar y resolver problemas de contingencia
• etc

  1.2 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 para procesar la autorización.

Esta librería se ejecutará de manera stand alone –autónoma– en el punto de venta, pudiendo iniciarse como servicio, transmitiendo una comunicación server TCP IP capaz de interpretar el protocolo VTOL. El mismo protocolo es utilizado para comunicarse con VTOL Server.

La integración entre la aplicación de punto de venta y 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 o .NET, construir los mensajes para comunicarse con EMVKIT.

  1.3 Alcance

EMVKIT tiene el siguiente alcance:

• Capturar el Track I y el Track II de la tarjeta por medio del PINPAD
• Capturar información del CHIP por medio del PINPAD
• Soporte de una variedad de PINPADS
• 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
• 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 según el adquirente
• Funcionalidad de venta con cashback
• Funcionalidad de venta con puntos Bancomer (para soluciones con adquirente Bancomer)
• Soporte de operaciones de venta como devoluciones, anulación de venta
• Gestionar la mensajería con VTOL Server

Es responsabilidad de la aplicación de punto de ventas:

• La confirmación del monto
• El cálculo de promociones, la validación de plan de pago, la determinación de cuotas.
• Impresión del voucher y duplicado

En resumen, EMV/KIT se encargará de la comunicación con el PINPAD y Vtol, autorizando pagos en línea y actualizando información en el PINPAD. El POS enviará requerimientos solicitando que se realicen pagos, los cuales será responsabilidad de EMV/KIT realizar todas las validaciones necesarias y comunicarse con todos los componentes para responder al POS si el pago se pudo realizar o no, y el motivo de error.

2. Protocolo de comunicación

A continuación, detallamos lo tipos de comunicaciones de EMV/KIT.

  2.1 TCP/IP

Comunicación por default de la aplicación, la cual mantiene la misma lógica presentada en el documento “VTOLCR-DB-Manual mensajeria POS - VTOL”.

Ejemplo de Respuesta:

  2.2 Servicio REST

Se debe realizar un PUT en el servicio EMVKit, la mensajería puede ser XML o JSON, a continuación un ejemplo del servicio:

    2.2.1 Ejemplo de request

PUT http://localhost:8080/bridge-pos-rest/service/emvKitMessage

<bridgeCoreRequest>

     <connectionId>${connectionId}</connectionId>

     <operation>emvKitAuthorize</operation>    

     <params>

           <store>123</store>

           <node>5</node>

           <server>VD</server>

           <trxType>Sale</trxType>

           <dateTime>20181226105000</dateTime>

           <amount>10099</amount>

           <payments>1</payments>

           <plan>0</plan>

     </params>

</bridgeCoreRequest>

Cabeceras de petición:

Connection: keep-alive

Content-Type: application/xml;charset=UTF-8

Accept:application/xml

    2.2.2 Ejemplo de response

<?xml version="1.0" encoding="UTF-8" ?>

<bridgeCoreResponse>

  <ack>0</ack>

  <message></message>

  <representation class="emvKitRepresentation">

    <params>

      <dateTime>20181226105000</dateTime>

      <authorizationCode>012345</authorizationCode>

      <withoutSign>false</withoutSign>

      <responseCode>Iso8583</responseCode>

      <field42>1</field42>

      <posInputMode>Chip</posInputMode>

      <posAuthenticationMethod>5</posAuthenticationMethod>

      <lastTrxId>10</lastTrxId>

      <productDescription>false</productDescription>

      <criptograma>DE41234AA6A7F0B6</criptograma>

      <amount>10099</amount>

      <ticket>1</ticket>

      <cardHolderName>PRG ORO</cardHolderName>

      <cardType>Debito</cardType>

      <store>123</store>

      <node>5</node>

      <applicationLabel>MasterCard</applicationLabel>

      <isoCode>00</isoCode>

      <authorizationMode>onLine</authorizationMode>

      <responseMessage>APROBADA</responseMessage>

      <aid>A0000000041010</aid>

      <cardNumber>5499490516183381</cardNumber>

      <electronicSign>false</electronicSign>

    </params>

  </representation>

</bridgeCoreResponse>

Nota: Todo campo que se obtenga de VTOL y no haya sido mapeado en la respuesta REST, será respondido de manera “fieldXX” donde XX es el número de campo obtenido de VTOL. Ver campo “field42”.

3. Tipos de transacciones

A continuación, enumeramos los tipos de transacciones necesarios para implementar pagos con tarjetas:

• CheckPending: Mensaje de consulta de transacciones pendientes.
• Sale: Solicitud de pago con tarjeta
• Refund: Solicitud de devolución o cancelación con tarjeta.
• UnSyncCompletion: Mensaje de confirmación de transacción (“tercer mensaje”).
• AdditionalData: Selección de planes, cuotas, puntos Bancomer y/o autorización telefónica.
• ResetKeys: Se solicita inyección de llaves opcional en pinpad.

El flujo de mensajería mantiene la misma lógica que actualmente se enumera en el documento de mensajería “POS-VTOL”: “VTOLCR-DB-Manual Mensajería POS – VTOL MX.docx”.

En nuestro caso, los mensajes “AdditionalData” y “ResetKeys” son complementarios y relacionados a EMV/KIT y el flujo será explicado en este documento.

Dependiendo de los autorizadores e implementaciones, se han agregado funcionalidades adicionales, las cuales se encontrarán habilitadas o no dependiendo del autorizador, algunas funcionalidades son: “CashAdvance”, “CardPayment”, “QueryPan” y “LoadExceptionBins”.

4. Autorizadores/Bancos

Existen funcionalidades propias de cada autorizador o banco, para lo cual ciertas funcionalidades y parámetros se encuentran restringidos a estos en todo el documento, es importante que tenga en cuenta cuando se realizan las integraciones, los autorizadores o bancos que actualmente se manejan son:

• Bancomer
• Banamex
• Visanet/Paradox
• Banorte

5. Flujo de mensajería

A continuación, se muestra un simple diagrama, donde se puede visualizar un caso completo de comunicación entre POS – EMV/KIT – Pinpad – VTOL para pagos simples con tarjetas.

En este caso, es un simple caso sin errores, donde se realiza un pago con cierta tarjeta.

Existen mensajes que EMV/KIT no necesita procesar y por lo tanto se enviarán directamente a VTOL, actualmente estos mensajes son “CheckPending” y “UnSyncCompletion”, a continuación un diagrama con esta situación.

También puede darse el caso de requerir enviar un mensaje a VTOL con datos leídos por un dispositivo externo, en ese caso, si un “Sale” o un “Refund” se envía con el campo InputMode (#10) presente se seguirá este proceso también.

A partir de este momento, en los diagramas no visualizaremos la comunicación con el Pinpad ni con VTOL ya que esto es responsabilidad del EMV/KIT.

En el próximo diagrama visualizamos un escenario con varios pagos parciales, al finalizar todos los pagos será necesario el envío de los “UnSyncCompletion”.

En caso de que antes de realizar el pago, no conozcamos los planes habilitados para la tarjeta que ingresaremos, será necesaria una interacción con EMV/KIT para informar estos planes:

Existen casos donde el Pos debe solicitar la inyección de llaves, esto sucede cuando el centro autorizador informa que se debe realizar una inyección de llaves “opcional”. Se pueden definir diferentes estrategias para realizar esta inyección, en este caso se debe revisar la documentación proporcionada por el autorizador. De acuerdo a algunas especificaciones, se solicita esta inyección en la carga de la aplicación, cuando es un nuevo día o cuando una transacción ha sido finalizada.

En todos los casos no se permite este tipo de mensaje mientras exista una transacción en curso.

6. Formato y campo requerido

Los campos son de longitud fija, numéricos, o alfanumérico. A continuación, se muestra el formato que se utilizará para determinar la representación de cada campo.

El campo de representación puede tener los siguientes formatos:

NX (F)          Caracteres numéricos con longitud fija de X caracteres

NX (V)          Caracteres numéricos con longitud variable de máximo X caracteres

AX (F)           Caracteres alfabéticos, numéricos y/o especiales con longitud fija de X caracteres

AX (V)          Caracteres alfabéticos, numéricos y/o especiales con longitud variable de máximo X caracteres

Si no se especifica (F) o (V) se considera por default una longitud variable (V)

Para los casos donde se especifica si un campo es requerido, las opciones son:

• M: Mandatorio
• O: Opcional
• C: Condicionado

7. Campos de la mensajería POS – EMV/KIT

A continuación se definen los campos utilizados en la mensajería entre el Pos y EMV/KIT.

Tener en cuenta que algunos campos se encuentran relacionados al autorizador, por lo tanto estos solo servirán en esos casos (ejemplos de autorizadores: Banamex, Bancomer, etc.)

  7.1 CheckPending y UnSyncCompletion

Estos mensajes tienen el mismo uso descripto en el documento “POS-VTOL”.

Los mensajes de “requerimiento” y de “respuesta” se mantienen idénticos.

Nota relacionada al UnSyncCompletion: Actualmente existe el “tercer mensaje embebido”, mismo que en esta mensajería podría utilizarse. El mensaje embebido se compone de los campos “19” y “24” y puede ser enviado con cualquier mensaje.

El único mensaje que no procesará estos campos será “resetKeys”.

  7.2 Sale y Refund

Mensaje utilizado para realizar un pago parcial, sea de venta o devolución.

Cuando se recibe este mensaje, comienzan las validaciones, comunicación con el Pinpad y autorización con Vtol.

En caso de que no se reporten los planes y cuotas inicialmente desde el POS, la aplicación generará el error correspondiente (ver códigos de error) informando la cuenta para que la aplicación indique el plan que se desea utilizar mediante el mensaje “AdditionalData”.

Nota1: Si este mensaje contiene el campo InputMode (#10), este mensaje deberá estar constituido según documento: “VTOLCR-DB-Manual Mensajería POS – VTOL MX”, y se enviará de manera directa a VTOL. Para la cual se asume que la cuenta fue ingresada por otro medio y no se desea el ingreso por medio del pinpad.

Nota2: Mediante este mensaje es posible generar un “cashAdvance” (retiro de efectivo, sin realizar un pago, con solicitud de cuenta desde el pinpad). Se tratará como un “Sale” para poder obtener la información necesaria para generar el mensaje al autorizador, en caso de no desear la lectura de la cuenta por pinpad se podrá enviar el mensaje “cashAdvance” directamente (ver punto 7.8 CashAdvance).

  7.2.1      Requerimiento Pos – EMV/KIT

   7.2.2 Respuesta EMV/KIT – Pos

Esta respuesta contiene todos los campos del documento “POS-VTOL” para “Sale” o “Refund”, donde se adicionan los siguientes campos por EMV/KIT.

   7.2.3 Campos adicionales de configuración de la tarjeta

Los campos 209, 110, 211 y 212 estarán presente teniendo en cuenta los siguientes comentarios:

1. Debe tener habilitada la funcionalidad de RSVTOL.INI: “rsvtol.enabled=true”
2. Se informarán estos campos en el caso de respuestas donde se solicita envío de additionalData. Los códigos de respuesta más comunes a tener en cuenta serán:
   • Código 12: Falta informar los planes y cuotas del pago. (Cuando no se han enviado los campos 14 y 15 en el request de Sale)
   • Código 15: Cuando la tarjeta se encuentra dentro del programa de puntos Bancomer y se necesita confirmar si el pago será o no con los puntos del cliente. Ver punto “8 – Códigos de errores”.
3. También se informarán estos campos al finalizar con una respuesta de “00 Aprobada” al “Sale”.

  7.3 PTService

Para el caso de conexión PagaTodo, la aplicación identifica el Bin de la tarjeta como tarjeta PagaTodo según la configuración del archivo RSVTOL.ini, y convierte el mensaje “Sale” en un “PTService”. De este modo el POS no necesita saber si es un tipo de tarjeta compatible con el servicio, y  se hacen las adaptaciones necesarias en el mensaje para que VTOL lo interprete como tal.

   7.3.1 Requerimiento Pos – EMV/KIT

   7.3.2 Respuesta EMV/KIT – Pos

7.4 PTPromotionQuery

Para el caso de conexión PagaTodo para consulta de promociones de tarjeta de Bienestar Capital social, la aplicación obtiene el Bin de la tarjeta para este tipo de solicitud según la configuración del archivo RSVTOL.ini, y genera la consulta a VTOL.

   7.4.1 Requerimiento Pos – EMV/KIT

   7.4.2 Respuesta EMV/KIT – Pos

7.5 AdditionalData

Luego de haber enviado un “Sale” o “Refund” es posible que EMV/KIT indique que faltan datos para continuar con el pago. En estos casos la respuesta generará un mensaje de error indicando cual es el caso, las opciones son:

1. No se ha informado el plan y cuotas a utilizar para el pago, EMV/KIT en su respuesta envía el número de cuenta/tarjeta, para que el POS pueda procesar los planes disponibles y reportarlos a EMV/KIT.

Para este caso en el “AdditionalData” se debe enviar los campos “payments” y “plan”.

2. La autorización con VTOL fue rechazada solicitando autorización telefónica, es necesario obtener la autorización de manera telefónica y enviar a EMV/KIT.

Para este caso en el “AdditionalData” se debe enviar el campo “authorizationCode”.

3. Pueden existir casos donde durante la autorización, VTOL reporte “trxIsPending”, como los ID de VTOL no son persistentes en EMV/KIT, será necesario que el POS envíe este mensaje cargando los campos “19” y “24”.

4. Existe un caso donde se ha solicitado “AdditionalData”, pero el Pos desea cancelar el pago, existe una marca en este mensaje para indicar que se desea cancelar el pago, así EMV/KIT realiza las sincronización correspondiente con el pinpad. En este caso este mensaje no generará respuesta al POS (similar al “UnSyncCompletion”).

5. En caso de implementación Bancomer, existen cuentas las cuales pueden ser pagadas con puntos Bancomer, en los casos donde se genere un código de respuesta 15 a un mensaje “Sale”, se deberá solicitar si se desea o no pagar con puntos Bancomer.

Para este caso en el “AdditionalData” se debe enviar con el campo “pointsPayment” en “true” o “false” según la elección del cliente.

6. En caso de implementación Bancomer, existen cuentas las cuales permiten el retiro de efectivo CashBack, en los casos donde se genere un código de respuesta 16 a un mensaje “Sale” se deberá solicitar si se desea o no pagar con cashBack y se deberá obtener el monto a aplicar. Este monto será enviado en el campo “additionalAmount” del additionalData.

Nota: tener en cuenta que si en un mismo pago se deben enviar varios “additionalData”, cada mensaje se debe enviar con los mismos campos enviados anteriormente. Por ejemplo, si se solicita ingreso de plan/cuotas y luego el ingreso de un código de autorización telefónica, el último mensaje (autorización telefónica)  deberá contener los datos del mensaje anterior (plan/cuotas).

   7.5.1 Requerimiento Pos - EMV/KIT

   7.5.2 Respuesta EMV/KIT - Pos

7.6      ResetKeys

Este mensaje es utilizado para indicarle a EMV/KIT que es momento de realizar la carga de llaves “opcional” solicitada por el centro autorizador en la autorización de un pago anteriormente realizado.

   7.6.1 Requerimiento Pos – EMV/KIT

   7.6.2 Respuesta EMV/KIT – Pos

7.7 Mensajes directos a VTOL (no procesa EMVKit)

En todos los mensajes de requerimiento existe el parámetro #3 (Server), el cual se envía con el valor “VD”, esto indica que se desea que sea procesado por EMVKit. En caso de que este atributo sea “VTOL”, este no será tenido en cuenta por EMVKit y será enviado directamente a Vtol para su procesamiento.

Nota: Tener en cuenta que este mensaje debe estar alineado con la especificación propia de VTOL.

Este tipo de mensaje puede ser usado para envío de:

1. voidSale
2. voidRefund
3. PTPromotionQuery

Los cuales no son procesados por EMVKit.

7.8 CashAdvance

La funcionalidad de CashAdvance es utilizada para realizar un retiro de efectivo, directamente desde el punto de venta, sin estar realizando un pago en ese momento.

Nota: Dependerá del centro autorizador si esta funcionalidad se encontrase o no habilitada.

Existen dos maneras para realizar este tipo de operaciones y depende directamente de quien es el responsable de realizar la lectura de la cuenta:

• La lectura de la cuenta es responsabilidad del punto de venta y por lo tanto se envía mensaje desde el mismo hacia EMVKit un mensaje de tipo “CashAdvance” de acuerdo a la mensajería de la documentación “VTOLCR-DB-Manual mensajeria POS - VTOL MX”.
• La lectura de la cuenta es responsabilidad de EMVKit, la cual se realizará por medio del pinpad. En estos casos se envía un mensaje a EMVKit de tipo “Sale” con el campo 12 “amount” con valor “0” y el monto del retiro se envía en el campo 65 “additionalAmount” con el valor del retiro. Para mayor información se debe revisar punto “2 Sale y Refund” en este documento.

La diferencia más importante entre estos dos tipos de mensajería, es que lo errores informados durante la operación podrían traducirse en mensajes “additionalData” de solicitud de información adicional (revisar punto “8 Códigos de errores”).

   7.8.1 Requerimiento Pos – EMV/KIT

Dependiendo de las dos opciones mencionadas anteriormente, se deberá revisar la documentación relacionada para el armado de la mensajería. En ambos casos, se ha agregado funcionalidad adicional que se detalla a continuación y puede ser usada en cualquier tipo de comunicación.

   7.8.2 Respuesta EMV/KIT – Pos

Dependiendo de las dos opciones mencionadas anteriormente, la respuesta deberá ser obtenida de la documentación pertinente.

7.9 CardPayment

Este mensaje es utilizado para corresponsalías, el mensaje se debe armar exactamente de la misma manera que se encuentra especificado en la documentación “Tech- Ref POS-VTOL Corresponsalías Bancomer”.

Nota: Dependerá del centro autorizador si esta funcionalidad se encontrase o no habilitada.

   7.9.1 Requerimiento Pos – EMV/KIT

Se deberá revisar la documentación relacionada para el armado de la mensajería.

Se ha agregado funcionalidad adicional que se detalla a continuación para este tipo de mensaje.

   7.9.2 Respuesta EMV/KIT – Pos

La respuesta deberá ser obtenida de la documentación pertinente.

7.10 QueryPan/QueryBin

Comando utilizado para lectura de una tarjeta mediante el pinpad, una vez leída se retorna el número y se cierra la comunicación.

La diferencia entre ambos comandos está dada por el campo 6 de la respuesta “cardNumber”:

• QueryPan: El campo “cardNumber” retornado será enmascarado de acuerdo al atributo de configuración “mask.account.type”.
• QueryBin: El campo “cardNumber” retornado será el bin de la tarjeta, el cual serán los caracteres iniciales de la cuenta definidos de acuerdo al atributo de configuración “queryBin.account.length”.

Ver documento ”F13 Documento de configuración - EMVKit v{version}.docx” para más información.

   7.10.1 Requerimiento Pos – EMV/KIT

   7.10.2    Respuesta EMV/KIT – Pos

7.11 LoadExceptionBins (Únicamente para Banorte)

Comando utilizado para lectura de una tarjeta mediante el pinpad, una vez leída se retorna el número y se cierra la comunicación.

   7.11.1 Requerimiento Pos – EMV/KIT

   7.11.2 Respuesta EMV/KIT – Pos

7.12    PointsLookup

Comando utilizado para consulta de puntos con el autorizador, actualmente para puntos Bancomer. Se realiza una lectura de una tarjeta mediante el pinpad, una vez leída se realiza la consulta correspondiente con VTOL y se devuelve el resultado.

Esta operación no genera id de transacción y por lo tanto no requiere tercer mensaje (commit/rollback)

   7.12.1 Requerimiento Pos – EMV/KIT

   7.12.2    Respuesta EMV/KIT – Pos

La respuesta contiene todos los campos respondidos por VTOL.

8. Códigos de errores

A continuación, enumeramos los códigos de error que son necesarios interpretar o conocer para el POS, los códigos enumerados a continuación hacen referencia al campo 27 “responseCode” en EMVKit.

Existen varias acciones diferentes a realizar con cada respuesta de EMVKit, a continuación las explicamos:

• Campo 27 “responseCode” con valor “00” (Aprobada), la operación se ha efectuado satisfactoriamente.
• Campo 27 “responseCode” con valor “03”: Información de la cuenta obtenida para “cashAdvance” la acción a ejecutar depende del escenario.
• Campo 27 “responseCode” con valor “11” (Error en VTOL), la operación no se ha realizado, se puede revisar el campo 201 “additionalResponseCode” para revisar exactamente el error generado por VTOL y validarlo con el documento de VTOL “VTOLCR-DB-Manual mensajeria POS - VTOL” en el apartado de “códigos de respuesta”.
• Campo 27 “responseCode” con valores “12”, “13”, “14”, “15” y “16”: Pago en curso y se necesita información adicional para continuar o cancelar el pago.
• Otros valores en campo 27 (02, 31, 99): La operación no se ha efectuado por un error, por lo cual el pago ha sido anulado y se debe volver a comenzar. El campo 201 “additionalResponseCode” contiene el código interno de EMVKit para este error.

Ej.:{28:Transacción en curso;27:99;26:11;201:10032;25:20161130170344;2:5;1:17}