VTOL CRÉDITO DÉBITO CENTROAMÉRICA
|
Napse establece un protocolo de comunicación para la interacción POS - VTOL, el cual se denomina "Protocolo VTOL" o "llavecitas". 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 Synthesis 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.
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 A101colocando el byte más significativo a la izquierda, con lo cual resulta: 101A.
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:
Mensaje Campo Valor Campo Valor
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.
Si se desea enviar el carácter especial punto y coma (;) en el valor e algún campo, será necesario escaparlo.
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 carácter ; y se muestra como escapar el mismo: {1:14\;56}
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:
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.
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:
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:
IMPORTANTE: La implementación del Tercer Mensaje y Mensajes de Control de Pendientes, dependerá del tipo de integración que se realiza en el Punto de Venta, y quedará a elección del cliente utilizar algunos, o todos los Mensajes descritos.
La mensajería entre el cliente y VTOL se compone por una serie de campos que tienen un determinado formato.
A continuación se muestra el formato que se utilizará para determinar la representación de cada campo.
El formato de cada campo puede tener los siguientes valores:
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)
En esta sección se detallarán las transacciones soportadas por VTOL así como los campos requeridos u opcionales de cada transacción.
# | FieldId | Formato | Requerido | Descripción | ||||||||||||||||||
1 | store | A10(V) | SI | Identificador del sitio originador de la transacción | ||||||||||||||||||
2 | node | N10(V) | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción | ||||||||||||||||||
3 | server | A4(F) | Compatibilidad atrás. | Constante VTOL | ||||||||||||||||||
4 | messageType | A4(F) | Compatibilidad atrás. | Constante Data | ||||||||||||||||||
6 | cardNumber | N19(V) | Obligatorio si es Manual | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. | ||||||||||||||||||
7 | expiration | N6(F) | Obligatorio si es Manual | Formato YYYYMM Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. | ||||||||||||||||||
9 | track2 | A200(V) | Obligatorio para todos los modos de ingreso excepto Manual | Track2 de la tarjeta. | ||||||||||||||||||
10 | posInputMode | A20(V) | Obligatorio | Modo de Ingreso:
Debe corresponder con el modo de ingreso que devuelve el PIN Pad en el campo entryMode
| ||||||||||||||||||
11 | trxType | A20(V) | Obligatorio | Tipo de Transacción:
| ||||||||||||||||||
12 | amount | N12(V) | Obligatorio | Monto de la transacción en centavos. Se envía sin coma. | ||||||||||||||||||
13 | currencyPosCode | A5(V) | Obligatorio | Tipos de Moneda:
| ||||||||||||||||||
14 | payments | N2(V) | Obligatorio | Cantidad de cuotas/parcialidades (meses). 2 dígitos como máximo. | ||||||||||||||||||
15 | plan | A1(F) | Obligatorio | Plan | ||||||||||||||||||
25 | dateTime | N14(F) | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss | ||||||||||||||||||
53 | paymentCondition | A3(V) | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. | ||||||||||||||||||
71 | checkPendingString | A5(V) | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas)
| ||||||||||||||||||
201 | additionalMessageData | A2000(V) | Opcional | Cuerpo del mensaje de la petición en formato JSON codificado en base 64 |
# | 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 emitido por el centro autorizador. 2 dígitos como máximo |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta |
29 | serialNumber | Numérico | Número 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. |
32 | ticket | Numérico | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
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". |
68 | rrn | Numérico | Número de referencia de la transacción informado por el centro autorizador |
102 | chipTokens | Alfanumérico | Issuer scripts que deben aplicarse a la tarjeta si la transacción utiliza EMV. |
126 | additionalRespData | Alfanumérico | Respuesta del canal en formato JSON codificada en base 64 |
161 | cardType | Alfanumérico | Tipo de tarjeta, según la configuración en VTOL:
|
166 | trxReferenceNumber | Numérico |
|
287 | systemTrace | Numérico | Número único de la transacción informado por el centro autorizador |
288 | giftMessage | Alfanumérico | Mensaje de premio regresado por el host en caso que el comercio afiliado tenga algún convenio para la entrega de premios o se requiera presentar algún mensaje adicional en el voucher. |
289 | acquirerTrxId | Alfanumérico | Identificación de la transacción en el banco de datos del adquiriente |
290 | taxDiscount | Numérico | Monto de devolución de impuesto. |
309 | cardBrand | Alfanumérico | Marca de tarjeta. Informado por Centro Autorizador |
# | FieldId | Formato | Requerido | Descripción | ||||||||||||||||||
1 | store | A10(V) | SI | Identificador del sitio originador de la transacción | ||||||||||||||||||
2 | node | N10(V) | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción | ||||||||||||||||||
3 | server | A4(F) | Compatibilidad atrás. | Constante VTOL | ||||||||||||||||||
4 | messageType | A4(F) | Compatibilidad atrás. | Constante Data | ||||||||||||||||||
6 | cardNumber | N19(V) | Obligatorio si es Manual | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. | ||||||||||||||||||
7 | expiration | N6(F) | Obligatorio si es Manual | Formato YYYYMM Fecha de vencimiento de la tarjeta. Sólo presente si el modo de ingreso fue Manual. | ||||||||||||||||||
8 | cvc | A4(V) | 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 | A200(V) | Obligatorio para todos los modos de ingreso excepto Manual | Track2 de la tarjeta. | ||||||||||||||||||
10 | posInputMode | A20(V) | Obligatorio | Modo de Ingreso:
| ||||||||||||||||||
11 | trxType | A20(V) | Obligatorio | Tipo de Transacción:
| ||||||||||||||||||
12 | amount | N12(V) | Obligatorio | Monto de la transacción en centavos. Se envía sin coma. | ||||||||||||||||||
13 | currencyPosCode | A5(V) | Obligatorio | Tipos de Moneda:
| ||||||||||||||||||
14 | payments | N2(V) | Obligatorio | Cantidad de cuotas/parcialidades (meses). 2 dígitos como máximo. | ||||||||||||||||||
15 | plan | A1(F) | Obligatorio | Plan | ||||||||||||||||||
16 | originalDate | N8(F) | Obligatorio | Fecha de la transacción original en el formato YYYYMMDD. | ||||||||||||||||||
17 | originalTrxTicketNr | N6(V) | Obligatorio | Número de ticket de la transacción original. Este valor fue informado al POS en el campo 32 de la venta y es único por cada caja | ||||||||||||||||||
25 | dateTime | N14(F) | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss | ||||||||||||||||||
53 | paymentCondition | A3(V) | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. | ||||||||||||||||||
66 | track1 | A100(V) | Opcional a su lectura | Criptograma obtenido de la lectura del track 1 de la tarjeta. | ||||||||||||||||||
71 | checkPendingString | A5(V) | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas)
| ||||||||||||||||||
139 | customerRef | A20(V) | Opcional | Número de referencia de comercio para trazabilidad. | ||||||||||||||||||
201 | additionalMessageData | A2000(V) | Opcional | Cuerpo del mensaje de la petición en formato JSON codificado en base 64 | ||||||||||||||||||
283 | keyLabel | N4(F) | Condicional | Etiqueta de la llave utilizada para encripción | ||||||||||||||||||
284 | keySerialNumber | A20(V) | Condicional | Key Serial Number. | ||||||||||||||||||
286 | encryptedTrack2 | A100(V) | Condicional a su lectura | Criptograma obtenido de la lectura del track 2 de la tarjeta. |
# | 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 emitido por el centro autorizador |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta |
29 | serialNumber | Numérico | Número 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. |
32 | ticket | Numérico | Número de Ticket correspondiente a la transacción. |
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". |
68 | rrn | Numérico | Número de referencia de la transacción informado por el centro autorizador |
161 | cardType | Alfanumérico | Tipo de tarjeta, según la configuración en 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. |
287 | systemTrace | Numérico | Número único de la transacción informado por el centro autorizador |
288 | giftMessage | Alfanumérico | Mensaje de premio regresado por el host en caso que el comercio afiliado tenga algún convenio para la entrega de premios o se requiera presentar algún mensaje adicional en el voucher. |
289 | acquirerTrxId | Alfanumérico | Identificación de la transacción en el banco de datos del adquiriente |
309 | cardBrand | Alfanumérico | Marca de tarjeta. Informado por Centro Autorizador |
# | FieldId | Formato | Requerido | Descripción | ||||||||||||||||||
1 | store | A10(V) | SI | Identificador del sitio originador de la transacción | ||||||||||||||||||
2 | node | N10(V) | SI | Identificación del nodo, en el sitio originador, donde se generó la transacción | ||||||||||||||||||
3 | server | A4(F) | Compatibilidad atrás. | Constante VTOL | ||||||||||||||||||
4 | messageType | A4(F) | Compatibilidad atrás. | Constante Data | ||||||||||||||||||
6 | cardNumber | N19(V) | Obligatorio si es Manual | Número de tarjeta. Sólo presente si el modo de ingreso fue Manual. | ||||||||||||||||||
9 | track2 | A200(V) | Obligatorio para todos los modos de ingreso excepto Manual | Track2 de la tarjeta. | ||||||||||||||||||
10 | posInputMode | A20(V) | Obligatorio | Modo de Ingreso:
Debe corresponder con el modo de ingreso que devuelve el PIN Pad en el campo entryMode
| ||||||||||||||||||
11 | trxType | A20(V) | Obligatorio | Tipo de Transacción:
| ||||||||||||||||||
12 | amount | N12(V) | Obligatorio | Monto de la transacción en centavos. Se envía sin coma. | ||||||||||||||||||
13 | currencyPosCode | A5(V) | Obligatorio | Tipos de Moneda:
| ||||||||||||||||||
14 | payments | N2(V) | Obligatorio | Cantidad de cuotas/parcialidades (meses). 2 dígitos como máximo. Debe ser el mismo valor que la venta original. | ||||||||||||||||||
15 | plan | A1(F) | Obligatorio | Plan. Debe ser el mismo valor que la venta original. | ||||||||||||||||||
16 | originalDate | N8(F) | Obligatorio si no se manda el campo 167 | Fecha de la transacción original en el formato YYYYMMDD. | ||||||||||||||||||
17 | originalTrxTicketNr | N6(V) | Obligatorio si no se manda el campo 167 | Número de ticket de la transacción original. Este valor fue informado al POS en el campo 32 de la venta y es único por cada caja | ||||||||||||||||||
25 | dateTime | N14(F) | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss | ||||||||||||||||||
53 | paymentCondition | A3(V) | Opcional | Condición de pago. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. | ||||||||||||||||||
71 | checkPendingString | A5(V) | Opcional, default = true | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas)
| ||||||||||||||||||
139 | customerRef | A20(V) | Opcional | Número de referencia de comercio para trazabilidad. | ||||||||||||||||||
167 | originalTrxReferenceNumber | N20(V) | Obligatorio si no se mandan los campos 16 y 17 | Número de referencia de la transacción original. Es el valor recibido en el campo 166 de la respuesta a la venta original. | ||||||||||||||||||
201 | additionalMessageData | A2000(V) | Opcional | Cuerpo del mensaje de la petición en formato JSON codificado en base 64 |
# | 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 emitido por el centro autorizador |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta |
29 | serialNumber | Numérico | Número 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. |
32 | ticket | Numérico | Número de Ticket correspondiente a la transacción. |
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". |
68 | rrn | Numérico | Número de referencia de la transacción informado por el centro autorizador |
161 | cardType | Alfanumérico | Tipo de tarjeta, según la configuración en 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. |
287 | systemTrace | Numérico | Número único de la transacción informado por el centro autorizador |
289 | acquirerTrxId | Alfanumérico | Identificación de la transacción en el banco de datos del adquiriente |
# | 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 | Constante VTOL |
4 | messageType | Alfanumérico | Constante Data |
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 |
El tercer mensaje no tiene respuesta, salvo que esté prendido el flag de chequeo de transacciones pendientes.
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:
# | 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. |
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.
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.
# | 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 eVTOL 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 |
# | FieldId | Tipo | Descripció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" |
Nota: si la respuesta es "Aprobada" significa que no hay transacciones pendientes.
# | FieldId | Tipo | Obligatorio | Description |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio si la tienda no es virtual | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Obligatorio | Valor constante 'VTOL' |
4 | messageType | Alfanumérico | Obligatorio | Valor constante Data |
11 | trxType | Alfanumérico | Obligatorio | Tipo de transacción:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la transacción en el POS. Formato YYYYMMDDHHmmss |
162 | storeFilter | Alfanumérico | Opcional | ID del originador del que se desea obtener la lista de transacciones pendientes. Si este campo no está presente se devolverá la lista de las transacciones pendientes para todos los originadores. |
163 | Threshold | Alfanumérico | Opcional; default=0 | Número de minutos hacia atrás que se ignoraran para buscar transacciones pendientes. |
169 | nodeFilter | Numérico | Opcional | Identificación de nodos, en el sitio originador, del que se desea obtener la lista de transacciones pendientes dado un rango de nodos. |
# | FieldId | Tipo | Descripción |
2 | node | Numeric | Identificación del nodo, en el sitio originador, donde se generó la transacción |
25 | dateTime | Numeric | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
26 | responseCode | Alphanumeric | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numeric | Código de Respuesta ISO-8583 emitido por el centro autorizador. 2 dígitos como máximo |
28 | responseMessage | Alphanumeric | Mensaje de la Respuesta ISO-8583 |
161 | trxIdList | Alphanumeric | Lista de transacciones pendientes de confirmación por el originador en el siguiente formato: [Store&Node&TrxIdList|Store&Node&TrxIdList|…] Donde:
Ejemplo: [0000000001&0000000006&4,2,3] Y para un originador virtual: [0000000006&V&13021512453900002321,13021512453600002320] |
# | FieldId | Tipo | Obligatorio | Descripción |
1 | store | Alfanumérico | Obligatorio | Identificador del sitio originador de la transacción |
2 | node | Numérico | Obligatorio si la tienda no es virtual | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | Obligatorio | Constante "VTOL" |
4 | messageType | Alfanumérico | Obligatorio | Constante: "Data" |
11 | trxType | Alfanumérico | Obligatorio | Tipo de transacción
|
19 | lastTrxAction | Alfanumérico | Obligatorio | Acción a realizar sobre las transacciones del campo 161:
|
25 | dateTime | Numérico | Obligatorio | Fecha de generación de la trx en el POS. Formato YYYYMMDDHHmmss |
161 | lastTrxIdList | Alfanumérico | Obligatorio | Lista de transacciones a confirmar/reversar para una tienda y nodo en el siguiente formato: [Store&Node&TrxIdList|Store&Node&TrxIdList|…] Donde:
|
Ejemplo:
{11:UnSyncCompletionList;1:1;2:1;25:20130511213613;19:Commit;3:VTOL;4:Data;161:[1&1&50,51,52|1&2&84,95|2&1&99,124]}
En este ejemplo, de acuerdo a los campos 19 y 161, VTOL tomará las siguientes acciones sobre las transacciones:
Store | Node | Transaction Id | Action |
1 | 1 | 50,51,52 | Commit |
1 | 2 | 84,95 | Commit |
2 | 1 | 99,124 | Commit |
Para el caso de un originador virtual:
{11:UnSyncCompletionList;1:1;2:1;25:20130511213613;19:Commit;3:VTOL;4:Data;161:[1&V&50000000000000000000,51000000000000000000,52000000000000000000,84000000000000000000,95000000000000000000|2&V&99000000000000000000,124000000000000000000]}
Store | Transaction Id | Action |
1 | 50000000000000000000,51000000000000000000,52000000000000000000, 84000000000000000000,95000000000000000000 | Commit |
2 | 99000000000000000000,124000000000000000000 | Commit |
El tercer mensaje en lista no tiene respuesta.
Este mensaje puede ser utilizado para monitorear que VTOL esté levantado. El propósito es saber si VTOL server está ejecutándose. No devuelve ninguna información adicional de salud de los canales, locales, etc.
# | FieldId | Tipo | Obligatorio | Description |
11 | trxType | Alfanumérico | Obligatorio | Tipo de transacción:
|
El contenido del mensaje de requerimiento a nivel bytes es el siguiente:
09 00 00 00 00 01 7b 31 31 3a 45 63 68 6f 7d
9 0 0 0 0 1 123 49 49 58 69 99 104 111 125
......{11:Echo}
*el punto "." representa caracteres no imprimibles
Los primeros 6 bytes del mensaje representan el header del protocolo llavecitas. Ver sección 1.1.1
# | FieldId | Tipo | Descripción |
25 | dateTime | Numeric | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. |
28 | responseMessage | Alfanumérico | Mensaje de la Respuesta valor constante: |
El contenido del mensaje de respuesta a nivel bytes es el siguiente:
19 00 00 00 00 00 7b 32 35 3a 32 30 31 36 31 31 30 39 31 33 34 33 30 36 3b 32 38 3a 4f 4b 7d 00
25 0 0 0 0 0 123 50 53 58 50 48 49 54 49 49 48 57 49 51 52 52 50 51 59 50 56 58 79 75 125
......{25:20161109134306;28:OK}
*el punto "." representa caracteres no imprimibles
Los primeros 6 bytes del mensaje representan el header del protocolo llavecitas.
La respuesta que el POS recibe de VTOL se encuentra en los siguientes campos:
A continuación se detallan las respuestas posibles con una breve descripción de cada una:
Únicamente el mensaje 00-APROBADA es totalmente satisfactorio.
Si se recibe el mensaje 08-ACEPTE CON IDENTIFICACIÓN la transacción ha sido aprobada pero se debe pedir la identificación al cliente. En caso de que se encuentre algo sospechoso en la identificación se debe anular la transacción desde el sistema.
Código | Descripción |
00 | Aprobada |
01 | Consulte verbal |
02 | Consulte verbal |
03 | Comercio inválido |
04 | Capture tarjeta |
05 | Denegada |
08 | Acepte con identificación |
09 | Aceptado |
10 | Aceptado por '$x.xx' |
12 | Transacción inválida |
13 | Cantidad inválida |
14 | Tarjeta inválida |
19 | Reintente transacción |
21 | Sin transacciones |
25 | Reintente TR NT |
41 | Retener tarjeta |
43 | Retener tarjeta |
51 | Denegada FI |
54 | Tarjeta vencida |
57 | Transacción no permitida |
58 | Transacción no permitida |
60 | Denegada |
61 | Denegada |
62 | Denegada |
63 | Denegada |
75 | Denegada |
78 | Tran. No encontrado |
79 | Lote ya abierto |
80 | Error en número de lote |
85 | Lote no existe |
89 | Terminal inválido |
94 | Transacción duplicada |
95 | Espere transmisión |
96 | Error en sistema |
Código de seguridad inválido | |
Error de comunicación | |
Reintente cierre | |
Monto inválido | |
Terminal inválida | |
Tipo de mensaje inválido | |
Sistema no disponible | |
Reintente transacción TO | |
Reintente transacción ND | |
Transacción inválida | |
Reintente to REM | |
Trans. ya procesada | |
Error en lectura de track | |
Error acceso a BD | |
Error interno del WS | |
Usuario inválido | |
Rechazado por sistema de recarga | |
Sistema de recarga no disponible | |
Número de teléfono inválido | |
Denegado por coinca | |
Billetera no existe | |
OTP Vencido | |
OTP Inválido | |
Moneda inválida | |
OTP Cancelado | |
OTP Expirado | |
Fondos insuficientes | |
Sup. Limite billetera | |
Monto no autorizado | |
No acepta anulación | |
'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 | |
Terjeta 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 | |
Campo emvFullGradeIcc Inválido | |
Error script | |
Error criptograma | |
Error cardSequenceNumber | |
Check-in no confirmado |
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.
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:
El mensaje de respuesta tiene siempre el siguiente formato:
Dónde: