VTOL EMVKIT - Manual de mensajería POS - EMVKIT
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 POSenviará 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 POSsi 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:
Header | Mensaje | |
|---|---|---|
Longitud del mensaje (4 bytes) | Indica si el mensaje requiere respuesta o no (2 bytes) | Ejemplo: {25:20020426172836;1:5;2:1;27:00;26:ISO8583;28:Aprobado} |
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 />
<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 campo 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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "Sale" o "Refund". |
12 | amount | M | N10 | Monto de la transacción, los últimos 2 dígitos son decimales. |
14 | payments | O | N2 | Cantidad de cuotas/parcialidades (meses). 2 dígitos como máximo. En el caso de no enviarse este dato (campo 14 y 15), se generará una respuesta de código 12 (ver tabla capítulo 6) que contendrá el número de Tarjeta. De este modo, la aplicación de punto de venta podrá evaluar el número de tarjeta y determinar si aplica parcializar. Enviar el dato de pagos como AdditionalData (ver 5.3) |
15 | plan | O | A | Plan. 1 carácter de longitud. En el caso de no enviarse este dato (campo 14 y 15), se generará una respuesta de código 12 (ver tabla capítulo 6) que contendrá el número de Tarjeta. De este modo, la aplicación de punto de venta podrá evaluar el número de tarjeta y determinar si aplica parcializar. Enviar el dato de plan como AdditionalData (ver 5.3) |
16 | originalDate | C | yyyyMMdd | Este campo es mandatorio únicamente en devoluciones, es la fecha original del pago que estamos devolviendo. |
17 | originalTrxTicketNr | C | N | Este campo es mandatorio únicamente en devoluciones, es el número de ticket del pago original que se está devolviendo. |
22 | authorizationCode | O | A6 | Código de autorización telefónica. Este campo se encuentra presente únicamente si la transacción se autorizó offline por teléfono. |
23 | authorizationMode | O | A | Modo de Autorización: |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
65 | additionalAmount | O | N10 | Se indica el monto a aplicar a cashBack o cashAdvance, valores posibles: |
71 | checkPendingString | O | A | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas): |
80 | taxAmount | O | N | Únicamente para Visanet/Paradox: |
125 | posAuthenticationMethod | O | A | Solo para Banamex: |
220 | paymentMobile | O | A | Únicamente para Banorte: Indica si nos encontramos en un pago mobile o no, lo cual habilita el ingreso manual o normal (chio/banda).
|
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.
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
6 | cardNumber | M | N16 | Número de tarjeta. Este valor es informado a la terminal pero no debe ser grabado en ningún lado para mantener las normas PCI, en caso de ser necesario el dato deberá enmascararse. |
10 | posInputMode | M | A | Es el modo de ingreso de la tarjeta: |
58 | loyaltyData | O | A | Únicamente para Bancomer: |
66 | track1 | M | A | Track1 de la tarjeta, es utilizado para obtener el "cardHolderName". Este campo no existe cuando el pago fue realizado en modo manual. |
125 | posAuthenticationMethod | O | A | Únicamente para Banamex y Bancomer: |
161 | cardType | O | A | Tipo de tarjeta, opcional si VTOL lo responde:
|
190 | comission | O | N12 | Campo Presente en caso de ser solicitada la configuración mediante el campo 218 en "cashAdvance", deberá enviarse luego un "additionalData". |
201 | additionalResponseCode | M | N2 | Código de respuesta generado por VTOL, actualmente VTOL lo reporta en el campo 27. |
202 | resetKeysOptional | O | A | Este campo indicará si el centro autorizador ha solicitado la carga de llaves opcionales. Valores:
|
204 | cardHolderName | O | A | Se reporta en el nombre del tarjeta habiente en caso de que exista. |
205 | aid | O | A | Card Application Identifier: |
206 | electronicSign | O | A | El valor "true" para este campo indica que se firmó electrónicamente el pago. |
207 | withoutSign | O | A | Para Bancomer: |
209 | acceptLoyaltyPoints | O | A | Uso solo para Bancomer. |
210 | providerName | O | A | El campo se encuentra presente si EMV/KIT se encuentra configurado para obtener configuración del "rsvtol.ini". |
211 | debit | O | A | El campo se encuentra presente si EMV/KIT se encuentra configurado para obtener configuración del "rsvtol.ini". |
212 | paymentPlanList | O | A | El campo se encuentra presente si EMV/KIT se encuentra configurado para obtener configuración del "rsvtol.ini". Ejemplo del campo con 1 solo plan de pago: “0|1” donde 0 es el plan y 1 la cantidad de cuotas. Ejemplo del campo con 2 planes de pagos: “0|1&1|12”, el primer plan de pago es plan 0 y cuotas 1; el segundo plan de pagos es plan 1 y cuotas 12. |
213 | cashBackAllowed | O | A | El campo se encuentra presente si EMV/KIT se encuentra configurado para obtener configuración del "rsvtol.ini". |
214 | applicationLabel | O | A(16) | Campo a ser impreso en el pagaré del tarjeta habiente. Se toma de la información obtenida del pinpad y podrá contener todos blancos. |
215 | preferredName | O | A(16) | Campo a ser impreso en el pagaré del tarjeta habiente. Se toma de la información obtenida del pinpad y podrá contener todos blancos. |
216 | criptograma | O | A(16) | Se infoma el criptograma a imprimir en el comprobante. |
217 | digitalSign | O | A (Hexadecimal) | Únicamente para Visanet/Paradox: |
221 | TVR | O | A | Únicamente para Banorte: Terminal Verification Results (Tag 95). |
222 | TSI | O | A | Únicamente para Banorte: Transactions Status Informations (Tag 9B). |
223 | expiryDate | Únicamente para Banorte: | ||
224 | Form Factor Ind | O | A | Únicamente para Banamex |
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:
- Debe tener habilitada la funcionalidad de RSVTOL.INI: "vtol.rsvtol.enabled=true"
- 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 informaran 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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "Sale". |
12 | amount | M | N10 | Monto de la transacción, los últimos 2 dígitos son decimales. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
7.3.2 Respuesta EMV/KIT – Pos
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
1 | store | AN | V10 | Identificador del sitio originador de la transacción |
2 | node | N | V10 | Identificación del nodo, en el sitio originador, donde se generó la transacción |
22 | authorizationCode | ANS | V10 | Código de autorización generado por el centro autorizador para la transacción. |
23 | authorizationMode | A | V7 | Modo de Autorización: |
24 | lastTrxId | N | V15 | Id de transacción. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | N | F14 | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | AN | V15 | Puede contener uno de los siguientes valores: |
27 | isoCode | N | V3 | Código de Respuesta generado por EMVKit. |
28 | responseMessage | ANS | V999 | Mensaje de la Respuesta ISO-8583 |
29 | serialNumber | N | V20 | Número identificatorio de la terminal en la que se procesó la transacción. |
32 | ticket | N | V4 | Número de Ticket correspondiente a la transacción. |
35 | errorDescription | ANS | V999 | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es "Error". |
68 | rrn | N | V20 | Reference referral number. |
134 | ticketMessage | ANS | V999 | Datos del ticket para impresión. |
201 | instructions | ANS | V999 | Mensaje de instrucciones |
202 | productDescription | ANS | V999 | Descripción del producto |
203 | sellerMessage | ANS | V999 | Mensaje hacia el vendedor |
1201 | additionalResponseCode | M | N2 | Código de respuesta generado por VTOL, actualmente VTOL lo reporta en el campo 27. |
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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "PTPromotionQuery". |
12 | amount | M | N10 | Monto de la transacción, los últimos 2 dígitos son decimales. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
7.4.2 Respuesta EMV/KIT – Pos
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
1 | store | AN | V10 | Identificador del sitio originador de la transacción |
2 | node | N | V10 | Identificación del nodo, en el sitio originador, donde se generó la transacción |
22 | authorizationCode | ANS | V10 | Código de autorización generado por el centro autorizador para la transacción. |
23 | authorizationMode | A | V7 | Modo de Autorización: |
24 | lastTrxId | N | V15 | Id de transacción. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | N | F14 | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | AN | V15 | Puede contener uno de los siguientes valores: |
27 | isoCode | N | V3 | Código de Respuesta generado por EMVKit. |
28 | responseMessage | ANS | V999 | Mensaje de la Respuesta ISO-8583 |
29 | serialNumber | N | V20 | Número identificatorio de la terminal en la que se procesó la transacción. |
32 | ticket | N | V4 | Número de Ticket correspondiente a la transacción. |
35 | errorDescription | ANS | V999 | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es "Error". |
68 | rrn | N | V20 | Reference referral number. |
134 | ticketMessage | ANS | V999 | Datos del ticket para impresión. |
200 | serviceInfo | ANS | V999 | Información adicional asociada al servicio |
201 | instructions | ANS | V999 | Mensaje de instrucciones |
202 | productDescription | ANS | V999 | Descripción del producto |
203 | sellerMessage | ANS | V999 | Mensaje hacia el vendedor |
1201 | additionalResponseCode | M | N2 | Código de respuesta generado por VTOL, actualmente VTOL lo reporta en el campo 27. |
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:
- 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".
- 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".
- 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".
- 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").
- 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.
- 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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "AdditionalData". |
14 | payments | C | N2 | Cantidad de cuotas/parcialidades (meses). 2 dígitos como máximo. |
15 | plan | C | A | Plan. 1 carácter de longitud. |
19 | lastTrxAction | C | A | Acción a realizar sobre la Transacción: |
22 | authorizationCode | C | A6 | Código de autorización telefónica. Este campo se encuentra presente únicamente si la transacción se autorizó offline por teléfono. |
23 | authorizationMode | O | A | Modo de Autorización: |
24 | lastTrxId | C | N10 | Id de transacción a confirmar / reversar. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. Debe ser exactamente el mismo valor enviado en el "Sale" o "Refund". |
65 | additionalAmount | O | N10 | Se indica el monto a aplicar a cashBack, valores posibles: |
125 | posAuthenticationMethod | O | A |
|
203 | cancelPayment | O | A | Se indica si el pago actual debe ser cancelado. Sus valores son:
|
208 | pointsPayment | O | A | Únicamente para Bancomer: |
218 | configurationRequest | O | A | En el mensaje "additionalData" este campo se envía en "false" cuando el código de respuesta fue "03", ver mensaje "cashAdvance" para más información de su uso. |
7.5.2 Respuesta EMV/KIT - Pos
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
26 | responseCode | M | AN7 | Puede contener uno de los siguientes valores: |
27 | isoCode | M | N2 | Código de respuesta generado. 2 caracteres máximo. Ver códigos de respuesta. |
28 | responseMessage | M | A100 | Descripción del código de Respuesta. |
201 | additionalResponseCode | M | N2 | Código de respuesta generado por VTOL, actualmente VTOL lo reporta en el campo 27. |
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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "resetKeys". |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
7.6.2 Respuesta EMV/KIT – Pos
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
26 | responseCode | M | AN7 | Puede contener uno de los siguientes valores: |
27 | isoCode | M | N2 | Código de respuesta generado. 2 caracteres máximo. Ver códigos de respuesta. |
28 | responseMessage | M | A100 | Descripción del código de Respuesta. |
201 | additionalResponseCode | M | N2 | Código de respuesta generado por VTOL, actualmente VTOL lo reporta en el campo 27. |
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.
3 | server | M | A4 | Valor fijo: VTOL |
Este tipo de mensaje puede ser usado para envío de:
- voidSale
- voidRefund
- 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 "7.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.
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
3 | server | M | A4 | Valor fijo: VD. |
218 | configurationRequest | O | A | Este campo es de tipo "boolean", por lo tanto acepta valores de tipo "true" o "false", la inexistencia de este campo se asume valor "false". |
7.8.2 Respuesta EMV/KIT – Pos
Dependiendo de las dos opciones mencionadas anteriormente, la respuesta deberá ser obtenida de la documentación pertinente.
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
190 | comission | O | N12 | Campo Presente en caso de ser solicitada la configuración mediante el campo 218. |
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.
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
3 | server | M | A4 | Valor fijo: VD. |
218 | configurationRequest | O | A | Este campo es de tipo "boolean", por lo tanto acepta valores de tipo "true" o "false", la inexistencia de este campo se asume valor "false". |
7.9.2 Respuesta EMV/KIT – Pos
La respuesta deberá ser obtenida de la documentación pertinente.
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
190 | comission | O | N12 | Campo Presente en caso de ser solicitada la configuración mediante el campo 218. |
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 "vtolDirect.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 "vtolDirect.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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "queryPan" o "queryBin". |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
7.10.2 Respuesta EMV/KIT – Pos
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
6 | cardNumber | M | N16 | Número de tarjeta obtenido, enmascarado o no o solo el bin, dependiendo del "trxType". |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
27 | isoCode | M | N2 | Código de respuesta generado. 2 caracteres máximo. Ver códigos de respuesta. |
28 | responseMessage | M | A100 | Descripción del código de Respuesta. |
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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "loadExceptionBins". |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
7.11.2 Respuesta EMV/KIT – Pos
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
27 | isoCode | M | N2 | Código de respuesta generado. 2 caracteres máximo. Ver códigos de respuesta. |
28 | responseMessage | M | A100 | Descripción del código de Respuesta. |
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
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
3 | server | M | A4 | Valor fijo: VD. |
11 | trxType | M | A22 | Identifica el tipo de transacción, en este caso será siempre "PointsLookup". |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
7.12.2 Respuesta EMV/KIT – Pos
La respuesta contiene todos los campos respondidos por VTOL.
# | Nombre | Req | Formato | Comentarios |
|---|---|---|---|---|
0 | company | O | A10 | Identificación de compañía. |
1 | store | M | N10 | Identificación de local. |
2 | node | M | N10 | Identificación de caja. |
6 | cardNumber | M | N16 | Número de tarjeta obtenido. |
25 | dateTime | M | yyyyMMddHHmmss | Fecha y hora de la transacción, de POS. |
27 | isoCode | M | N2 | Código de respuesta generado. 2 caracteres máximo. Ver códigos de respuesta. |
28 | responseMessage | M | A100 | Descripción del código de Respuesta. |
58 | loyaltyData | O | A | Únicamente para Bancomer: |
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}
Código | Descripción | Acción |
|---|---|---|
00 | La petición fue procesada correctamente. | Se ha realizado el pago correctamente, una vez terminada la transacción es necesario el envío del comando UnSyncCompletion e impresión de voucher con la información proporcionada en esta respuesta. |
01 | Mensaje de aviso. | De este mensaje se puede obtener el código de mensaje y descripción actual del estado de VtolStore. Muy útil en los casos que se desee indicar mensajes como "inserte tarjeta", "autorizando", "confirmando transacción", etc. El código descriptivo puede tomarse del campo 201. |
02 | Error en el mensaje | Revisar la documentación ya que el mensaje se encuentra incorrectamente armado. |
03 | Cuando el campo "218" se encuentre presente en "true" y la configuración de la cuenta se haya podido obtener. | En caso de mensaje "Sale" para funcionalidad "cashAdvance" (cuenta leída desde el pinpad) se deberá manejar como mensaje "additionalData". |
11 | Se ejecuta "Sale" o "Refund" y VTOL ha generado un error. | Obtener del campo 201 el "código de repuesta" de VTOL, revisar documento "VTOLCR-DB-Manual mensajeria POS - VTOL". |
12 | Se ejecuta "Sale" o "Refund" y es necesario enviar plan/cuotas. | Ejecutar "AdditionalData", con valores plan/cuotas. |
13 | Se ejecuta "Sale" o "Refund" y es necesario autorizar telefónicamente la transacción. | Ejecutar "AdditionalData", con valor authorizationCode. |
14 | Se ejecuta "Sale" o "Refund" y Vtol indica TrxIsPending sobre el ID informado en el campo 24. | Ejecutar "AdditionalData", con valores lastTrxId y lastTrxAction. |
15 | Se ejecuta "Sale" o "Refund" y se identifica que el bin ingresado necesita conocer si se desea pagar o no con puntos Bancomer. | Ejecutar "AdditionalData", con el valor "pointsPayment". |
16 | Se ejecuta "Sale" o "Refund" y se identifica que el bin ingresado necesita conocer si se desea retirar cashBack. | Ejecutar "AdditionalData", con el valor "additionalAmount". |
31 | Cuando el campo "218" se encuentre presente en "true" y la configuración de la cuenta no haya podido obtenerse. | Mensaje de error. |
99 | Error genérico | Revisar mensaje de error campo 28 y 201. |