VTOL CRÉDITO DÉBITO ARGENTINA
Mensajería POS - VTOL
Cambios por revisiones
Fecha | Revisión | Cambios |
02/11/2009 | 1.0 | Generación del documento |
04/11/2009 | 1.1 | Indicación de campos obligatorios |
26/04/2010 | 1.2 | Actualización de gráfico manejo de PINPAD |
22/03/2011 | 1.3 | Incorporación mensajes MembershipQuery y VoidMembershipQuery para consulta membresía Club Personal y Club La Nación |
03/06/2011 | 1.4 | Agregado de definición de mensaje de cierre de lote |
30/05/2012 | 1.5 | Agrego Tabla de Respuestas al POS y mejoro explicación de Tercer Mensaje y Chequeo de Pendientes. |
08/03/2013 | 1.6 | Agrego nuevos campos relacionados con operador y vendedor en operaciones de pre-autorización, venta, devolución y anulación. |
21/08/2013 | 1.7 | Agregado de apartado de error del core. |
09/09/2013 | 1.8 | Agrego campos EMV en operaciones de Venta, Devolución y anulación. Incorporo mensaje RejectedEMVAdvice y flujo de datos EMV. |
15/11/2013 | 1.9 | Agregado de 'Formato Interface POS' |
23/12/2013 | 2.0 | Agregado de detalle de los mensajes ServicePayment y VoidServicePayment |
13/02/2014 | 2.1 | Agregado del campo bandera '164 – posEncryptedFields', que indica cuando los datos sensibles viajan encriptados. |
29/05/2014 | 2.2 | Aclaración sobre el uso de pre-autorizaciones. |
22/08/2014 | 2.3 | Agregado de campo pinpadAutoCode en Tercer Mensaje y RejectedEMVAdvice. |
29/08/2014 | 2.4 | Actualización del Formato Interface POS, agregando el campo 'Tarjeta que Encripta' a los prefijos. |
11/09/2014 | 2.5 | Incorporación de Bines de Excepción y nuevo mensaje CardInfoService. |
09/12/2014 | 2.6 | Agregado de mensaje de Anulación de Pre Autorización. |
26/02/2015 | 2.7 | Agregado de nuevos campos ServiceCode y ProviderPosCode. |
27/02/2015 | 2.8 | Agregado de nuevos mensajes propios a la funcionalidad Cash Back. |
07/08/2015 | 2.9 | Agregado de aclaraciones en el uso de la mensajería |
09/09/2015 | 3.0 | Incorporación de campo PinpadApplicationVersion en los mensajes Sale, VoidSale, Refund y VoidRefund |
30/10/2015 | 3.1 | El campo ProviderPosCode para a ser el número 147. Incorporación de campo trxReferenceNumber en las respuestas de VTOL. Corrección de formato esperado en campo 7 - Expiration. El formato correcto es: YYMM. |
11/02/2016 | 3.2 | Incorporación del campo 201 additionalMessageData en el requerimiento y respuesta y la posibilidad de incluir el número de Ticket original en una anulación (Campo 17 originalTrxTicketNr) |
29/07/2016 | 3.3 | Incorporación del apartado 1.9. Mecanismo en Tiendas Virtuales y del 1.3.13. Chequeo de Listado de Pendientes |
19/04/2017 | 3.4 | Actualización de la tabla Prefijo en el apartado Formato Interface POS |
03/05/2017 | 3.5 | Incorporación del apartado 1.3.10 Echo |
05/05/2017 | 3.6 | Incorporación del apartado 1.3.9 SynQuery y de la sección 1.7 Formato Datos Sincronización |
06/06/2017 | 3.7 | Actualización de la tabla Prefijo en el apartado Formato Interface POS. Mayor detalle del campo MasterKey Position, incluyendo el valor 99 |
07/07/2017 | 3.8 | Agregado del campo promocional en Formato Interface POS para indicar que se aplica una promoción sobre un plan de pago. |
Índice
1. Campos de los mensajes
1.1 Conexión con VTOL Server
VTOL Server expone únicamente una comunicación SSL del tipo servidor, por defecto en el puerto 3003. Esta comunicación utiliza Protocolo TLSv1.2 e intercambio de certificado de seguridad.
Para poder conectarse al servidor, la implementación de la comunicación Cliente debe crear un Socket SSL con el puerto 3003, teniendo en cuenta las siguientes propiedades de conexión:
Parámetro | Descripción |
IP de VTOL Server | IP donde se encuentra VTOL Server. |
Puerto SSL de VTOL Server | Es el puerto SSL sonde escucha VTOL Server. Valor por defecto: 3003 |
Almacén de certificados del servidor | Ruta donde se encuentra el almacén de certificados con los certificados del servidor. |
Contraseña para acceder al almacén de certificados | Contraseña para acceder al almacén de certificados. |
Algoritmo del almacén de certificados | Algoritmo del manejador del almacén de certificados. Valor por defecto: SunX509 |
Tipo de almacén de certificados | Indica el tipo de almacén de certificados. Valor por defecto: JKS |
1.1.1 Ejemplo Comunicación Cliente SSL en JAVA
A continuación se puede ver un ejemplo de cómo crear una conexión cliente con VTOL Server a través de un socket SSL, teniendo en cuenta las propiedades mencionadas.
/** public SSLSocket connectToVTOLServer() throws Exception {
try{ long init = System.currentTimeMillis();
///////////////////////////////////////////////////////////////////////////////// // create de SSL Context ///////////////////////////////////////////////////////////////////////////////// KeyStore keyStore = KeyStore.getInstance("JKS"); String keyStorePass = this.keyStorePassword; // key store password keyStore.load(new FileInputStream(this.keyStorePath),keyStorePass.toCharArray()); //key store file
// Create key manager KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance("SunX509"); keyManagerFactory.init(keyStore, keyStorePass.toCharArray()); KeyManager[] km = keyManagerFactory.getKeyManagers();
// Create trust manager TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance("SunX509"); trustManagerFactory.init(keyStore); TrustManager[] tm = trustManagerFactory.getTrustManagers();
// TLSv1.2 Supports RFC 5246: TLS version 1.2 ; may support other versions String protocol = (sslProtocol != null) ? sslProtocol : "TLSv1.2"; SSLContext sslContext = SSLContext.getInstance(protocol);
// Initialize SSLContext sslContext.init(km, tm, null);
// Create socket factory SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();
// Create socket with VTOL Server SSLSocket sslSocket = (SSLSocket) sslSocketFactory.createSocket(this.hostIP, 3003); sslSocket.setSendBufferSize(400);
sslSocket.setEnabledCipherSuites(sslSocket.getSupportedCipherSuites());
// Start handshake sslSocket.startHandshake();
// Get session after the connection is established SSLSession sslSession = sslSocket.getSession();
System.out.println("SSLSession. Protocol: "+ sslSession.getProtocol() + " Cipher suite: " + sslSession.getCipherSuite());
System.out.println("SSL client started Time: " + (System.currentTimeMillis() - init) + " milliseconds.");
return sslSocket;
} catch (Exception exception) { throw new Exception("Error conectandose al host.\n" + exception.getMessage()); } } |
1.2 Protocolo de comunicación POS – VTOL Server
Synthesis establece un protocolo de comunicación para la interacción POS - VTOL, el cual se denomina "Protocolo VTOL". Dicho protocolo se basa en un esquema recursivo compuesto por campos y separadores. A continuación se provee una especificación detallada de su estructura junto con los consecuentes diagramas para un mejor entendimiento.
Para implementar esta mensajería, VTOL provee una librería en el cual se encuentra la declaración de funciones y las definiciones de constantes y tipos necesarias. La librería es en realidad un módulo cliente que se comunica vía TCP/IP con el servidor de transacciones VTOL. El cliente podrá implementar esta mensajería sin utilizar la librería, pero deberá respetar el formato de la misma.
El formato del protocolo VTOL se basa en la siguiente estructura:
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} |
La estructura posee dos partes separadas que son el Header y el Mensaje propiamente dicho.
1.2.1 Header
Dentro del Header viaja información específica del mensaje que se encuentra a continuación del mismo, como ser su longitud y si requiere o no una respuesta. Para ello fueron destinados 6 bytes que se distribuyen de la siguiente manera: los primeros 4 bytes son destinados a la longitud (expresado en hexadecimal, con el último byte como el más significativo) y los últimos 2 indican la necesidad de recibir o no una respuesta (expresado en hexadecimal, con el último byte como el más significativo)
Longitud máxima representable por medio de este protocolo: 2047 MB (Mega Bytes) (cantidad máxima representable por un entero: 2147483647 bytes)
Un ejemplo de lo explicado anteriormente podría ser el siguiente:
HEADER | |
Longitud del mensaje | Requiere respuesta |
A101 | 01 |
En este ejemplo la longitud del mensaje será:
0001 0000 0001 1010
1 0 1 A = 212 + 24 + 23 + 21 = 4122
NOTA: Se ordena la longitud A101 colocando el byte más significativo a la izquierda, con lo cual resulta: 101A.
1.2.1.1 Creación del Header
Ejemplo 1: Mensaje de 268 bytes de datos
Longitud (268) representada binario: 100001100, tiene 9 bits por lo tanto un byte no alcanza.
El header se representa en un arreglo de bytes, donde los primeros 4 bytes indican la longitud del área de datos:
byte[0] = longitud & 0xFF = 100001100 & 11111111 = 00001100 = 12
byte[1] = longitud >> 8 & 0xFF = 00000001 & 11111111 = 00000001 = 1 (>> 8 significa desplazar los bits 8 posiciones a la derecha)
byte[2] = longitud >> 16 & 0xFF = 00000000 & 11111111 = 00000000 = 0 (>> 16 significa desplazar los bits 16 posiciones a la derecha)
byte[3] = longitud >> 24 & 0xFF = 00000000 & 11111111 = 00000000 = 0 (>> 24 significa desplazar los bits 24 posiciones a la derecha)
Los últimos dos bytes indican si requiere respuesta. Ejemplo de un mensaje que requiere respuesta:
byte[4] = 0
byte[5] = 1
Header | Mensaje | |
Longitud del mensaje (4 bytes) | Indica si el mensaje requiere respuesta o no (2 bytes) | Campos de la operación con sus valores {campo1:valor1;campo2:valor2;…;campo3:valor3} |
Finalmente sería:
Header completo: {12, 1, 0, 0, 0, 1}
Ejemplo 2:
El mensaje de “CheckPending” enviado a VTOL Client, tiene una longitud de datos de 43 bytes: {25:20161021172545;2:1;1:1;11:CheckPending}
43 en binario: 101011 tiene menos de 8 bytes, la longitud puede expresarse completamente en el 1er. byte del arreglo:
byte[0] = longitud & 0xFF = 00101011 & 11111111 = 00101011 = 43
byte[1] = longitud >> 8 & 0xFF = 00000000 & 11111111 = 00000000 = 0 (>> 8 significa desplazar los bits 8 posiciones a la derecha)
byte[2] = longitud >> 16 & 0xFF = 00000000 & 11111111 = 00000000 = 0 (>> 16 significa desplazar los bits 16 posiciones a la derecha)
byte[3] = longitud >> 24 & 0xFF = 00000000 & 11111111 = 00000000 = 0 (>> 24 significa desplazar los bits 24 posiciones a la derecha)
Header completo indicando que requiere respuesta: {43, 0, 0, 0, 0, 1}
Hexa DUMP del mensaje:
00000: 2b 00 00 00 00 01 7b 32 35 3a 32 30 31 36 31 31 |,.....{25:201611|
00010: 31 37 32 31 30 38 30 32 3b 32 3a 31 3b 31 3a 31 |17210802;2:1;1:1|
00020: 3b 31 31 3a 43 68 65 63 6b 50 65 6e 64 69 6e 67 |;11:CheckPending|
00030: 7d 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |}...............|
1.2.1.2 Lectura del Header
Ejemplo: Mensaje de 268 bytes de datos.
Header completo {12, 1, 0, 0, 0, 1}
Para obtener la longitud de los datos enviados en el mensaje se toman los primero 4 bytes y se aplica la siguiente lógica:
byte[0] = 00001100 & 0xFF = 00001100 & 11111111 = 00101100 = 12
byte[1] = 00000001 & 0xFF << 8 = 00000001 & 11111111 = 00000001 << 8 = 1 00000000 = 256 (<< 8 significa desplazar los bits 8 posiciones a la izquierda)
byte[2] = 00000000 & 0xFF << 16 = 00000000 & 11111111 = 00000000 << 16 = 0 00000000 00000000 = 0 (<< 16 significa desplazar los bits 16 posiciones a la izquierda)
byte[3] = 00000000 & 0xFF << 24 = 00000000 & 11111111 = 00000000 << 24 = 0 00000000 00000000 00000000 = 0 (<< 24 significa desplazar los bits 24 posiciones a la izquierda)
Longitud obtenida a partir del arreglo de butes: 12 + 256 + 0 + 0 = 268
1.2.2 Mensaje
A continuación del Header se encuentra el Mensaje propiamente dicho, el cual contiene la información que el emisor desea transmitirle al sistema receptor.
Existen dos opciones para la estructura del Mensaje, las cuales se presentan a continuación:
Simple
El mensaje viajará encerrado entre "{ }" (llaves). Cada campo del mismo se compondrá de la siguiente manera: los primeros dígitos indicarán el número de campo y a partir de los ":" (dos puntos) se encontrará el valor del campo. Los campos viajan separados por ";" (punto y coma).
Ejemplo:
{1:5;2:1;26:ISO8583;27:00;28:Aprobado}
El mensaje anterior posee 5 campos, los cuales se identifican con los números 1, 2, 26, 27 y 28. A continuación de cada uno de ellos (luego del separador ":") se encuentra el valor de cada campo. En el ejemplo presentado, para el campo 1 el valor es "5", para el campo 2 el valor es "1" y así sucesivamente.
1.2.3 Escape de caracteres
Para realizar el escape de un caracter especial se deberá usar "\" inmediatamente antes del carácter a escapar.
Ejemplo:
A continuación se presenta un campo cuyo valor incluye el caracter ; y se muestra como escapar el mismo: {1:14\;56}
1.3 Mecanismo de "Tercer Mensaje"
1.3.1 Descripción
VTOL es un intermediario entre el POS y el Centro Autorizador. Cuando VTOL responde al POS un requerimiento a partir de la información recibida desde el Centro Autorizador, el mismo desconoce la interacción que se está teniendo entre el cliente y el operador y los problemas técnicos que pueda tener el POS (impresora, enlaces, etc). Es necesario cargar al POS con la responsabilidad de confirmar a VTOL cómo terminó la transacción, pudiéndose confirmar o reversar. Para ello existe el Tercer Mensaje del POS a VTOL.
Por lo tanto, el tercer mensaje es un mecanismo para asegurar la consistencia y concordancia de las transacciones realizadas que son registradas en VTOL.
A fines de simplificar el esquema de comunicación, suponiendo que el Centro Autorizador aprueba el requerimiento de VTOL, el flujo de mensajes entre el POS y VTOL es el siguiente:
- El POS envía un requerimiento de autorización a VTOL.
- VTOL responde al POS que el requerimiento fue autorizado y envía el ID de la transacción.
- El POS informa a VTOL con el Tercer Mensaje si la transacción se debe confirmar o reversar (COMMIT / ROLLBACK)
Dicho esquema requiere que cada transacción aprobada deba ser confirmada o reversada con un tercer mensaje. Si VTOL responde al POS con la aprobación de una transacción y no se confirma o reversa, a la próxima transacción que el POS envíe VTOL responderá que aún existe una transacción pendiente y hasta que no se envíe el tercer mensaje correspondiente no se podrá tratar la transacción en curso.
El tercer mensaje puede enviarse embebido en un requerimiento. Así en una misma transacción se enviará un requerimiento y la confirmación o reverso de una transacción pendiente.
No siempre cada transacción en el POS se corresponde con un único pago electrónico. Una operación de venta en el POS podría tener una o más transacciones de pago electrónico validadas por intermedio de VTOL. En dicho escenario, para el envío del tercer mensaje debe establecerse una condición por la que se da por finalizada la venta en el POS. Esta condición podría ser el registro de la transacción o la impresión del comprobante, pero se deberá tener en cuenta que para confirmar una transacción, VTOL se tiene que asegurar que la venta que contiene esa transacción sea procesada por el POS, que se emitan los comprobantes correspondientes, etc.
Por otro lado, si la venta en el POS se registra como anulada o directamente no se registra (ya sea por pedido del operador, o por problemas técnicos) se debe asegurar que en el tercer mensaje de las transacciones correspondientes vaya la orden de ROLLBACK para esta transacción.
1.3.2 Control de operaciones pendientes (mensaje "CheckPending")
Los mensajes de confirmación no son respondidos por VTOL. Además estos mensajes pueden ser embebidos en futuros mensajes de pedido de autorización, lo que da lugar a que algunas operaciones queden pendientes de confirmación entre dos transacciones distintas. El cierre o la eventual caída del punto de venta podrían ocasionar dicha contingencia ya que no existiría un futuro mensaje de confirmación o pedido de autorización con la confirmación embebida.
Ante esta problemática, el esquema de comunicación entre el POS y VTOL posee un mecanismo para asegurar que ninguna transacción quede pendiente de confirmación en VTOL. El mecanismo consta de los siguientes pasos:
- El punto de venta envía un mensaje de chequeo de pendientes "CheckPending" a VTOL. Para ello, el mensaje debe contar con el siguiente campo: 71:True.
2. VTOL verificará la existencia de transacciones pendientes y en caso de existir responderá con un mensaje que, entre otros campos, tendrá los siguientes:
Campo 24: ID de la Transacción pendiente.
Campo26: TrxIsPending.
3. El punto de venta envía la confirmación de dicha transacción (Commit/Rollback) y envía un nuevo mensaje de chequeo de pendientes. Esto se podría realizar en un solo paso, enviando un mensaje de chequeo de pendientes con la confirmación embebida.
4. Se deberá repetir el proceso hasta tanto existan transacciones pendientes en VTOL. Cuando ya no existan VTOL responderá APROBADA.
1.3.3 Tercer Mensaje con múltiples operaciones
También existe la posibilidad de deshabilitar el chequeo de pendientes (Campo 71:False). Esto permite realizar un conjunto de transacciones que podrán ser confirmadas o reversadas posteriormente haciendo que VTOL se dedique a la transacción en curso. Por ejemplo: 
1.4 Transacciones permitidas
En esta sección se detallarán las transacciones soportadas por VTOL así como los campos requeridos u opcionales de cada transacción.
1.4.1 Venta / Pre-autorización / Anulación / Anulación Pre-autorización / Cash Back / Anulación Cash Back
1.4.1.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | SI | Identificador del sitio originador de la transacción |
2 | node | Numérico | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás. | Identificador del Server que procesará la transacción. ('VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás. | Tipo de Mensaje:
|
6 | cardNumber | Numérico | Obligatorio si es Manual | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. |
7 | expiration | Numérico | Obligatorio si es Manual | Formato YYYYMM Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
8 | Cvc | Numérico | Obligatorio si es Manual. Además es opcional según la tarjeta. | Código de seguridad de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
9 | track2 | Alfanumérico | Obligatorio si es MSR | 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 | posInputMode | Alfanumérico | Obligatorio | Modo de Ingreso:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | 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 | Obligatorio | Tipos de Moneda:
|
14 | payments | Numérico | Obligatorio | Cantidad de cuotas. 2 dígitos como máximo. |
15 | plan | Alfanumérico | Obligatorio | Plan. 1 caracter de longitud. |
17 | originalTrxTicketNr | Numérico | Opcional | Este campo es Opcional. Si viaja se debe precisar el número de ticket de la venta original para poder distinguir la transacción a anular. Se trata del número de ticket de la transacción original. 4 dígitos como máximo. |
18 | referedSale | Numérico | Condicional a tarjeta AMEX | 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 | Numérico | Condicional a si fue realizada la autorización telefónica. | 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. |
23 | authorizationMode | Alfanumérico | Opcional, default = Online | Modo de Autorización:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
53 | paymentCondition | Alfanumérico | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. |
54 | additionalAmount | Alfanumérico |
| Contiene el Importe del "Cash Back". Se usa en transacciones del tipo CashBack o Sale + CashBack. Debe contener 12 dígitos como máximo |
56 | pinblock | Alfanumérico | Condicional a PINPAD | PIN encriptado. Se emplea para tarjetas que tienen PIN. Ejemplo pinblock: D76484D688FE1826 |
57 | accountType | Alfanumérico | Condicional a tarjeta de débito | Campo que se emplea para identificar el tipo de cuenta (ej: cta cte en pesos) Se usa para tarjetas de débito. Los valores posibles son:
|
66 | track1 | Alfanumérico | Opcional a su lectura | Track1 de la tarjeta entero (se envía todo el contenido del track1 en este campo) Este campo sólo está presente si la banda magnética / chip de la tarjeta pudo ser leído. |
70 | effectiveDate | Alfanumérico | Opcional AMEX | Fecha efectiva. Se usa para AMEX con formato yyMM |
71 | checkPendingString | Alfanumérico | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
72 | creditCardCondition | Alfanumérico | Opcional | Es una cadena de 3 de largo donde se indica una condición de la tarjeta. Se usa para las tarjetas regionales o propias donde los prefijos se superponen. Este valor es identificable en el TrackI de la tarjeta y si es manual se le pregunta al cajero. |
73 | interestAmount | Alfanumérico | Opcional | 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 | Opcional, default = 0 | Indica si puede recibir el número de cuenta (Visa y Posnet). Valores posible:
|
101 | differDate | Alfanumérico | Opcional | Fecha diferida. Solo utilizada para AMEX. |
102 | chipTokens | Alfanumérico | Obligatorio para modo de ingreso Chip | Visa: Criptograma tarjetas EMV |
103 | emvEncryptedType | Alfanumérico | Opcional | Tipo de encriptación utilizada entre Pinpad y Host Autorizador.
|
104 | emvEncryptedData | Alfanumérico | Opcional | Paquete encriptado devuelto por el pinpad y que se enviará al Host Autorizador. |
105 | cardSequenceNumber | Numérico | Opcional | Numero de secuencia del PAN |
106 | pinpadLogSerialNumber | Alfanumérico | Opcional | Número de serie lógico del pinpad |
107 | pinpadFisSerialNumber | Alfanumérico | Opcional | Número de serie Físico del pinpad |
108 | useEncryptedData | Alfanumérico | Opcional | Indica si se utiliza encriptación entre Pinpad y Host Autorizador (Visa, Posnet, etc).
|
118 | terminalCapability | Alfanumérico | Opcional | Capacidad de captura. Valores 1 = Manual / 2 = Lectura de Banda / 5 = Lectura de Chip |
130 | posPeriod | Numérico | Opcional | Periodo enviado por el POS. Longitud 5 |
131 | turn | Numérico | Opcional | Turno. Longitud 2 |
132 | operatorCode | Alfanumérico | Opcional | Código de operador. Longitud 20 |
133 | operatorName | Alfanumérico | Opcional | Nombre de operador. Longitud 50 |
134 | sellerCode | Alfanumérico | Opcional | Código del vendedor. Longitud 20 |
135 | sellerName | Alfanumérico | Opcional | Nombre del vendedor. Longitud 50 |
136 | attentionMode | Alfanumérico | Opcional | Modalidad de atención (AU ó AS). Longitud 2 |
137 | serviceCode | Numérico | Opcional | Código de Servicio, se envía cuando el mensaje esta encriptado (campo 108=true) y no se tiene acceso al Track2. Longitud 3. |
147 | providerPosCode | Alfanumérico | Opcional | Código del Provider. Se utiliza en los casos donde VTOL Server no puede obtener unívocamente el Proveedor utilizando los prefijos (debido enmascaramiento de la tarjeta). Ejemplo VI (Visa). Longitud 20. |
164 | posEncryptedFields | Numérico | Opcional | Indica si se utiliza encripción entre Pinpad y VTOL (modo RSA). En este caso los datos sensibles se envían encriptados. Si está activo, los campos a enviar encriptados son: 6, 8, 9, 66
|
168 | pinpadApplicationVersion | Alfanumérico | Opcional | Versión de la aplicación del software del PinPad- |
201 | additionalMessageData | Alfanumérico | Opcional | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.1.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
22 | authorizationCode | Numérico | Código de autorización generado por el centro autorizador para la transacción. |
23 | authorizationMode | Alfanumérico | Modo de Autorización:
|
24 | lastTrxId | Numérico | Id de transacción. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 |
29 | serialNumber | Numérico | Número identificatorio de la terminal en la que se procesó la transacción. |
30 | businessNumber | Numérico | Número de comercio en el que se procesó la transacción. |
31 | lotNumber | Numérico | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
33 | creditCardIssuerName | Alfanumérico | Nombre del Centro emisor de la tarjeta |
34 | hostName | Alfanumérico | Nombre del canal por el cual se autorizó la tarjeta. |
35 | errorDescription | Alfanumérico | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es "Error". |
42 | lotDefinitionId | Numérico | Identificador de la definición de lote. |
58 | workingKey | Alfanumérico | VTOL devuelve este campo tal como lo entrega el CA. Representa la llave que el PINPAD deberá usar para generar el PINBLOCK en la próxima transacción. |
68 | rrn | Numérico | Reference referral number. |
75 | accountNumber | Numérico | Número de cuenta. Este campo es devuelto si el campo 74- requestAccountNumber fue activado en el requerimiento. |
81 | responseAuth | Alfanumérico | Mensaje de repuesta para ser mostrado en el diplay del POS donde se indican promociones. |
82 | softwareVersion | Alfanumérico | Versión de la aplicación. |
102 | chipTokens | Alfanumérico | En las respuestas hacia el POS se actualiza con el valor que envió el CA |
110 | requeredAdvice | Alfanumérico | Con valor true si se requiere que se envíe el advice para la autorización. En este caso la terminal lógica queda en estado AdvicePending. |
130 | posPeriod | Numérico | Periodo enviado por el POS. Longitud 5 |
131 | turn | Numérico | Turno. Longitud 2 |
132 | operatorCode | Alfanumérico | Código de operador. Longitud 20 |
133 | operatorName | Alfanumérico | Nombre de operador. Longitud 50 |
134 | sellerCode | Alfanumérico | Código del vendedor. Longitud 20 |
135 | sellerName | Alfanumérico | Nombre del vendedor. Longitud 50 |
136 | attentionMode | Alfanumérico | Modalidad de atención (AU ó AS). Longitud 2 |
165 | publicKey | Alfanumérico | Clave Pública utilizada en la encripción punto a punto POS - VTOL. Viaja cuando la clave expiró y se generó una nueva; o bien, cuando es necesario sincronizar claves entre POS y VTOL. |
166 | trxReferenceNumber | Numérico | 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. |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.1.3 Pre-autorización
La pre-autorización es utilizada para validar y reservar un saldo de una tarjeta en vías de asegurarse que se podrá saldar la transacción de productos que primero se consumen y luego se pagan siendo difícil o imposible devolverlos en caso de no haber saldo.
Ejemplos en donde se podría utilizar éste tipo de transacción es el despacho de combustible, pago en restaurants con propina, etc.
El flujo normal de ésta operatoria es el siguiente:
- Se realiza una pre-autorización por un monto X.
- Se debe almacenar el código de autorización recibido en la respuesta
- Se lleva a cabo la venta de los productos
- finalizada la venta se procede a realizar una venta por el momento exacto e incorporando el código de autorización recibido en el paso 1. El sistema aprobará automáticamente ésta transacción.
1.4.1.4 Anulación de Pre-autorización
La anulación de Pre-Autorización sirve para anular completamente una Pre-autorización realizada previamente. Dado el caso de que un cliente se arrepienta de realizar la compra, por ejemplo, en una estación de servicio el cliente se arrepiente de cargar combustible, en este caso ,es necesario realizar una anulación de la Pre autorización para que el monto retenido por la pre autorización sea devuelto al cliente.
El flujo normal de ésta operatoria es el siguiente:
- Se realiza una pre-autorización por un monto X.
- Por algún motivo, como el expuesto mas arriba, es necesario anular la pre-autorización y reintegrar el monto retenido al cliente. Mientras se esté en el mismo periodo que la operación original, se puede enviar el mensaje de anulación de pre-autorización.
La Anulación de una pre-autorización no se incluirá en los archivos de cierre o TEF.
1.4.1.5 Cash Back / Anulación Cash Back
Los clientes de Visa pueden extraer efectivo en los negocios habilitados para este tipo de operación, previo a realizar una compra con su tarjeta o bien incluirla junto con la compra.
El flujo normal de ésta operatoria es el siguiente:
Compra + Cash Back (TrxType = Sale)
- Se envía la compra desde el POS junto con el importe del Cash Back en el campo 54 - additionalAmount. El importe de la compra también debe viajar en el campo 12 - amount.
Tipo de mensaje Cash Back (trxType = CashBack).
- Se envía el mensaje desde el POS. En este caso, el importe de Cash Back del campo 54 - additionalAmount y el importe total (campo 12 - amount) deben coincidir. Además el número de cuotas debe viajar con valor 1.
Anulación de Compra + Cash Back (trxType = VoidSale)
Esta opción se utilizará para anular una operación de Compra + Cash Back existente dentro del mismo periodo contable. Es decir, no se ha realizado el Cierre de Lote.
Anulación de Cash Back (trxType = VoidCashBack)
Esta operación se utiliza cuando se intenta anular un mensaje Cash Back enviado de manera explícita (trxType = CashBack). Es decir, cuando no se incluyó como parte de una compra.
Es necesario incluir el número de cupón del mensaje Cash Back original para poder identificar la operación a anular.
Importante: Todas las operaciones que involucran Cash Back solo pueden realizarse de manera "On-Line" y el importe otorgado es en la misma moneda.
1.4.1.6 Anulación
La anulación sirve para anular completamente una venta previa. La diferencia con una devolución, es que la cancelación se hace por el monto total de la venta, en cambio la devolución puede ser parcial.
Además la cancelación implica un reintegro instantáneo, mientras que la devolución puede tardar unos días (dependerá de la tarjeta).
Tener en consideración que la anulación solo se puede realizar mientras el lote de transacciones esté abierto en VTOL, esto es en el mismo día.
1.4.2 Devolución
La estructura del mensaje de devolución es igual al del mensaje de venta, con la diferencia que se agregan dos campos que identifican a la transacción original sobre la que se hace la devolución: originalDate y originalTrxTicketNr.
1.4.2.1 Requerimiento
Nota: A continuación se toma como base el tipo de mensaje de Sale y se agregan las diferencias.
# | FieldId | Tipo | Descripción |
11 | trxType | Alfanumérico | Tipo de Transacción:
|
12 | amount | Importe | Monto de la transacción. 12 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: 1000 equivale a 10.00 |
13 | currencyPosCode | Alfanumérico | Tipos de Moneda:
|
14 | payments | Numérico | Cantidad de cuotas. 2 dígitos como máximo. |
15 | plan | Alfanumérico | Código de plan. Largo 1. |
16 | originalDate | Fecha | Este campo debe viajar si el tipo de transacción es Refund. Se trata de la fecha de la transacción original en el formato YYYYMMDD. |
17 | originalTrxTicketNr | Numérico | Este campo debe viajar si el tipo de transacción es Refund. Se trata del número de ticket de la transacción original. 4 dígitos como máximo. |
53 | paymentCondition | Alfanumérico | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.2.2 Respuesta
Nota: Tomar como referencia la respuesta del tipo de mensaje Sale
1.4.3 ServicePayment
Mensaje utilizado para el pago de resumen de cuenta de una tarjeta de crédito.
1.4.3.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | SI | Identificador del sitio originador de la transacción |
2 | node | Numérico | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás. | Identificador del Server que procesará la transacción. ('VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás. | Tipo de Mensaje:
|
6 | cardNumber | Numérico | Obligatorio si es Manual | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. |
7 | expiration | Numérico | Obligatorio si es Manual | Formato YYYYMM Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
8 | Cvc | Numérico | Obligatorio si es Manual. Además es opcional según la tarjeta. | Código de seguridad de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
9 | track2 | Alfanumérico | Obligatorio si es MSR | 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 | posInputMode | Alfanumérico | Obligatorio | Modo de Ingreso:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | 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 | Obligatorio | Tipos de Moneda:
|
14 | payments | Numérico | Obligatorio | Cantidad de cuotas. 2 dígitos como máximo. |
15 | plan | Alfanumérico | Obligatorio | Plan. 1 caracter de longitud. |
22 | authorizationCode | Numérico | Condicional a si fue realizada la autorización telefónica. | 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. |
23 | authorizationMode | Alfanumérico | Opcional, default = Online | Modo de Autorización:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
53 | paymentCondition | Alfanumérico | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. |
56 | pinblock | Alfanumérico | Condicional a PINPAD | PIN encriptado. Se emplea para tarjetas de débito. Ejemplo pinblock: D76484D688FE1826 |
57 | accountType | Alfanumérico | Condicional a tarjeta de débito | Campo que se emplea para identificar el tipo de cuenta (ej: cta cte en pesos) Se usa para tarjetas de débito. Los valores posibles son:
|
66 | track1 | Alfanumérico | Opcional a su lectura | Track1 de la tarjeta entero (se envía todo el contenido del track1 en este campo) Este campo sólo está presente si la banda magnética / chip de la tarjeta pudo ser leído. |
70 | effectiveDate | Alfanumérico | Opcional AMEX | Fecha efectiva. Se usa para AMEX con formato yyMM |
71 | checkPendingString | Alfanumérico | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
72 | creditCardCondition | Alfanumérico | Opcional | Es una cadena de 3 de largo donde se indica una condición de la tarjeta. Se usa para las tarjetas regionales o propias donde los prefijos se superponen. Este valor es identificable en el TrackI de la tarjeta y si es manual se le pregunta al cajero. |
73 | interestAmount | Alfanumérico | Opcional | 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 | Opcional, default = 0 | Indica si puede recibir el número de cuenta (Visa y Posnet). Valores posible:
|
101 | differDate | Alfanumérico | Opcional | Fecha diferida. Solo utilizada para AMEX. |
147 | providerPosCode | Alfanumérico | Opcional | Código del Provider. Se utiliza en los casos donde VTOL Server no puede obtener unívocamente el Proveedor utilizando los prefijos (debido enmascaramiento de la tarjeta). Ejemplo VI (Visa). Longitud 20. |
164 | posEncryptedFields | Numérico | Opcional | Indica si se utiliza encripción entre Pinpad y VTOL (modo RSA). En este caso los datos sensibles se envían encriptados. Si está activo, los campos a enviar encriptados son: 6, 8, 9, 66
|
201 | additionalMessageData | Alfanumérico |
| Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.3.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
22 | authorizationCode | Numérico | Código de autorización generado por el centro autorizador para la transacción. |
23 | authorizationMode | Alfanumérico | Modo de Autorización:
|
24 | lastTrxId | Numérico | Id de transacción. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 |
29 | serialNumber | Numérico | Número identificatorio de la terminal en la que se procesó la transacción. |
30 | businessNumber | Numérico | Número de comercio en el que se procesó la transacción. |
31 | lotNumber | Numérico | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
33 | creditCardIssuerName | Alfanumérico | Nombre del Centro emisor de la tarjeta |
34 | hostName | Alfanumérico | Nombre del canal por el cual se autorizó la tarjeta. |
35 | errorDescription | Alfanumérico | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es "Error". |
42 | lotDefinitionId | Numérico | Identificador de la definición de lote. |
58 | workingKey | Alfanumérico | VTOL devuelve este campo tal como lo entrega el CA. Representa la llave que el PINPAD deberá usar para generar el PINBLOCK en la próxima transacción. |
68 | rrn | Numérico | Reference referral number. |
75 | accountNumber | Numérico | Número de cuenta. Este campo es devuelto si el campo 74- requestAccountNumber fue activado en el requerimiento. |
81 | responseAuth | Alfanumérico | Mensaje de repuesta para ser mostrado en el diplay del POS donde se indican promociones. |
165 | publicKey | Alfanumérico | Clave Pública utilizada en la encripción punto a punto POS - VTOL. Viaja cuando la clave expiró y se generó una nueva; o bien, cuando es necesario sincronizar claves entre POS y VTOL. |
166 | trxReferenceNumber | Numérico | 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. |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.4 VoidServicePayment
Anulación de pago de resumen de tarjeta de crédito.
1.4.4.1 Requerimiento
Nota: A continuación se toma como base el tipo de mensaje de ServicePayment y se agregan las diferencias.
# | FieldId | Tipo | Obligatorio | Descripción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
1.4.4.2 Respuesta
Nota: Tomar como referencia la respuesta del tipo de mensaje ServicePayment
1.4.5 Consulta Membresía/Anulación Consulta Membresía
Las transacciones de membresía sirven para validar que la tarjeta asociada a la transacción es miembro y/o está vigente.
Algunos ejemplos de tarjetas asociadas son:
- Club La Nación
- Clarín 365
- Club Personal
- Etc
1.4.5.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | SI | Identificador del sitio originador de la transacción |
2 | node | Numérico | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás. | Identificador del Server que procesará la transacción. (en el caso de VTOL será 'VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás. | Tipo de Mensaje:
|
6 | cardNumber | Numérico | Obligatorio si es Manual | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. |
7 | expiration | Numérico | Obligatorio si es Manual | Formato YYYYMM Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
9 | track2 | Alfanumérico | Obligatorio si es MSR | 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 | posInputMode | Alfanumérico | Obligatorio | Modo de Ingreso:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | 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 | Obligatorio | Tipos de Moneda:
|
23 | authorizationMode | Alfanumérico | Opcional, default = Online | Modo de Autorización:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
53 | paymentCondition | Alfanumérico | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. |
71 | checkPendingString | Alfanumérico | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
73 | interestAmount | Alfanumérico | Opcional | 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 | Opcional, default = 0 | Indica si puede recibir el número de cuenta (Visa y Posnet). Valores posible:
|
147 | providerPosCode | Alfanumérico | Opcional | Código del Provider. Se utiliza en los casos donde VTOL Server no puede obtener unívocamente el Proveedor utilizando los prefijos (debido enmascaramiento de la tarjeta). Ejemplo VI (Visa). Longitud 20. |
164 | posEncryptedFields | Numérico | Opcional | Indica si se utiliza encripción entre Pinpad y VTOL (modo RSA). En este caso los datos sensibles se envían encriptados. Si está activo, los campos a enviar encriptados son: 6, 9
|
201 | additionalMessageData | Alfanumérico | Opcional | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.5.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
22 | authorizationCode | Numérico | Código de autorización generado por el centro autorizador para la transacción. |
23 | authorizationMode | Alfanumérico | Modo de Autorización:
|
24 | lastTrxId | Numérico | Id de transacción. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 |
29 | serialNumber | Numérico | Número identificatorio de la terminal en la que se procesó la transacción. |
30 | businessNumber | Numérico | Número de comercio en el que se procesó la transacción. |
31 | lotNumber | Numérico | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
33 | creditCardIssuerName | Alfanumérico | Nombre del Centro emisor de la tarjeta |
34 | hostName | Alfanumérico | Nombre del canal por el cual se autorizó la tarjeta. |
35 | errorDescription | Alfanumérico | Descripción de error. Sólo se encuentra presente si el valor del campo 26 es "Error". |
42 | lotDefinitionId | Numérico | Identificador de la definición de lote. |
58 | workingKey | Alfanumérico | VTOL devuelve este campo tal como lo entrega el CA. Representa la llave que el PINPAD deberá usar para generar el PINBLOCK en la próxima transacción. |
68 | rrn | Numérico | Reference referral number. |
75 | accountNumber | Numérico | Número de cuenta. Este campo es devuelto si el campo 74- requestAccountNumber fue activado en el requerimiento. |
81 | responseAuth | Alfanumérico | Mensaje de repuesta para ser mostrado en el diplay del POS donde se indican promociones. |
165 | publicKey | Alfanumérico | Clave Pública utilizada en la encripción punto a punto POS - VTOL. Viaja cuando la clave expiró y se generó una nueva; o bien, cuando es necesario sincronizar claves entre POS y VTOL. |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.6 Consulta de Configuración
Por medio de éste mensaje, el POS puede solicitar a VTOL el envío de la configuración generada a partir de la ejecución de la interface para POS.
El POS debe enviar en el mensaje el número de versión de la configuración que posee, de esta manera VTOL puede validar si es necesario devolver la información o no.
A nivel implementación se recomienda no ejecutar éste mensaje entre cada mensaje de autorización ya que podría degradar la performance del sistema.
Es recomendable hacerlo en alguno de los siguientes casos:
- Cuando un operador hace login
- Cada una X cantidad de tiempo. Por ejemplo, cada 1 hora
- Cuando el punto de venta inicia (dependiendo frecuencia)
- Opcionalmente, proveer al sistema integrador una opción para forzar el cambio de configuración manualmente (que manualmente se dispare el proceso de actualización)
- etc
Nota: si el POS no posee número de configuración debe enviar el valor por defecto 0 (cero), ya que VTOL valida que el campo versión siempre esté presente.
1.4.6.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | SI | Identificador del sitio originador de la transacción |
2 | node | Numérico | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás | Identificador del Server que procesará la transacción. ('VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás | Tipo de Mensaje:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
71 | checkPendingString | Alfanumérico | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
137 | confVersion | numérico | Obligatorio | Número de versión de la configuración que posee el POS. En caso de que el POS no posea configuración previa, se debe enviar el campo con valor 0 y de esta manera evitar el error de validación por ausencia del campo. |
201 | additionalMessageData | Alfanumérico | Opcional | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.6.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
24 | trxId | Numérico | OPCIONAL. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por VTOL. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Valor fijo ISO-8583. |
137 | confVersion | numérico | Número de versión de la configuración más actual. Si el número es distinto al enviado en el requerimiento, entonces el POS debe actualizar la configuración. |
138 | confData | Alfanumérico | Configuración creada en la generación de la Interface para POS, codificada en Base64. |
165 | publicKey | Alfanumérico | Clave Pública vigente utilizada en la encripción punto a punto entre POS - VTOL |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.7 Servicio de Información de Tarjeta
Permite consultar información adicional de una tarjeta, según sea de Crédito Debito o de Excepción.
Cuando VTOL recibe este mensaje, primero realiza una identificación del tipo de tarjeta, determinando si se trata de una Tarjeta de Crédito/Débito o de Excepción.
La información que se devuelve al POS se basa en el tipo de tarjeta:
Si es de excepción
- Nombre de tarjeta de Excepción
- Información adicional.
- Si en el requerimiento viene encendido el campo de encriptado (campo 164 = 1), se intentará descencriptar todos los datos sensibles, devolviéndolos en texto plano.
Si es crédito/débito
- Descripción tipo de Tarjeta.
- Nombre de la tarjeta
- Código de Tarjeta.
- Medio de Pago
NOTA:
- Para las tarjetas Crédito Debito no se retorna ningún dato sensible en texto plano.
- Cuando viene encendido el campo de encriptado (campo 164=1), se deben enviar todos los datos sensibles encriptados. Si alguno de ellos viaja en texto plano se producirá un error y será notificado en la respuesta.
1.4.7.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás. | Identificador del Server que procesará la transacción. ('VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás. | Tipo de Mensaje:
|
6 | cardNumber | Numérico | Opcional | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. |
7 | expiration | Numérico | Opcional | Formato YYYYMM. Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
8 | cvc | Numérico | Opcional | Código de seguridad de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
9 | track2 | Alfanumérico | Opcional | Track2 de la tarjeta entero. Este campo sólo está presente si la banda magnética / chip de la tarjeta pudo ser leído. |
10 | posInputMode | Alfanumérico | Obligatorio | Modo de Ingreso:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
66 | track1 | Alfanumérico | Opcional a su lectura | Track1 de la tarjeta entero. Este campo sólo está presente si la banda magnética / chip de la tarjeta pudo ser leído. |
71 | checkPendingString | Alfanumérico | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
137 | serviceCode | Numérico | Opcional | Código de Servicio, se envía cuando el mensaje esta encriptado y no se tiene acceso al Track2. Longitud 3. |
147 | providerPosCode | Alfanumérico | Opcional | Código del Provider. Se utiliza en los casos donde VTOL Server no puede obtener unívocamente el Proveedor utilizando los prefijos (debido enmascaramiento de la tarjeta). Ejemplo VI (Visa). Longitud 20. |
164 | posEncryptedFields | Numérico | Opcional | Indica si se utiliza encripción entre Pinpad y VTOL (modo RSA). En este caso los datos sensibles se envían encriptados. Si está activo, los campos a enviar encriptados son: 6, 8, 9, 66
|
201 | additionalMessageData | Alfanumérico | Opcional | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.7.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
6 | cardNumber | Numérico | Número de tarjeta en texto plano. Opcional: Presente solo para Tarjeta de Excepción. |
7 | expiration | Numérico | Fecha de vencimiento de la tarjeta en texto plano. Opcional: Presente solo para Tarjeta de Excepción. |
8 | cvc | Numérico | Código de seguridad de la tarjeta. Opcional: Presente solo para Tarjeta de Excepción. |
9 | track2 | Alfanumérico | Track2 de la tarjeta entero. Opcional: Tarjeta de Excepción. |
24 | trxId | Numérico | OPCIONAL. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por VTOL. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Valor fijo ISO-8583 |
66 | track1 | Alfanumérico | Track1 de la tarjeta entero. Opcional: Presente solo para Tarjeta de Excepción. |
140 | cardType | Alfanumérico | Descripción de tipo de tarjeta. Opcional: Presente solo para Tarjeta de Crédito / Debito. |
141 | isDebit | Numérico | Indicador si la tarjeta es de Débito (0: no es débito, 1: es debito). Opcional: Presente solo para Tarjeta de Crédito / Debito. |
142 | providerName | Alfanumérico | Nombre de la tarjeta. Opcional: Presente solo para Tarjeta de Crédito / Debito. |
143 | providerPosCode | Alfanumérico | Código de tarjeta. Opcional: Presente solo para Tarjeta de Crédito / Debito. |
144 | providerPosTenderCode | Alfanumérico | Medio de Pago. Opcional: Presente solo para Tarjeta de Crédito / Debito. |
145 | exceptionBinName | Alfanumérico | Nombre de la tarjeta de Excepción. Opcional: Presente solo para Tarjeta de Excepción. |
146 | exceptionBinData | Alfanumérico | Información adicional de la tarjeta de excepción. Opcional: Presente solo para Tarjeta de Excepción. |
165 | publicKey | Alfanumérico | Clave Pública utilizada en la encripción punto a punto POS - VTOL. Viaja cuando la clave expiró y se generó una nueva; o bien, cuando es necesario sincronizar claves entre POS y VTOL. |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.8 EMV Advice de Rechazo
Mensaje implementado para enviar un Advice al autorizador en caso de que el PINPAD rechace la autorización en primera decisión de la tarjeta en comando Y02, y segunda decisión en comando Y03, cuando la operación inicial fue rechaza por el autorizador.
El mensaje no está vinculado a ninguna autorización previa. Es solamente informativo hacia el centro autorizador.
1.4.8.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | SI | Identificador del sitio originador de la transacción |
2 | node | Numérico | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás. | Identificador del Server que procesará la transacción. ('VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás. | Tipo de Mensaje:
|
8 | cvc | Numérico | Obligatorio si es Manual. Además es opcional según la tarjeta. | Código de seguridad de la tarjeta. Sólo presente si el modo de ingreso fue Manual. |
9 | track2 | Alfanumérico | Opcional, default = true | 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 | posInputMode | Alfanumérico | Obligatorio | Modo de Ingreso:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
12 | amount | Importe | Obligatorio | 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 | Obligatorio | Tipos de Moneda:
|
14 | payments | Numérico | Obligatorio | Cantidad de cuotas. 2 dígitos como máximo. |
15 | plan | Alfanumérico | Obligatorio | Plan. 1 caracter de longitud. |
25 | dateTime | Numérico | Obligatorio | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
53 | paymentCondition | Alfanumérico | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. |
56 | pinblock | Alfanumérico | Condicional a PINPAD | PIN encriptado. Se emplea para tarjetas de débito. |
57 | accountType | Alfanumérico | Condicional a tarjeta de débito | Campo que se emplea para identificar el tipo de cuenta (ej: cta cte en pesos) Se usa para tarjetas de débito. Los valores posibles son: |
66 | track1 | Alfanumérico | Opcional a su lectura | Track1 de la tarjeta entero (se envía todo el contenido del track1 en este campo) Este campo sólo está presente si la banda magnética / chip de la tarjeta pudo ser leído. |
71 | checkPendingString | Alfanumérico | Opcional | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
102 | chiptokens | Alfanumérico | Obligatorio | Visa: Criptograma tarjetas EMV |
103 | emvEncryptedType | Alfanumérico | Opcional | Tipo de encriptación utilizada entre Pinpad y Host Autorizador.
|
104 | emvEncryptedData | Alfanumérico | Opcional | Paquete encriptado devuelto por el pinpad y que se enviará al Host Autorizador. |
105 | cardSecuenceNumber | Numérico | Opcional a PINPAD | Numero de secuencia del PAN |
106 | pinpadLogSerialNumber | Alfanumérico | Opcional | Número de serie lógico del pinpad |
107 | pinpadFisSerialNumber | Alfanumérico | Opcional | Número de serie Físico del pinpad |
108 | useEncryptedData | Alfanumérico | Opcional | Indica si se utiliza encriptación entre Pinpad y Host Autorizador (Visa, Posnet, etc).
|
109 | pinpadResponseCode | Alfanumérico | Obligatorio | Código de Respuesta del Pinpad (CRE). |
111 | pinpadAutCode | Alfanumérico | Obligatorio | Código de Autorización (Z1 o Z3) del Pinpad (CAU). |
118 | terminalCapability | Numérico | Opcional | Capacidad de captura. Valores 1 = Manual / 2 = Lectura de Banda / 5 = Lectura de Chip |
137 | serviceCode | Numérico | Opcional | Código de Servicio, se envía cuando el mensaje esta encriptado (campo 108=true) y no se tiene acceso al Track2. Longitud 3. |
147 | providerPosCode | Alfanumérico | Opcional | Código del Provider. Se utiliza en los casos donde VTOL Server no puede obtener unívocamente el Proveedor utilizando los prefijos (debido enmascaramiento de la tarjeta). Ejemplo VI (Visa). Longitud 20. |
164 | posEncryptedFields | Numérico | Opcional | Indica si se utiliza encripción entre Pinpad y VTOL (modo RSA). En este caso los datos sensibles se envían encriptados. Si está activo, los campos a enviar encriptados son: 6, 8, 9, 66
|
201 | additionalMessageData | Alfanumérico | Opcional | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.8.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
24 | trxId | Numérico | OPCIONAL. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por VTOL. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 |
165 | publicKey | Alfanumérico | Clave Pública utilizada en la encripción punto a punto POS - VTOL. Viaja cuando la clave expiró y se generó una nueva; o bien, cuando es necesario sincronizar claves entre POS y VTOL. |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.9 SynQuery
Este es un mensaje de consulta de sincronización de llaves P2PE con los autorizadores.
Se envía a VTOL Server para obtener las claves de encripción 3DES para datos y PIN para cada autorizador que lo implemente.
1.4.9.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio | Identificación del nodo, en el sitio originador, donde se generó la transacción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
201 | additionalMessageData | Alfanumérico | Obligatorio | Mapa con los Ids de derivación por autorizador. Formato: [Autorizador1|IdDerivación1,Autorizador2|IdDerivación2,…,AutorizadorN|IdDerivaciónN] |
258 | forceSync | Alfanumérico | Opcional | Indica si se debe forzar la sincronización de llaves con el autorizador. Valores:
|
1.4.9.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador de la tienda donde se originó el mensaje |
2 | node | Numérico | Identificación del nodo |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 |
259 | workingKeys | Alfanumérico | Mapa con los datos de sincronización por canal. Formato: [Autorizador1|DatosSincronizacion1,Autorizador2| DatosSincronizacion2,…]
La información en el campo Datos Sincronización se encuentra codificado en base64. Ver sección Formato Datos Sincronización |
1.4.10 Cierre de Nodo
Por medio de éste mensaje se le puede indicar a VTOL que ejecute el cierre financiera de la terminal lógica asociada a la terminal física o nodo.
Existen dos modos, uno es indicarle a VTOL el identificar de definición de lote que se desea cerrar.
En este caso VTOL busca la terminal lógica (es una sola) asociada a:
- Numero de tienda indicado en el mensaje
- Numero de POS, nodo o terminal física indicado en el mensaje
- Identificador de definición de lote.
Para la terminal lógica encontrada se planificará el cierre.
La segunda modalidad se activa mediante la omisión del campo 75. En este caso VTOL busca todas las terminales lógicas asociadas a
- Numero de tienda indicado en el mensaje
- Numero de POS, nodo o terminal física indicado en el mensaje
Sin importar la definición de lote y planifica el cierre.
NOTA: el cierre no se ejecuta inmediatamente recibido el mensaje, sino que se planifica para que cuando VTOL esté en condiciones de cerrar lo haga.
1.4.10.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | SI | Identificador del sitio originador de la transacción |
2 | node | Numérico | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Compatibilidad atrás | Identificador del Server que procesará la transacción. ('VTOL') |
4 | messageType | Alfanumérico | Compatibilidad atrás. | Tipo de Mensaje:
|
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
71 | checkPendingString | Alfanumérico | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
75 | lotDefinition | numérico | Opcional | Identificador de definición de lote. Es requerido que el POS sepa de antemano cuales son los identificadores de defunción de lote y a que definición de lote pertenecen. |
201 | additionalMessageData | Alfanumérico | Opcional | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.10.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
24 | trxId | Numérico | OPCIONAL. En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta ISO-8583 |
201 | additionalMessageData | Alfanumérico | Este campo tiene como finalidad que el POS, o cliente VTOL, pueda enviar un dato X y que el mismo esté presente en la respuesta. Cada módulo según implementación puede decidir qué hacer con dicho dato (Ejem Persistir en BBDD). |
1.4.11 Echo
El propósito de este mensaje es conocer si VTOL se está ejecutando y se encuentra disponible.
Por lo general, se utiliza este mensaje en entornos de clúster donde existe un balanceador de carga.
1.4.11.1 Requerimiento
# | FieldId | Tipo | Obligatorio | Descripción |
11 | trxType | Alfanumérico | Obligatorio | Tipo de Transacción:
|
1.4.11.2 Respuesta
# | FieldId | Tipo | Descripción |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta con valor constante: "OK". |
1.4.12 Tercer Mensaje
1.4.12.1 Requerimiento
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Identificador del Server que procesará la transacción. (‘VTOL’) |
4 | messageType | Alfanumérico | Tipo de Mensaje:
|
11 | trxType | Alfanumérico | Tipo de Transacción:
|
19 | lastTrxAction | Alfanumérico | Acción a realizar sobre la Transacción:
|
24 | lastTrxId | Numérico | Id de transacción a confirmar / reversar. |
25 | dateTime | Numérico | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
200 | EMV extra data | Alfanumérico | Datos extras que se deben enviar en el tercer mensaje cuanto el EMV Advice es requerido.
Es necesario enviar los campos: adviceChipTokens, pinpadResponseCode y pinpadAutCode. Formato del campo: [adviceChipTokens|valor,pinpadResponseCode|valor, pinpadAutCode|valor] |
1.4.12.2 Respuesta
El tercer mensaje no tiene respuesta, salvo que esté prendido el flag de chequeo de transacciones pendientes.
1.4.13 Tercer Mensaje Embebido
El tercer mensaje puede enviarse embebido en otro requerimiento. Así en una misma transacción se enviará un requerimiento y la confirmación o reverso de una transacción pendiente. Para ello, deberán ser agregados los siguientes campos a la transacción en curso:
1.4.13.1 Requerimiento
# | FieldId | Tipo | Descripción |
19 | lastTrxAction | Alfanumérico | Acción a realizar sobre la Transacción:
|
24 | lastTrxId | Numérico | Id de transacción a confirmar / reversar. |
200 | EMV extra data | Alfanumérico | Datos extras que se deben enviar en el tercer mensaje cuanto el EMV Advice es requerido.
Es necesario enviar los campos: adviceChipTokens, pinpadResponseCode y pinpadAutCode.
Formato del campo: [adviceChipTokens|valor,pinpadResponseCode|valor, pinpadAutCode|valor] |
1.4.13.2 Respuesta
El tercer mensaje embebido, al igual que el Tercer Mensaje, no tiene respuesta. De todas formas, sí existe respuesta para la transacción que lo embebe.
1.4.14 Chequeo de Pendientes
El mensaje de chequeo de pendientes sirve para averiguar si el POS que envía la transacción tiene alguna transacción pendiente de confirmación.
1.4.14.1 Requerimiento
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Identificador del Server que procesará la transacción. (en el caso de VTOL será 'VTOL') |
4 | messageType | Alfanumérico | Tipo de Mensaje:
|
11 | trxType | Alfanumérico | Tipo de Transacción:
|
25 | dateTime | Numérico | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
1.4.14.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
24 | trxId | Numérico | OPCIONAL: En caso que el Campo 26 sea TrxIsPending, contendrá el trxId de la transacción pendiente. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta emitido por VTOL. OPCIONAL: Aparece si campo 26 no es TrxIsPending. |
28 | responseMessage | Alfanumérico | Mensaje de respuesta. Por ejemplo "Aprobada" |
31 | lotNumber | Numérico | Constante igual a 1 para mantener compatibilidad hacia atrás. |
32 | ticket | Numérico | Constante igual a 1 para mantener compatibilidad hacia atrás. |
Nota: si la respuesta es "aprobada" significa que no hay transacciones pendientes.
1.4.15 Chequeo de Listado de Pendientes
Este mensaje permite listar todos los id de las transacciones pendientes en VTOL que una tienda en particular, física o virtual, tiene.
1.4.15.1 Requerimiento
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Identificador del Server que procesará la transacción. (en el caso de VTOL será 'VTOL') |
4 | messageType | Alfanumérico | Tipo de Mensaje:
|
11 | trxType | Alfanumérico | Tipo de Transacción:
|
25 | dateTime | Numérico | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
1.4.15.2 Respuesta
# | FieldId | Tipo | Descripción |
1 | store | Alfanumérico | Identificador del sitio originador de la transacción |
2 | node | Numérico | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
25 | dateTime | Numérico | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alfanumérico | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | Código de Respuesta emitido por VTOL |
28 | responseMessage | Alfanumérico | Mensaje de respuesta. Por ejemplo "Aprobada" |
31 | lotNumber | Numérico | Constante igual a 1 para mantener compatibilidad hacia atrás. |
32 | ticket | Numérico | Constante igual a 1 para mantener compatibilidad hacia atrás. |
161 | trxIdList | Numérico | OPCIONAL: En caso que el campo 26 sea TrxIsPending contendrá la lista de transacciones pendientes. |
Nota: si la respuesta es "aprobada" significa que no hay transacciones pendientes.
1.5 Códigos de Respuesta al POS
La respuesta que el POS recibe de VTOL se encuentra en los siguientes campos:
- Campo 27: Código de Respuesta
- Campo 28: Descripción de la Respuesta
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 |
Nota: La respuesta con código '99' representa un error en el procesamiento interno de VTOL, independientemente de la interacción con el Centro Autorizador. Dicho error no debe ser manejado por el POS.
1.6 Código de errores del CORE
Es posible que VTOL responda "Error" en el campo 26 del mensaje de respuesta. Éste 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:
Dónde:
- Donde 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.
1.7 Formato Interface POS
A continuación se detalla la información que viaja en el campo ConfData y que se corresponde con la interface generada para el POS.
La versión de Formato de interface utilizada por Crédito Debito Argentina es la v101
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 |
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;;;
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. |
Ejemplo:
PP:AM;$;;0;1;98765432;101607;0000000000.00;0000000000.00;12.30;1
PP:VI;$;;0;10;98765432;101608;0000000100.00;0000000000.00;15.00;0
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
1.8 Formato Datos Sincronización
El formato es el siguiente:
Status;PinWorkingKey;PinWorkingKeyCtrl;dataWorkingkey;dataWorkingkeyCtrl
Donde:
- Status: código de estado de procesamiento de la consulta de sincronización de llaves para el autorizador en cuestión. Ver tabla códigos de estado.
- PinWorkingKey: llave de PIN
- PinWorkingKeyCtrl: información de control para llave de PIN
- dataWorkingkey: llave de DATOS
- dataWorkingkeyCtrl: información de control para llave de DATOS
Channel [POSNET] Decoded Sync Data [00;5b4940313332346231375b4940653030;6330;315b4940313336346235335b49403138;6236]
Channel [VISA] Decoded Sync Data [02]
1.8.1 Códigos de Estado
Código | Descripción |
00 | La sincronización con el autorizador se realizó con éxito y se obtuvieron llaves nuevas |
01 | No se realizó la sincronización con el autorizador debido a que el flag de sincronización forzada no fue enviado en TRUE y la terminal no estaba con estado de sincronización pendiente |
02 | La sincronización de llaves no está implementada para el autorizador |
03 | La respuesta a la sincronización de llaves no fue respondida en tiempo y forma por el autorizador |
1.9 Manejo de PIN
1.10 Flujo de datos EMV
1.10.1 Tercer Mensaje - Flujo Normal
El Advice hacia el autorizador es generado luego de recibir el tercer mensaje Commit desde el POS.
Pasos:
- En caso de que el campo requiredAdvice tenga valor true, el POS debe enviar en el tercer mensaje Commit, los campos chipTokens (criptograma del Advice) y pinpadResponseCode (código autorización del Pinpad).
Estos datos se incluyen el campo 200 –extraData-, con el siguiente formato:
Nota: Si el campo requiredAdvice no tiene valor true, se envía el tercer mensaje sin el campo de datos extras.
2. VTOL procesa el tercer mensaje registrando el código de respuesta del Pinpad (Aprobada o Rechazada) y genera el Advice a enviar hacia el autorizador incluyendo los datos recibidos en el Commit.
1.10.2 Tercer Mensaje - Pagos Parciales
Los pagos parciales son permitidos, siempre y cuando no sean para la misma terminal lógica. En VTOL se valida que si la terminal tiene estado AdvicePending, no se podrá realizar otra autorización antes de enviar el Advice.
El POS debe acumular los mensajes de Advice aprobados y rechazados por el Pinpad.
- En caso de que el POS finalice la transacción de POS:
- Hace Commit de todas las transacciones y se mandan los Advice
2. En caso de que el POS no finalice la transacción de POS, contingencia o anulación total, existen varias opciones que VTOL soportará. Será decisión del POS ver qué estrategia utilizar en base a cómo sea la certificación con VISA/POSNET:
- El POS hace Rollback de todas las autorizaciones:
- VTOL elimina el Advice pendiente de enviar y hace un Rollback de las autorizaciones
- El POS hace Rollback de las autorizaciones aprobadas por CA y el Pinpad, y Commit de autorizaciones aprobadas por CA y no aprobadas por el Pinpad
- VTOL elimina los Advice de las operaciones aprobadas por el CA y el Pinpad, y envía reversos; por otro lado, envía los Advice de las autorizaciones no aprobadas por el Pinpad.
- El POS hace Rollback de todas las autorizaciones:
1.11 Mecanismo en Tiendas Virtuales
Cuando se transacciona desde un POS no físico, como ser una tienda virtual, VTOL debe asignar automáticamente un número de nodo a la transacción.
Por lo que cuando se utiliza tiendas virtuales, en el requerimiento de los mensajes, no se deberá mencionar el nodo pero sí la tienda sobre la que se opera. VTOL al recibir una transacción asignará un nodo a dicha tienda. Este nodo deberá existir, estar libre para su uso y no tener transacciones pendientes.
VTOL tendrá definido un número de nodos por tienda y los manejará automáticamente. De cierto modo, esto limitará la cantidad máxima de transacciones en paralelo que la tienda soportará.