fci especificación tecnica para los h2h con el protocolo iso8583_v1.4.pdf

Copyright 2009 ® Fullcarga S.A.

Especificación tecnica para los clientes

H2H con el protocolo ISO8583

Documento: FCI Especificación tecnica para los H2H con el protocolo ISO8583_v1.4.docx 2/25 Fecha: 29/08/2011 v1.2/r1

Plataforma Fullcarga

Especificación técnica para los clientes H2H con el protocolo ISO8583

Autor: David Soria Ortiz

Departamento: Departamento de tecnología.

Fecha: 16 de abril de 2009

Asunto: Especificación técnica para los clientes H2H con el protocolo ISO8583

Versión: v1.2

Histórico: Ver. Fecha Autor Notas

1.0 16/04/2009 David Soria Ortiz

1.1 10/12/2009 Beatriz Brun Revisión

1.2 16/12/2009 David Soria Ortiz Códigos de error

1.3 30/05/2011 David Soria Ortiz

1.4 01/08/2011 David Soria Ortiz Se añaden los campos de respuesta para los productos internacionales


Índice

1. Introducción ........................................................ 4

2. Protocolo de comunicación ...................................... 5

2.2. Seguridad en los datos. ........................................... 6

2.3. Versión de protocolo .............................................. 7

3. Operaciones. ....................................................... 8

3.1. Operación Echo. .................................................. 11

3.2. Operación de venta .............................................. 12

3.3. Operación de Devolución ........................................ 17

3.4. Operación de Consulta ........................................... 19

3.5. Operación de consulta de saldo. ............................... 21

3.6. Respuesta Errónea ................................................ 23

4. Consulta en caso de operación demorada o fallo de comunicación 25


1. Introducción En este documento se describirá el comportamiento en cuanto a funcionalidades y protocolo de

comunicación que deben implementar los clientes H2H que se comuniquen con la plataforma

transaccional de Fullcarga.


2. Protocolo de comunicación El protocolo utilizado para la comunicación entre el cliente H2H y el Host de la plataforma transaccional

se basa en el protocolo ISO-8583.

Además del contenido de los campos ISO las tramas incluirán una cabecera que consta de:

� 2 Bytes en binario para la longitud de la trama (sin incluir los 2 bytes de este campo)

� 5 Bytes para el TPDU (El valor para los H2H será, 0x00, 0x00, 0x00, 0x00, 0x00 representado en

hexadecimal).

Por lo tanto las tablas quedarán como:

LEN (2 bytes) TPDU (5 bytes) DATA

2.1.1. Protocolo básico para las operaciones El protocolo básico de las operaciones constará de una petición realizada por el cliente H2H, y una

respuesta enviada por el HOST antes de un time-out de 60 segundos.

Tamaño de la tramas. Se ha definido un máximo de 1KB para el tamaño de las tramas.

Por lo que en caso de que una respuesta necesite más cantidad de información, será necesario dividir la

respuesta en varias tramas.

División de la respuesta en varias tramas.

Petición

Respuesta

TPV

Máx. 60 seg.

Host


En todas las operaciones en las que la información a enviar por parte del host de Fullcarga en la

respuesta sea superior a un 1KB será necesario enviar varias tramas.

Para ello el host de Fullcarga indicará en las tramas de respuesta que es necesario que el cliente H2H

espere más tramas. A cada trama de respuesta del host de Fullcarga le seguirá una nueva trama de

petición del cliente H2H siempre dentro de la misma conexión.

En este caso el time-out de espera del cliente H2H se volverá a contar desde 0 después de cada petición

enviada por el cliente H2H.

En la última trama a enviar el Host de Fullcarga indicará al cliente H2H que ya no es necesario que

espere más tramas, cerrando así la conexión.

En las tramas de respuesta en las que el host de Fullcarga indica que son necesarias más tramas el

campo PROCESS CODE (campo ISO nº 3) es xxxxx1 mientras que en las que el Host de Fullcarga indica

que ya no es necesario esperar más tramas el campo PROCESS CODE es xxxxx0.

2.2. Seguridad en los datos. Para proteger la información que se envía en las tramas el campo 60 (Privado, datos de la operación) se

enviaran de forma encriptada.

Petición

Respuesta

TPV

Máx. 60 seg.

Host

Petición

Respuesta Máx. 60 seg.

…

Petición

Respuesta Máx. 60 seg.


La encriptación utilizada será 3DES ECB. Debido al algoritmo 3DES es necesario que cada campo

encriptado se ajuste previamente a una longitud múltiplo de 8 bytes, para rellenar los campos hasta

dicha longitud se utilizaran tantos byte 0x00 como sean necesarios.

La clave se informará a cada cliente H2H mediante mail.

Además las tramas incluyen un campo password que se enviará encriptado, que se asignará a cada H2H,

para asegurar la identificación del cliente H2H.

Por otra parte también se validará la IP desde la que se conecta el H2H.

2.3. Versión de protocolo Para poder permitir posteriores cambios en el protocolo, se incluye en las tramas un identificador de

versión.

Cada vez que se realicen cambios que afecten a los campos de la tramas, se cambiará el número de

versión.

La versión actual del protocolo para H2H es “02”.


3. Operaciones. A continuación se describen las diferentes operaciones que debe implementar el cliente H2H, así como

las tramas de petición y respuesta correspondientes.

Tipos de datos de los campos Los campos del protocolo pueden ser de estos tipos:

� HEXA: Indica un campo binario en valor hexadecimal.

� BCD: Indica un número codificado en BCD.

� ASCII: Indica un campo alfanumérico de tamaño fijo codificado en ASCII.

� LLV: Indica un campo alfanumérico de tamaño variable codificado en ASCII. En este caso los 2

primeros Bytes indican la longitud del campo puesta en BCD.

� V: Indica un campo alfanumérico.

� LBCD: Indica un número codificado en BDC de longitud variable. El primer byte es la longitud.

Importes Tanto en las tramas de petición como en las tramas de respuesta de las operaciones se pueden incluir

diversos importes.

En cualquier caso un campo que contenga información de importe se incluirá sin separadores de miles ni

de decimales. De esta forma se asumirá que los últimos X dígitos del importe corresponden a los

decimales. El número de decimales a utilizar se informará por parte de Fullcarga al cliente H2H.

Campos comunes de petición Todas las tramas de petición tendrán una serie de campos comunes, que se describen a continuación:

Nº ISO

Campo Tipo Tamaño

(BYTES)

MESSAGE LENGHT HEXA 2

TPDU HEXA 5

TYPE BCD 2

BITMAP HEXA 8

03 PROCCES CODE BCD 3

11 STAN BCD 3

12 TIME (HHMMSS) BCD 3

13 DATE (MMDD) BCD 2

41 TERMINAL ID ASCII 8

62 PRIVATE (Campos de control)

Longitud del campo BCD 2


Versión del protocolo ASCII 2

Password (Encriptado) HEXA 8

TYPE Es en identificador ISO de tipo de operación.

PROCCES CODE Es el identificador que corresponde al tipo de operación que se esta ejecutando.

STAN Es el identificador correlativo de operación que tiene enviará el TPV en las peticiones. No es el

identificador que se utilizará como referencia del cliente H2H para la conciliación.

TIME y DATE Son los campos de hora y fecha. En la petición indicarán la hora del TPV y en la respuesta la hora del

Host.

TERMINAL ID Es el código de TPV asignado por la plataforma de Fullcarga.

VERSIÓN DE PROTOCOLO Indica la versión del protocolo de la plataforma de Fullcarga utilizada.

PASSWORD Es un password que se asignará a cada H2H.

Campos comunes de respuesta Las respuestas contendrán los mismos campos que se han enviado en la petición, además de los propios

campos de respuesta. Por lo tanto a los campos comunes de la petición se añaden los siguientes que

serán comunes a las respuestas:

Nº ISO

Campo Tipo Tamaño

(BYTES)

39 RESPONSE CODE ASCII 2

61 PRIVATE (Mensaje vendedor)

- Longitud del campo BCD 2

- Mensaje V


RESPONSE CODE Este campo indicará el código de respuesta. Si es 00 la respuesta será correcta, si es 01 indicará que la

operación se ha demorado, por lo que será necesario consultar el resultado mediante la operación de

consulta ver el capitulo 4 Consulta en caso de operación demorada . En cualquier otro caso se tomará la

operación como errónea. Tener en consideración estas transacciones como correctas hasta que las

defina la operadora a través de la consulta.

MENSAJE VENDEDOR En este campo se podrá incluir un mensaje para el H2H, o bien dejarlo vacío.


3.1. Operación Echo. Esta es una operación especial que se utiliza únicamente para testear la conectividad entre el H2H y el

Host.

Por lo tanto no se enviara el campo Termina ID (41).

El campo STAN no puede ser 00000000 por definición del protocolo ISO 8583, por lo que se enviará el

último valor utilizado en la operación anterior.

Si no se recibe respuesta al echo, no se deberán enviar transacciones de venta, devolución o consulta y

se seguirán aviando echos hasta recibir respuesta cada 2 minutos.

3.1.1. Trama de petición. La trama de petición tendrá estos campos.

Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0800) BCD 2

BITMAP HEXA 8

03 PROCCES CODE (990000) BCD 3

11 STAN BCD 3



3.1.2. Trama de respuesta. La trama de respuesta tendrá estos campos.

Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0810) BCD 2

BITMAP HEXA 8


11 STAN BCD 3



39 RESPONSE CODE (00) ASCII 2


3.2. Operación de venta A continuación la descripción de las tramas involucradas en la operación de venta.

3.2.1. Trama de petición. La trama de petición será la siguiente.

Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0200) BCD 2

BITMAP HEXA 8


11 STAN BCD 3




60 PRIVATE (Datos operación) (Encriptado) <= 900


- Código de producto ASCII 8

- Usuario ASCII 10

- REF H2H LLV

- Lista de parámetros

Número de parámetros HEXA 1

Valor del parámetro LLV





REF H2H Es la referencia que asigna el cliente H2H a la venta, y que se utilizará para la conciliación.


Usuario El usuario se enviará fijo de longitud 10 con espacios a la derecha si fuese necesario.

Lista de parámetros Para cada producto se definirán una lista de parámetros que se incluirán en la petición, ya que esta

información depende del tipo de producto, y de la información requerida por la operadora.

Esta información se envía adjunto en el anexo.



Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0210) BCD 2

BITMAP HEXA 8

03 PROCCES CODE (000100 ó 000101) BCD 3

04 AMOUNT TRANS BCD 6

06 AMOUNT DESTINO BCD 6

11 STAN BCD 3



37 REFERENCIA LOCAL ASCII 12



51 MONEDA DESTINO ASCII 3

48 PRIVATE (Referencia remota)


- Referencia V

60 PRIVATE (Datos operación) (Encriptado) <=900


Lista de Parámetros

- Número de Parámetros HEXA 1

- Valor de parámetro LLV



- Mensaje V


AMOUNT DESTINO Y MONEDA DESTINO Estos campos indicarán el importe y la moneda en el que se ha hecho la operación en el país de destino

del producto, en caso de que sea necesario informarlos.

Lista de parámetros Para cada producto se definirán una lista de parámetros que se incluirán en la respuesta, ya que esta

información depende del tipo de producto, y de la información requerida por la operadora.


AMOUNT TRANS Es el importe de la venta. Como todos los importes ira sin separador de miles ni decimales, por lo que

como decimales se tomaran tantos dígitos como se hayan definido.

REFERENCIA LOCAL (id de transacción de Fullcarga). Este campo se enviara rellenado de espacios en blanco a la izquierda del valor de la referencia. El H2H

deberá eliminar estos espacios al leer este valor tanto para mostrarlo en el ticket, como para registrar

la operación.

REFERENCIA REMOTA (id de transacción del operador). Este campo se enviara rellenado de espacios en blanco a la izquierda del valor de la referencia. El H2H

deberá eliminar estos espacios al leer este valor tanto para mostrarlo en el ticket, como para registrar

la operación.


3.3. Operación de Devolución A continuación la descripción de las tramas involucradas en la operación de devolución.


Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0200) BCD 2

BITMAP HEXA 8


11 STAN BCD 3







- Usuario ASCII 10

- REF H2H LLV

- Lista de parámetros







REF H2H Es la referencia que asigna el cliente H2H a la devolución, y que se utilizará para la conciliación.



Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0210) BCD 2

BITMAP HEXA 8


04 AMOUNT TRANS BCD 6

06 AMOUNT DESTINO BCD 6

11 STAN BCD 3






51 MONEDA DESTINO ASCII 3



- Referencia V








- Mensaje V


3.4. Operación de Consulta A continuación la descripción de las tramas involucradas en la operación de consulta.


Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0800) BCD 2

BITMAP HEXA 8


11 STAN BCD 3







- Usuario ASCII 10

- Lisa de parámetros









Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0810) BCD 2

BITMAP HEXA 8


11 STAN BCD 3








- Referencia V








- Mensaje V


3.5. Operación de consulta de saldo. Esta es la operación de consulta de saldo del cliente.

Como resultado de esta operación se devolverá el saldo del cliente H2H en el campo ISO 4 de la

respuesta.


Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0800) BCD 2

BITMAP HEXA 8


11 STAN BCD 3




62

PRIVATE (Campos de control)





3.5.2. Trama de respuesta. La trama de respuesta será la siguiente.

Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (0810) BCD 2

BITMAP HEXA 8


04 AMOUNT TRAS (SALDO) BCD 6

11 STAN BCD 3







- Mensaje V

AMOUNT TRANS (SALDO) Es el saldo del cliente H2H. Como todos los importes ira sin separador de miles ni decimales, por lo que

como decimales se tomaran tantos dígitos como se hayan definido.


3.6. Respuesta Errónea En caso de error en cualquier operación el Host enviará una trama indicando el error. Los campos de la

trama serán:

Nº ISO

Campo Tipo Tamaño

(BYTES)


TPDU HEXA 5

TYPE (XX10 según de la petición) BCD 2

BITMAP HEXA 8

03 PROCCES CODE (igual a la petición) BCD 3

11 STAN BCD 3




39 RESPONSE CODE (Distinto de 00 y de 01)

ASCII 2




- Referencia V

60 PRIVATE (Datos operación) <=900





En caso error, el campo RESPONDE CODE indicará sólo que la operación es errónea, la descripción del

error se incluirá en el primer parámetro de la Lista de parámetros del campo 60.

En esta respuesta no se enviará el campo 60 encriptado.

La plataforma de Fullcarga enviará dos tipos de mensajes de error dependiendo de si el error se ha

detectado en las validaciones de los datos o en la propia operación de la plataforma de Fullcarga, o bien

si el error es enviado por la propia operadora.

En caso de que el error sea enviado por la propia operadora el mensaje empezará siempre por

“NAKGW”.


La lista de los diferentes errores internos en la plataforma de Fullcarga es la siguiente:

Errores

HS0500 El sistema esta ocupado intentelo mas tarde

HS0502 El sistema esta ocupado intentelo mas tarde

HS0505 La operacion no se ha podido realizar

HS0506 Ha habido problemas con la operacion, consulte el estado de la misma

HS1000 El POS no esta activo o no existe

HS1001 La operacion no es valida

HS1002 El cliente no esta activo o no existe

HS1003 Operacion no esperada

HS1004 La version utilizada no es valida

HS1005 La diferencia horaria no permite la operacion

HS1006 El tipo de comunicacion no es valido

HS1008 El importe no es un valor permitido

HS1009 El importe esta fuera del rango minimo-maximo

HS1010 Error en la trama de confirmacion

HS1012 Error en la sincronizacion

HS1014 La referencia no existe

HS1021 El telefono es incorrecto

HS1026 El estado del producto no permite operar

HS1027 El producto no esta habilitado

HS1031 La trama es incorrecta

HS1032 El POS no tiene mensajes pendientes

HS1033 El tipo de aviso no es valido

HS1050 Los datos del cliente no son correctos

HS2002 No existen pines disponibles en este momento

HS3005 No dispone de saldo suficiente para operar

HS4003 La referencia de la venta no es valida

HS4005 Error en la validacion

HS4006 La venta todavia esta en proceso, consulte call center

HS4007 La venta esta anulada


4. Consulta en caso de operación demorada o fallo de comunicación En el caso de que en una operación de Venta ó Devolución no llegue al respuesta al cliente, o la

plataforma responda al cliente una respuesta con el campo RESPONSE CODE con valor ‘01’ (Operación

demorada), el cliente deberá enviar una petición de consulta (Ver apartado 3.4 Operación de Consulta)

utilizando el producto CONSULIVR, para consultar en qué estado se ha quedado la operación.

En el IVR la consulta ser realizará 2 veces antes de rechazar la venta.

Este producto tiene como único parámetro para la operación de consulta la referencia que el cliente ha

enviado en la venta en el campo REF IVR.

Los parámetros de respuesta incluidos en el campo 60 serán los siguientes:

1.- CODIGO DE PRODUCTO

Igual que en la petición

2.- RESULTADO

OK: Indicará que la operación es correcta. En este caso el campo 37 tendrá la referencia para

la operación de la plataforma Fullcarga.

KO: Indicará que la operación no ha sido correcta: bien porque no se ha recibido la petición;

bien porque ha habido algún fallo en las validaciones; bien porque la operadora ha indicado un error

para la operación o bien porque en el caso de una venta se haya podido anular.

PE: Indicará que la operación todavía sigue pendiente, por lo que se tendrá que seguir

consultando.

Si la operación ha pasado las validaciones previas en la plataforma de Fullcarga y se ha podido

registrar, el campo 37 también incluirá la referencia de la operación.

3.- INSTRUCCIONES

Incluirá un mensaje que indicará el motivo por el que la operación consultada no fue correcta.

4.- MSJ CLIENTE

Incluirá cualquier otro tipo de mensaje para el cliente.

fci especificación tecnica para los h2h con el protocolo iso8583_v1.4.pdf

Documents